Spawn a Claude Code agent on a GitHub repository.

WORKFLOW: agent clones repo → creates its own branch → implements → tests → commits → pushes → opens PR → merges PR → publishes.

IMPORTANT: Always set create_branch: false. The agent creates its own branch internally with git checkout -b. Setting create_branch: true will cause a clone failure because the branch doesn't exist on remote yet.

BRANCH PARAM WARNING: Only pass branch for already-existing remote branches (e.g. to resume work on a branch that was previously pushed). For new branches, omit branch entirely — include git checkout -b <name> in the task steps instead. Passing a branch that does not exist on the remote will cause an immediate clone failure ('fatal: Remote branch not found').

Parameters:

• repo_url: GitHub repo URL (https://github.com/owner/repo)

• task: Full task description. A workflow preamble is auto-injected before your task.

• create_branch: ALWAYS false. The agent manages its own branch.

• branch: Existing remote branch to checkout (see BRANCH PARAM WARNING above)

• claude_token: Optional Claude API token override

Get the current status of a spawned agent job. For waiting until completion, prefer wait_for_job (zero-poll) or subscribe to the Redis pub/sub channel cca:job:done:{job_id} for instant notification.

Block until a job reaches a terminal state (done/failed/cancelled/rejected/interrupted) or the timeout expires. Returns the final status and score. Preferred over polling get_job_status in a loop. For non-MCP coordinators: subscribe to Redis pub/sub channel cca:job:done:{job_id} for instant zero-copy notification — the payload is JSON with fields: job_id, status, score, score_source, finished_at, exit_code.

Get output lines from a running or finished job. Use offset to paginate.

List all agent jobs (running, done, failed, cancelled). To wait for a specific job, use wait_for_job or subscribe to cca:job:done:{job_id} on Redis.

Cancel a running agent job.

Send a message to a running agent's stdin. Use this to give the agent corrections, new information, or updated instructions mid-task.

Returns total USD cost across all jobs, broken down by repo.

Returns the running cc-agent MCP server version.

Save a named spawn config (profile) for repeated use. Task templates support {{variable}} substitution.

// Create once: // create_profile('fix-bugs', 'https://github.com/me/app', 'Fix {{issue}}: {{title}}', 5) // Use many times: // spawn_from_profile('fix-bugs', { issue: '42', title: 'Login broken' })

List all saved named job profiles, including built-in profiles. Call this before spawn_from_profile to discover what profiles are available.

Delete a named job profile.

Spawn a full dependency graph of agent jobs in one call. Each step can declare depends_on referencing other step IDs in this plan. Returns a summary with actual job IDs mapped to step IDs.

Return the last N lines of the cc-agent log file (~/.cc-agent/logs/cc-agent.log). Default 100, max 500.

Manually wake a sleeping job immediately, bypassing its scheduled wake time.

Returns the content of ~/.cc-agent/model-ratings.jsonl as a structured JSON array. Used to monitor which open models (routed via Ollama) are performing well. Rating and notes fields are null until filled in by the operator.

List GitHub issues for a repository using the gh CLI.

Fetch a GitHub issue, post a pickup comment, and spawn a cc-agent to work on it.

Post a comment on a GitHub issue.

Close a GitHub issue, optionally posting a comment.

Approve a job that is pending approval due to an untrusted repo owner. Transitions the job from pending_approval to running.

Set a quality score (0.0–1.0) on a completed job. Used by evaluator agents in evolutionary branching plans to record how well each variant performed.

Return accumulated learnings for a repo or namespace. Learnings are written by agents at the end of each job. Use this to understand what prior agents have discovered.

Clear all stored learnings for a namespace. Useful when starting fresh on a refactored codebase.

Return all wiki pages for a repo. Wiki pages are structured knowledge injected automatically into every spawn_agent call for the repo. Use this to inspect what knowledge is stored.

Return a single wiki page by name for a repo.

Create or update a wiki page for a repo. Content is markdown. Pages are auto-injected into spawn_agent calls for this repo.

Delete a single wiki page for a repo.

List all wiki page names for a repo.

List currently running cc-agent Docker containers. Shows container name, status, and uptime.

List the status of all configured OAuth tokens (CLAUDE_TOKENS env var). Shows which token is currently active and how many are configured. Useful for diagnosing token rotation issues.

Spawn an agent job from a saved profile. Supports variable interpolation and per-call overrides. Call list_profiles first to see available profiles. Built-in profiles: coder, fix-issue, implement-feature, write-tests, security-audit, refactor, review-pr, bump-deps. Use the 'coder' profile for general coding tasks — it injects Karpathy discipline guidelines.

List all scheduled cron jobs for the current namespace.

Create a new cron job that fires on a recurring interval and spawns an agent.

Delete a cron job by ID.

Update fields on an existing cron job.

Return the last 20 notification messages sent by the coordinator for the current namespace.

List all active namespaces/repos with job counts and recent activity. Each namespace = one project column in the UI.

Debug: show all active Redis pub/sub channels and subscriber counts. Use to diagnose chat sync issues.

List all available agent drivers and their status (binary found / API key configured). Use this to check which drivers are ready to use before calling spawn_agent with agent_driver.

Export all job records as JSONL or JSON for statistical analysis. Each record includes id, status, repo_url, task (truncated to 500 chars), started_at, finished_at, exit_code, output_lines count, score, and duration_seconds. Use this to pull job traces, compute success rates, and study failure modes.

Longitudinal cost breakdown for research budget tracking. Returns grouped cost summary with total USD spent, job count, avg cost per job, and avg score. Useful for tracking spending by repo, day, or outcome.

Find jobs by content of task prompt. Returns matching jobs with a task snippet showing match context. Useful for finding all jobs that involved a specific tool, repo, or task type.

Auto-decompose a high-level goal into N parallel sub-tasks, fan out agents across all of them, then run a synthesis agent that produces one unified deliverable. Returns immediately with swarm_id and sub_job_ids. Use get_swarm_status to poll progress.

Poll the status of a swarm created by swarm_task. Returns goal, status (running_subs | synthesizing | done | failed), sub_job counts, and synthesis_job_id once spawned.

Auto-decompose a high-level goal into an ordered sequence of stages, then spawn all jobs with stage-based dependency enforcement. Returns immediately with workflow_id, job_ids, and the stage breakdown. Use get_workflow_status to poll progress. Each stage only starts after ALL jobs in the prior stage complete — guaranteeing ordered execution even across 100s of agents.

Poll the status of a workflow created by generate_workflow. Returns goal, stage breakdown, per-step job IDs and statuses.