Autonomous Agent

The Autonomous Agent takes a GitHub milestone (or individual issue) and works through each issue automatically — creating branches, writing code, running quality checks, and opening pull requests.

How It Works

1. Pick a milestone — Select a GitHub repo and one or more open milestones
2. Review the estimate — See per-issue cost estimates before committing
3. Create the job — The agent queues each issue in dependency order
4. Execute — The agent processes issues one at a time inside a sandboxed container
5. Review results — Each issue produces a PR with quality gate results

You (dashboard) --> Create Job --> Agent picks up Issue #1
                                    |
                                    +--> Creates branch
                                    +--> Writes code
                                    +--> Runs checks (typecheck, lint, test, build)
                                    +--> Opens PR
                                    +--> Moves to Issue #2 ...

Getting Started

Prerequisites

• A project with a linked GitHub repository
• Issues organized under a GitHub milestone
• Issues formatted with the Agent Issue Specification for best results

Step 1: Open the Jobs Dashboard

Navigate to your project, then click Autonomous Agent in the sidebar (or go to /app/project/:id/jobs).

Step 2: Select a Milestone

1. Choose the GitHub repo (auto-populated if your project has a linked repo)
2. Select one or more open milestones
3. Click Estimate Cost to see a breakdown before committing

Step 3: Configure Options

Option	Default	What it does
Auto-merge PRs	Off	Merge PRs automatically when all quality gates pass
Security scan	On	Run npm audit before committing
Deploy on complete	Off	Trigger a staging deploy after the last issue finishes
Pause per issue	Off	Pause after each issue so you can review before continuing

Set budget limits to control maximum spend:

• Cost limit (USD) — the agent pauses when 80% consumed, stops at 100%
• Token limit — hard cap on total LLM tokens used

Step 4: Create and Execute

Click Create Job to queue the work. Then click Execute to start processing.

Monitoring a Job

Real-Time Dashboard

While a job runs you see:

• Progress bar — issues completed vs. total
• Budget tracker — tokens used, compute time, estimated cost
• Per-issue table with:
  • Current stage (planning, building, testing, committing)
  • Quality gates (TypeScript, lint, tests, build, security)
  • Duration and token usage
  • PR link when created

Updates stream in real time via server-sent events (SSE).

Job Statuses

Status	Meaning
Queued	Created but not yet started
Running	Actively processing issues
Paused	Stopped at a budget threshold or by user request
Completed	All issues processed
Failed	Stopped due to an error or budget exceeded
Cancelled	Manually cancelled by user

Issue Stages

Each issue within a job moves through:

Queued —> Running —> Planning —> Building —> Testing —> Committing —> Done

If a step fails the agent retries up to 3 times with a targeted fix prompt before marking the issue as Failed.

Budget and Cost

How Cost Is Calculated

Component	Rate
LLM input tokens	1 credit / 1,000 tokens
LLM output tokens	4 credits / 1,000 tokens
Container compute	1 credit / minute

A 25% safety margin is applied to all estimates.

Budget Enforcement

• At 80% of your limit the job pauses automatically
• At 100% the job stops
• You can resume a paused job and optionally raise the limits

Complexity Tiers

The estimator classifies each issue into a tier based on its body, labels, and scope:

Tier	Typical Work	Token Range	Compute
Trivial	Typo fix, config change	5k-15k	1-3 min
Small	Bug fix, simple feature	15k-40k	3-8 min
Medium	Feature with tests	40k-100k	8-20 min
Large	Multi-file refactor	100k-250k	20-45 min
Epic	Major system change	250k-500k	45-90 min

Quality Gates

Every issue runs through up to five checks:

1. TypeScript — tsc --noEmit
2. Lint — eslint
3. Tests — npm test
4. Build — npm run build
5. Security — npm audit (when enabled)

Results appear as pass/fail icons on each issue row. If a gate fails, the agent attempts a self-healing retry.

Writing Good Issues

The agent works best with well-structured issues. Include:

• What — clear description of the change
• Why — motivation and context
• Requirements — specific acceptance criteria
• Technical Specification — files to create/modify, integration points
• Scope Constraints — complexity tier, line estimate

See the Agent Issue Specification for the full template.

Pause, Resume, and Cancel

• Pause — stops after the current issue finishes; no work is lost
• Resume — continues from where it left off; you can raise budget limits
• Cancel — marks remaining issues as skipped; completed PRs are kept

FAQ

Can I run multiple jobs at once? One job runs at a time per project. You can queue additional jobs.

What happens if my budget runs out? The job pauses automatically. You can increase the limit and resume.

Does auto-merge bypass code review? Auto-merge only triggers when all quality gates pass. You can disable it to review every PR manually.

Can I use this on a repo without milestones? Yes — create a single-issue job instead of a milestone job.