spawn_agent
Deploy an autonomous AI agent to clone a GitHub repo, implement changes, run tests, create a pull request, and merge it, handling the full development workflow from start to finish.
Instructions
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
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| goal | No | LoopJob: verifiable intent — what 'done' looks like. Required when completion_criteria is set. Injected into the quality eval agent prompt. | |
| task | Yes | Task description to pass to Claude Code. A workflow preamble is auto-injected before this task. | |
| model | No | Model override for this job (e.g. 'claude-sonnet-4-5'). Defaults to CC_AGENT_DEFAULT_MODEL env var or 'claude-sonnet-4-5'. | |
| branch | No | Existing remote branch to checkout after cloning. Only pass this for branches that already exist on the remote. DO NOT pass a new branch name here — it will cause clone failure ('fatal: Remote branch not found'). New branches must be created by the agent via git checkout -b inside the task. | |
| chat_id | No | Discord/Telegram chat ID to include in the completion notification payload. When set, cc-discord routes the notification back to the originating channel. | |
| repo_url | Yes | Git repository URL to clone (https or ssh) | |
| fast_mode | No | If true, inject /fast at session start to enable fast mode (faster output, same model). Default: false. | |
| depends_on | No | Job IDs that must be done before this job starts. Job will be queued as pending until all dependencies complete. | |
| session_id | No | Session ID to resume from a previous job (use sessionIdAfter from a prior job). Passes --continue to Claude CLI. | |
| smoke_test | No | Shell command to run as a cheap pre-check before the full task. If it exits non-zero or times out, the job fails immediately. Example: 'npm test -- --testPathPattern=smoke 2>&1 | tail -5' | |
| agent_model | No | Model override for the selected driver (e.g. 'qwen2.5-72b-instruct', 'kimi-k2', 'gpt-4o'). Optional. | |
| no_preamble | No | If true, no preamble is injected — the raw task is passed directly to the agent. Overrides custom_preamble. | |
| ollama_host | No | Ollama host URL (default: 'http://localhost:11434'). Only used when ollama_model is set. | |
| agent_driver | No | Which agent driver to use. One of: claude (default), aider, openai, qwen, kimi, deepseek, pi, gemini, amp, codex. Defaults to 'claude' (Claude Code). gemini requires GEMINI_API_KEY, amp requires AMP_API_KEY, codex requires OPENAI_API_KEY. | |
| claude_token | No | Claude OAuth token or Anthropic API key to use for this job (optional — falls back to server env) | |
| effort_level | No | Token spend strategy. Maps to Claude Code's /effort command injected at session start. 'low' = minimal tokens, fast and cheap. 'high'/'xhigh'/'max' = more thorough, higher cost. 'auto' = let the model decide. Default: unset (Claude Code default). | |
| ollama_model | No | If set, route Claude Code through Ollama using this model name (e.g. 'nemotron-3-nano', 'deepseek-r1:7b'). Sets ANTHROPIC_BASE_URL, ANTHROPIC_API_KEY=ollama, and CLAUDE_MODEL env vars. | |
| create_branch | No | ALWAYS false. The agent creates its own branch with git checkout -b. Setting this to a branch name will cause a clone failure because the branch does not exist on remote yet. | |
| max_budget_usd | No | Maximum USD budget for this Claude Code session (optional, default 20) | |
| max_iterations | No | LoopJob: maximum number of worker iterations before declaring loop_exhausted. Default 3. Hard cap 3. | |
| openai_api_key | No | API key override for OpenAI-compatible drivers. Falls back to OPENAI_API_KEY / driver-specific env var. | |
| quality_rubric | No | LoopJob: rubric injected into the quality eval agent. Describes what good output looks like. If omitted, quality gate is skipped. | |
| custom_preamble | No | Custom workflow preamble to inject before the task. If set, replaces the default cc-agent workflow preamble entirely. Use no_preamble to remove the preamble completely. | |
| openai_base_url | No | Base URL for OpenAI-compatible API endpoint. Only used when agent_driver is openai/qwen/kimi/deepseek/pi. | |
| timeout_minutes | No | Wall-clock timeout in minutes per active run. Job is terminated (SIGTERM then SIGKILL) if it exceeds this limit. Set to 0 to disable. Default: 120 (2 hours). | |
| continue_session | No | Pass --continue to Claude Code to resume the most recent session in the repo directory (optional, default false) | |
| docker_isolation | No | Run agent in Docker container for isolation. Default: false. Requires Docker to be running. On macOS, Docker runs in a VM — use only when isolation is specifically needed. | |
| smoke_test_timeout | No | Timeout for the smoke test in seconds (default 60). Only used when smoke_test is set. | |
| spawning_namespace | No | Namespace of the caller (e.g. 'simorgh-mobile-app'). When set, job completion notifications are routed to cca:notify:{spawning_namespace} instead of the server's default namespace. Use this when spawning from a meta-agent so the completion signal returns to your namespace. | |
| completion_criteria | No | LoopJob: list of shell commands run after the worker finishes. Each command runs in the cloned repo directory. All must exit 0 for the completion gate to pass. Presence of this field opts the job into the loop engine. |