Issue Sessions

An issue session is an AI-powered scanning process that analyzes your codebase and automatically discovers problems, bugs, improvements, and tasks. The session runs inside a cloud sandbox, giving the AI agent full access to your repository code, and produces a structured JSON list of issues that are imported into CodeCourier for tracking and resolution. In addition to issues, sessions generate questions and assumptions - structured artifacts that capture what the agent was uncertain about during scanning and what it assumed in the absence of explicit guidance.

What is an Issue Session?

Think of an issue session as an automated code review with a specific focus. You provide a discovery prompt - for example, “scan for security vulnerabilities and performance issues” - and CodeCourier provisions a sandbox, clones your repository, and runs an AI agent that investigates the codebase according to your instructions. The agent outputs its findings as a structured list of issues, each with a title, description, priority, and suggested fix. It also records questions it could not answer from the codebase alone, and the assumptions it made when proceeding without answers.

Configuring the Issue Agent

Before starting a session, you configure the Issue Agent from the Issues Setup page at /p/{projectId}/issues-setup. This configuration is applied to all issue sessions in the project. The setup page lets you specify:

Starting a Session

To start an issue session, navigate to the Issues page and click New Session. You need to provide:

1. Discovery Prompt (required) - Instructions for the AI agent describing what to look for. Be as specific as possible for better results.
2. Sandbox Configuration (optional) - Override default sandbox settings including template, memory, CPU count, and timeout.

Example discovery prompts:

# Security-focused scan
"Analyze the codebase for security vulnerabilities including XSS, SQL injection,
authentication bypasses, and insecure defaults. Focus on API routes and user input handling."

# Performance scan
"Identify performance bottlenecks, memory leaks, N+1 queries, unnecessary re-renders,
and large bundle size contributors."

# General code quality
"Find bugs, error handling gaps, untested edge cases, and code that doesn't follow
the project's established patterns and conventions."

# Architecture review
"Identify architectural inconsistencies, missing abstractions, leaky abstractions,
and components that have grown beyond a single responsibility."

Session Lifecycle

Every issue session progresses through a series of phases:

1. Initiation

When you submit the session, CodeCourier validates your authentication and API keys, creates a session record in active status, and dispatches a Trigger.dev background task to handle the scanning work.

2. Sandbox Execution

The background task provisions an E2B sandbox with your project’s environment configuration. If a GitHub repository URL is configured, the repository is cloned into the sandbox. The AI agent then executes with your discovery prompt, analyzing files, tracing code paths, and identifying issues. The agent writes its findings to /home/user/issues.json and its questions to /home/user/questions.json inside the sandbox.

Session progress is tracked via two counters on the session record:

• currentIteration- The agent’s current iteration count, updated in real time as the session progresses. This reflects how many scanning passes or reasoning cycles the agent has completed.
• maxIterations - The configured upper bound on iterations. Once currentIteration reaches maxIterations, the agent wraps up and writes its final output. Increasing this limit allows for deeper, more thorough scanning at the cost of additional runtime and tokens.

3. Issue Extraction

When the session completes (or is manually killed), CodeCourier reads the issues.json output from the sandbox. The extraction parser handles multiple JSON formats:

• Wrapped arrays: { "issues": [...] } or { "results": [...] }
• Direct arrays: [{ "title": "...", "description": "..." }, ...]
• Alternative field names: name mapped to title, goal mapped to description
• Partial JSON with fallback regex extraction for malformed output

4. Questions & Assumptions Extraction

In addition to issues, the session extracts questions and assumptions from questions.json. These are stored in the session record’s questionsJson and assumptionsJson fields. Each question captures what the agent was uncertain about, and each assumption captures how the agent proceeded in the absence of an explicit answer.

These questions and assumptions form the input to an optional Answering Session that runs after the Issue Session completes.

5. Issue Record Creation

Each extracted issue is validated (title and description must be present) and created as an individual issue record linked to the session. Priority is normalized to one of the four supported levels, defaulting to medium if not specified or unrecognized. All issues start with status new.

The session also dispatches learnings and triggers any review hooks configured for the project, allowing the Judge and Evaluator roles to participate in session evaluation before issues are acted upon.

Session Statuses

Configuring Session Parameters

When starting a session, you can customize the sandbox configuration:

Starting an Answering Session

Once an Issue Session completes and questions/assumptions have been extracted, you can optionally start an Answering Session directly from the Issue Session detail page. Click the Start Answering Session button to launch the flow.

The Answering Session uses a separate Answering Agent (configured in the answering-setup page) to review the questions and produce refined, actionable assumptions. You then review each assumption individually - approving, declining, or correcting them. Approved assumptions are stored as structured context that can be injected into workflow runs when executing the resulting issues.

See the Answering Sessions documentation for a complete walkthrough of this flow.

Running Individual Issues

Once issues are extracted from a session (or created manually), you can run each one individually:

1. Click Run Issue on the issue card
2. Select a workflow blueprint to use for execution
3. Optionally configure a GitHub repository URL and branch name
4. Submit to launch the workflow run

The run uses the issue’s suggestedPrompt if available, falling back to the description as the prompt. When an Answering Session has been completed for this Issue Session, the approved assumptions are available as additional context for the run. The issue status changes to runningand is automatically synced with the run’s outcome.

Managing Sessions

From the session list, you can:

• Rename - Give the session a descriptive name
• Kill - Terminate an active session (partial results are salvaged)
• Archive - Move completed sessions out of the active list
• Delete - Soft-delete a session
• Bulk delete - Delete multiple sessions at once
• Start Answering Session - Launch an Answering Session for a completed session that has questions/assumptions

Next Steps