Your First Project

After signing in, you land on the project selection screen. If you are already inside a project, click your project name in the sidebar header to return to the project switcher. Click New Project.

Provide the following information:

• Project name- A human-readable name for your project, e.g., “E-commerce Backend” or “Design System”
• GitHub repository URL - (Optional) The HTTPS URL of the repository you want agents to work on, e.g., https://github.com/your-org/your-repo. This enables automatic branch creation and PR generation.

The project slug is generated automatically from the name. For example, “E-commerce Backend” becomes e-commerce-backend. This slug is used in all project URLs.

Click Create Project. CodeCourier creates the project record, sets you as the owner, initializes project settings with defaults, and redirects you to the project dashboard. The dashboard initially shows zeroed counters for sandboxes, runs, workflows, and members.

Click New Context and select the issuesession type. Write the system prompt that the issue-scanning agent should receive, including your project’s priorities, areas of concern, and any patterns it should look for:

You are scanning a TypeScript/Next.js codebase for issues.
Focus on:
- Type safety violations and implicit any usage
- Missing error boundaries and unhandled promise rejections
- N+1 query patterns in data fetching
- Accessibility regressions in UI components
- Missing or inadequate test coverage

Prioritize issues that would affect production stability.
Generate specific, actionable titles and descriptions.

Save the context. CodeCourier creates version 1 of this document and associates it with issue sessions in your project.

Create another context for the learning session type. This context instructs the learning-extraction agent how to identify and categorize learnings from completed runs:

You are extracting learnings from an AI agent's completed coding session.
Focus on:
- Mistakes the agent made that were corrected
- Project-specific patterns or conventions that emerged
- Tool usage gotchas specific to this codebase
- Architectural decisions with rationale

Categorize each learning as: preference, pattern, gotcha, tool, or architecture.
Only extract learnings that would be actionable in future sessions.

Repeat for any other session types you use: merging, answering, evaluating, and judging. Each context type is independent; you can add them as you introduce each capability into your workflow.

Click New Skill. Give the skill a name (e.g., “Project Conventions”) and add one or more files. Each file has a name and content:

# Project Conventions

## TypeScript
- All files must use strict mode
- Never use `any` - use `unknown` and narrow it
- Prefer interface over type for object shapes

## Database (Convex)
- Never call .collect() on large tables
- Use paginate() for lists longer than 100 items
- Batch writes use ctx.scheduler.runAfter

## Testing
- All new functions need a Vitest unit test
- Integration tests go in __tests__/integration/
- Use MSW for HTTP mocking, never mock fetch directly

Save the skill. It is now available to attach to personas and session configurations.

Create commands for your most common agent operations. For example:

• Name: run-tests - Expression: npx vitest run --reporter=verbose
• Name: typecheck - Expression: npx tsc --noEmit
• Name: lint - Expression: npx eslint . --ext .ts,.tsx

Commands give agents stable, project-specific aliases that remain consistent even if your tooling configuration changes.

Scripts are optional but useful for pre-run or post-run automation. For example, a pre-run script might clone the repository to a known state, or a post-run script might run a final lint pass and commit any auto-fixed issues.

Navigate to Issue Session in Project Settings. Here you can:

• Bind a context - Select the issue context you created earlier. This context document will be injected automatically into every issue scanning session.
• Select skills- Choose which skill packages are available in issue sessions. Your “Project Conventions” skill is a good default selection.
• Select commands - Add yourrun-tests and typecheck commands so the scanning agent can validate its findings.
• Set the issue session prompt- An additional free-text prompt prepended to the user’s discovery prompt.

Open the Learning Session configuration tab. Bind your learning context document and select any skills or commands relevant to learning extraction. The learning agent will use these resources when analyzing completed sessions.

Repeat the binding process for Merge, Answering, Evaluator, and Judge sessions as you adopt those capabilities. Each session type is fully independent - you can configure them incrementally as your workflow matures.

Click Members in the sidebar under the Insights section. This page shows all current members and pending invitations.

Click Invite Member. Enter the email address of the person you want to invite and select their role:

• Admin - Can manage all project resources and settings, invite other members
• Member - Can create and manage their own sandboxes, runs, and workflows

The invitation is created immediately. The invited person will see a pending invitation when they sign into CodeCourier. Once they accept, their status changes from “pending” to “accepted” and they gain access to all project resources according to their role.

