Quickstart

Navigate to the CodeCourier application and sign in with your preferred method. CodeCourier uses Clerk for authentication, so you can sign in with Google, GitHub, email, or any other configured OAuth provider.

After signing in for the first time, CodeCourier creates your user record and redirects you to the project selection screen. If you have been invited to an existing project, you will see it listed with a pending invitation badge.

Click New Project on the project selection screen. Enter a name for your project - this will auto-generate a URL slug. Optionally, provide your GitHub repository URL now (you can also add it later in project settings).

Once created, CodeCourier sets you as the project owner and redirects you to the project dashboard. The sidebar organizes your workspace into sections: Issues (issue sessions and work chains), Runs (all workflow and sandbox runs), Workflows, Personas, Learnings, and Insights (usage, analytics, and members). Sandboxes are accessible through individual run detail pages.

Navigate to Project Settings from the sidebar (the wrench icon at the bottom). Open the API Keys tab. You need to configure at least two providers:

1. E2B - Required. This is used to provision cloud sandboxes. Get your key from the E2B dashboard at e2b.dev/dashboard.
2. Anthropic / OpenRouter / OpenAI - At least one is required. This powers the AI model that runs inside your sandboxes. Choose whichever provider matches the CLI tool you want to use (Anthropic for Claude Code, OpenRouter or OpenAI for broader model access).
3. GitHub - Optional but recommended. A personal access token with repo scope enables CodeCourier to create branches and pull requests automatically.

API keys are encrypted at rest and stored per-project. Each team member can see only the last four characters of configured keys. Keys are decrypted server-side only when a Trigger.dev job needs to provision a sandbox.

Navigate to Workflows in the sidebar. Click New Workflow to open the creation dialog. For your first workflow, start with the Designer & Checker type:

• Name: Give it a descriptive name, e.g., “Feature Builder”
• Type: Select Designer & Checker
• Template: Choose the sandbox template for your preferred CLI tool (e.g., claude-code for Claude Code)
• Max Iterations: Set to 3 for a balanced quality/cost trade-off
• Timeout: 30 minutes (1,800,000 ms) is a good starting point
• Checker Instructions: Describe what the checker should verify, e.g., “Verify the implementation follows TypeScript best practices, has no type errors, and includes appropriate error handling.”

Click Create. Your workflow blueprint is now saved and ready to run.

From the workflows page, click the Run button on your new workflow. This opens the run dialog where you configure the specific execution:

• Prompt: Write a clear, specific instruction for the AI agent. For example:

Add a new utility function to lib/utils.ts that formats
a number as a human-readable file size (e.g., 1024 becomes
"1 KB", 1048576 becomes "1 MB"). Include JSDoc comments
and handle edge cases like 0 and negative numbers.
Write a test file at lib/__tests__/utils.test.ts.

• GitHub Repo URL: Enter your repository URL if not already set at the project level
• Branch Name: Optionally specify a branch name, or let CodeCourier generate one

Click Start Run. CodeCourier dispatches a background job through Trigger.dev that:

1. Provisions an E2B sandbox with your configured template
2. Installs and starts the AI CLI tool inside the sandbox
3. Sends your prompt along with any bound context document and approved project learnings
4. Waits for the designer to complete, then runs the checker with your review instructions
5. If the checker rejects, sends feedback back to the designer for another iteration
6. Records quality scores for each step (correctness, type safety, code style, test coverage, completeness)
7. On completion, optionally creates a PR and extracts learnings

Navigate to Runs in the sidebar to see your active run. Click on the run to open its detail view. You will see:

• Run status: pending, running, completed, or failed
• Step timeline: Each designer and checker step is shown with its status, start time, and duration
• Live messages: The conversation between the platform and the AI agent streams in real time, including the agent’s thought process and tool calls
• Checker verdicts: If using a designer/checker workflow, each checker step shows a pass/fail verdict with feedback
• Quality scores: Completed steps show their quality score breakdown - visible in the step details panel

When the run completes, check the following:

• PR status: If GitHub integration is configured and the run was set to create a PR, you will see the PR URL and status (creating, created, merged, or failed) directly on the run detail page. CI check results will appear as your pipeline runs against the PR branch.
• Quality scores: The run summary shows the overall quality score. Expand individual steps to see dimension-level scores and identify areas for improvement in your prompts or persona configurations.
• Learnings: Navigate to the Learnings section. If learning extraction was enabled, you will see new pending learnings extracted from the session. Review each one and approve or reject it - approved learnings will be included in future runs automatically.
• Cost tracking: Visit Usage in the insights section to see token consumption and cost breakdown for the run.