Autonomous Mode

Autonomous mode lets an AI agent (Claude Code, Codex, or OpenCode) work end-to-end on a task — analyzing the codebase, planning, writing code, running tests, and creating a PR — all without step-by-step human oversight.

When to Use Autonomous Mode

Enabling Autonomous Mode

Set the execution mode on a project's autonomy configuration:

# Via API
curl -X PATCH http://localhost:8000/api/projects/my-project \
  -H "Content-Type: application/json" \
  -d '{
    "autonomy_config": {
      "execution_mode": "autonomous",
      "plan_approval": "none"
    }
  }'

Or configure it in the Project Settings → Autonomy panel in the web UI.

Execution Modes

Plan Approval

Control how much oversight the agent gets:

Episodic Execution

For complex tasks that may exceed a single agent session, enable episodic execution. The agent works in bounded episodes with git checkpoints between each.

{
  "autonomy_config": {
    "execution_mode": "autonomous",
    "episode_config": {
      "max_episodes": 5,
      "max_turns_per_episode": 30,
      "stall_timeout_seconds": 600
    }
  }
}

How Episodes Work

1. Episode starts — Agent launches with --max-turns limit
2. Agent works — Code, test, commit in bounded session
3. Episode ends — Max turns reached, task completed, or context exhausted
4. Git checkpoint — All work committed as WIP
5. Context compacted — Summary of accomplished work built
6. Next episode — Agent resumes with context summary

Episode 1: Analyze codebase, write initial implementation
    → git checkpoint (abc1234)
    → context summary: "Created auth middleware, 3 endpoints"

Episode 2: Continue with tests and edge cases
    → git checkpoint (def5678)
    → context summary: "Added 15 tests, fixed login flow"

Episode 3: Final review and cleanup
    → task complete → PR created

Session Recovery

If an agent session crashes, the SSH connection drops, or the server restarts:

1. Worker engine detects the interrupted run on startup
2. Finds the last episode with a git checkpoint
3. Builds a context summary from the episode's stream log
4. Launches a new episode that picks up where the previous one left off

No manual intervention needed — the task continues automatically.

Stall Detection

If the agent produces no output for the configured timeout (default: 10 minutes), the platform:

1. Detects the stall via stream-json monitoring
2. Kills the stuck process
3. Creates a context summary
4. Starts a new episode to retry

Budget and Safety Controls

Set per-project limits to prevent runaway costs:

{
  "max_budget_usd": 10.00,
  "max_turns_per_episode": 30,
  "max_episodes": 5,
  "max_total_duration_seconds": 7200,
  "stall_timeout_seconds": 600,
  "max_files_changed": 50
}

If any limit is exceeded, the agent is stopped and the run is marked accordingly.

Monitoring Autonomous Runs

Episode Timeline

The run detail page shows a live episode timeline:

• Current episode number and status
• Turn count per episode
• Context window usage meter
• Git checkpoint SHAs

Live Agent Stream

An SSE endpoint streams real-time agent activity:

GET /api/runs/{run_id}/agent-stream

Remote Control

While an agent is running autonomously, you can:

• Send a message — Redirect the agent's focus
• Pause — Send interrupt signal
• Resume — Continue execution

# Send instruction to running agent
curl -X POST /api/runs/123/agent/message \
  -d '{"message": "Focus on the authentication tests first"}'

# Pause the agent
curl -X POST /api/runs/123/agent/pause

# Resume
curl -X POST /api/runs/123/agent/resume

Example Workflow

# 1. Create a project
curl -X POST /api/projects -d '{
  "project_id": "my-app",
  "repo_url": "https://github.com/org/my-app",
  "git_provider": "github",
  "autonomy_config": {
    "execution_mode": "autonomous",
    "episode_config": {
      "max_episodes": 5,
      "max_turns_per_episode": 30
    }
  }
}'

# 2. Create a task
curl -X POST /api/runs -d '{
  "project_id": "my-app",
  "title": "Add user authentication",
  "description": "Implement JWT auth with login/register endpoints, password hashing, middleware, and full test coverage"
}'

# 3. Monitor (or just wait for the PR)
curl /api/runs/1/episodes

# 4. Approve the PR when ready
curl -X POST /api/runs/1/approve

Configuration Reference

autonomy_config Fields

episode_config Fields