From the members page you can change a member’s role or remove them from the project. The project owner cannot be removed but can transfer ownership by making another member the owner.

Click Personas in the sidebar. This page shows all personas configured for the project.

Click New Persona and configure it:

• Name: “Senior Developer”
• Type: Designer
• Model: Choose your preferred model (e.g., claude-sonnet-4-6 for speed or claude-opus-4-6 for quality)
• Thinking effort: Medium or High
• Instructions:

You are a senior full-stack developer. Follow these principles:
- Write clean, well-documented TypeScript code
- Prefer composition over inheritance
- Write tests for all new functions
- Use existing project patterns and conventions
- Keep changes focused and minimal

• Skills: Select your “Project Conventions” skill and any other relevant skills
• Commands: Enable run-tests, typecheck, and lint
• Learnings: Enable to include project learnings in context

Create a second persona for code review:

• Name: “Code Reviewer”
• Type: Checker
• Model: Use a strong model for reviewing ( claude-opus-4-6 recommended)
• Thinking effort: High
• Instructions:

You are a thorough code reviewer. Evaluate the changes against:
- Correctness: Does the code do what was asked?
- Type safety: Are there any TypeScript errors or any-typed values?
- Edge cases: Are error states and boundary conditions handled?
- Testing: Are tests present and meaningful?
- Style: Does the code follow project conventions?

Return pass: true only if ALL criteria are met.
If rejecting, provide specific, actionable feedback.

Consider creating additional personas for specific roles:

• Investigator - For research tasks that explore codebases before making changes
• Planner - For issue sessions and codebase analysis with specific architectural principles
• Reviewer - Focused on readability, maintainability, and code review thoroughness
• Deep-dive - For in-depth analysis tasks requiring extended reasoning

Navigate to Sandboxes in the sidebar and click New Sandbox. Configure the sandbox template, timeout, and resources. Give it a descriptive name like “Explore codebase” and provide an initial prompt.

Standalone sandboxes are useful for one-off tasks: investigating a bug, prototyping a solution, or testing a configuration change before encoding it in a workflow.

Once the sandbox is running, you can view the agent’s message stream in real time. The detail page shows the full conversation history, sandbox status, and any PR or learning extraction status.

Navigate to Workflows and create a new Persona Pipeline workflow:

• Name: “Full Review Pipeline”
• Type: Persona Pipeline
• Steps: Add your “Senior Developer” persona as the first step, then your “Code Reviewer” persona as the second step. Optionally configure a loop between them with a max iteration count.
• Template: Select the sandbox template matching your CLI tool preference
• Timeout: 30 minutes per step

Click Run on your new workflow. Enter a prompt describing the feature or fix you want:

Add a reusable DateRangePicker component to
components/ui/date-range-picker.tsx. It should:

1. Accept startDate, endDate, and onChange props
2. Use the existing react-day-picker dependency
3. Support both controlled and uncontrolled modes
4. Include proper TypeScript types
5. Follow the existing shadcn/ui component patterns
6. Add a Storybook story file

Specify a branch name (e.g., feat/date-range-picker) and confirm the GitHub repository URL if needed. Click Start Run.

Watch the run progress from the run detail page:

1. The designer persona receives your prompt, explores the repository, and implements the feature
2. The checker persona reviews the implementation against your criteria and either approves or provides feedback
3. If rejected, the designer iterates with the feedback until approval or the max iteration count is reached
4. Quality scores are recorded for each step - you can see correctness, type safety, code style, test coverage, and completeness scores in the step details
5. On completion, CodeCourier creates a PR on the specified branch

Navigate to Issues in the sidebar and click New Issue Session. Select the branch you want to analyze and provide a discovery prompt (or rely on the context document you configured earlier). Start the session.

The session will use the Issue Session context and assets you configured in Project Settings. When it completes, you will see a list of generated issues with titles, descriptions, and priorities.

Some issues may come with open questions or unresolved assumptions - for example, “Is this cache miss acceptable, or should we pre-warm the cache?” When you see such questions attached to an issue, click Start Answering Session.

The Answering Session creates a sandbox using your configured Answering Session context. The agent receives the open questions and works through them, producing structured answers that are attached back to the issue. These answers are then passed to the implementation run so the designer agent does not need to guess.

With questions resolved, click Runon an issue (or select multiple issues and create a work chain). The implementation run receives the issue’s suggested prompt plus any answers from the Answering Session.