convez.ai
MCP Server
Gonzih

cc-agent

Gonzih/cc-agent

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server for spawning Claude Code agents in cloned repos — branch your agents

Instalação

$npx convez-ai Gonzih/cc-agent

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
1
Contribuidores
2

README

A tradução para o português deste README ainda está na fila.

cc-agent

npm version

Distill and delegate.

MCP server for spawning Claude Code agents in GitHub repos. Give Claude Code the ability to branch itself — clone a repo and kick off a sub-agent to work on it autonomously, with persistent state across MCP restarts.

Built by @Gonzih.

Quickstart

claude mcp add cc-agent -- npx @gonzih/cc-agent

Set one of:

CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...   # OAuth token (recommended)
ANTHROPIC_API_KEY=sk-ant-api03-...         # API key

Restart Claude Code. You now have 13 new MCP tools.

MCP Tools

ToolDescription
spawn_agentClone a repo, optionally create a branch, run Claude Code on a task
get_job_statusCheck status of a specific job
get_job_outputStream output lines from a job (supports offset for tailing)
list_jobsList all jobs with status, recent tool calls, and exit info
cancel_jobKill a running job
send_messageWrite a message to a running agent's stdin mid-task
cost_summaryTotal USD cost across all jobs, broken down by repo
get_versionReturn the running cc-agent version
create_planSpawn a dependency graph of agent jobs in one call
generate_workflowAuto-decompose a natural language goal into ordered stages and spawn all agents with stage-based dependency enforcement
get_workflow_statusPoll the status of a workflow created by generate_workflow, with per-stage and per-step breakdown
get_wikiReturn all wiki pages for a repo — structured knowledge auto-injected into every spawn_agent call
get_wiki_pageReturn a single wiki page by name for a repo
update_wiki_pageCreate or update a wiki page (markdown) for a repo
delete_wiki_pageDelete a single wiki page for a repo
list_wiki_pagesList all wiki page names for a repo
create_profileSave a named spawn config for repeated use with {{variable}} templates
list_profilesList all saved profiles
delete_profileDelete a named profile
spawn_from_profileSpawn a job from a saved profile with variable interpolation

spawn_agent parameters

ParameterTypeRequiredDescription
repo_urlstringyesGit repo to clone (HTTPS or SSH)
taskstringyesTask prompt for Claude Code
branchstringnoExisting branch to check out after clone
create_branchstringnoNew branch to create (e.g. feat/my-feature)
claude_tokenstringnoPer-job token override
continue_sessionbooleannoPass --continue to resume last Claude session in workdir
max_budget_usdnumbernoSpend cap in USD (default: 20)
session_idstringnoSession ID from a prior job's sessionIdAfter — resumes that session
depends_onstring[]noJob IDs that must be done before this job starts (queued as pending)
effort_levelstringnoToken spend strategy: low | medium | high | xhigh | max | auto. Injects /effort <level> at session start.
fast_modebooleannoIf true, inject /fast at session start (faster output, same model). Default: false.

create_plan parameters

ParameterTypeRequiredDescription
goalstringyesHigh-level description of what this plan achieves
stepsarrayyesOrdered list of steps to execute

Each step in steps:

FieldTypeRequiredDescription
idstringyesLogical step ID (used for depends_on references within the plan)
repo_urlstringyesGit repo to clone
taskstringyesTask prompt for Claude Code
create_branchstringnoNew branch to create before running
depends_onstring[]noStep IDs from this plan that must complete first
effort_levelstringnoToken spend strategy for this step (low | medium | high | xhigh | max | auto).
fast_modebooleannoIf true, inject /fast at session start for this step.

create_profile parameters

ParameterTypeRequiredDescription
namestringyesProfile name (alphanumeric, dashes, underscores)
repo_urlstringyesGit repo to clone
task_templatestringyesTask template — use {{varName}} for substitution
default_budget_usdnumbernoDefault USD budget for jobs from this profile
branchstringnoBranch to check out after cloning
descriptionstringnoHuman-readable profile description
effort_levelstringnoDefault effort level for all jobs spawned from this profile.
fast_modebooleannoIf true, enable fast mode by default for jobs from this profile.

spawn_from_profile parameters

ParameterTypeRequiredDescription
profile_namestringyesName of the saved profile to use
varsobjectnoVariables to interpolate into the task template
task_overridestringnoUse this task instead of the profile template
branch_overridestringnoOverride the profile's branch
budget_overridenumbernoOverride the profile's default budget
effort_levelstringnoOverride the profile's default effort level for this spawn.
fast_modebooleannoOverride the profile's fast mode setting for this spawn.

Usage examples

Basic agent

spawn_agent({
  repo_url: "https://github.com/yourorg/yourrepo",
  task: "Add error handling to all API endpoints. Open a PR when done.",
  create_branch: "feat/error-handling",
  max_budget_usd: 5
})
// → { job_id: "abc-123", status: "started" }

list_jobs()
// → [{ id: "abc-123", status: "running", recentTools: ["Read", "Edit", "Bash", ...] }]

get_job_output({ job_id: "abc-123", offset: 0 })
// → { lines: ["[cc-agent] Cloning...", "Reading src/api.ts...", ...], done: false }

send_message({ job_id: "abc-123", message: "Also update the tests." })
// → { sent: true }

cost_summary()
// → { totalJobs: 1, totalCostUsd: 1.23, byRepo: { "https://github.com/...": 1.23 } }

Multi-step plan with dependencies

create_plan({
  goal: "Refactor auth and update docs",
  steps: [
    {
      id: "refactor",
      repo_url: "https://github.com/yourorg/app",
      task: "Refactor auth middleware to use JWT. Open a PR.",
      create_branch: "feat/jwt-auth"
    },
    {
      id: "docs",
      repo_url: "https://github.com/yourorg/app",
      task: "Update README to document the new JWT auth flow.",
      create_branch: "docs/jwt-auth",
      depends_on: ["refactor"]
    }
  ]
})
// → { goal: "...", totalSteps: 2, steps: [{ stepId: "refactor", jobId: "abc-1", status: "cloning" }, { stepId: "docs", jobId: "abc-2", status: "pending" }] }

Profiles for repeated tasks

// Save once:
create_profile({
  name: "fix-issue",
  repo_url: "https://github.com/yourorg/app",
  task_template: "Fix issue #{{issue}}: {{title}}. Open a PR when done.",
  default_budget_usd: 5
})

// Use many times:
spawn_from_profile({
  profile_name: "fix-issue",
  vars: { issue: "42", title: "Login broken on mobile" }
})

Resume a prior session

// Get session ID from a completed job:
get_job_status({ job_id: "abc-123" })
// → { ..., session_id_after: "ses_xyz" }

// Resume it:
spawn_agent({
  repo_url: "https://github.com/yourorg/app",
  task: "Continue where you left off — finish the tests.",
  session_id: "ses_xyz"
})

Persistence

cc-agent v0.3.0+ stores all job state in Redis, which is auto-provisioned on startup — zero configuration needed.

Auto-provisioning

On startup, cc-agent tries to connect to Redis at localhost:6379. If unavailable:

  1. Docker — runs docker run -d --name cc-agent-redis -p 6379:6379 --restart=unless-stopped redis:alpine
  2. redis-server — if redis-server is on PATH, spawns it as a daemon
  3. In-memory fallback — logs a warning and continues; jobs are not persisted across restarts

Once Redis is available, all job state, output, profiles, and plans survive MCP server restarts and are shared across all Claude Code sessions pointing at the same Redis instance.

Key schema

KeyTypeTTLContents
cca:job:<id>String (JSON)7 daysFull job record
cca:jobs:indexList—Job IDs, newest first (capped at 500)
cca:job:<id>:outputList7 daysOutput lines (one entry per line)
cca:plan:<id>String (JSON)30 daysPlan record with step→job mapping
cca:profile:<name>String (JSON)permanentProfile config
cca:profiles:indexSetpermanentAll profile names

Disk fallback

When Redis is unavailable, cc-agent falls back to the original disk-based storage:

  • .cc-agent/jobs.json — job metadata
  • .cc-agent/jobs/<id>.log — per-job output log
  • ~/.cc-agent/profiles.json — profiles

Existing disk profiles are automatically migrated to Redis on first startup with Redis available.

Job statuses

StatusMeaning
pendingWaiting for depends_on jobs to complete
cloningCloning the repo
runningClaude Code is running
doneCompleted successfully
failedExited with an error (check error field)
cancelledCancelled by cancel_job

Tool call visibility

list_jobs returns recentTools — the last 10 tool names Claude called per job (e.g. ["Read", "Edit", "Bash", "Glob"]). get_job_output returns the full tool_calls array. This gives insight into what agents are actually doing during silent periods.

Budget control

Set max_budget_usd per job to cap spend. Default is $20. Claude Code is killed with SIGTERM when the budget is exhausted (exit code 143).

spawn_agent({ ..., max_budget_usd: 10 })  // up to $10 for this task
spawn_agent({ ..., max_budget_usd: 2  })  // quick/cheap task

Agent delegation pattern

The recommended mental model: you are the tech lead, agents are your team.

  • Spawn agents for any task touching a codebase (multiple files, running tests, opening PRs)
  • Do research, quick edits, and orchestration yourself
  • Always end agent prompts with the terminal steps: gh pr create → gh pr merge → npm publish (or whatever ships the work)
  • Monitor with list_jobs + get_job_output, respawn if budget runs out
# Standard agent task prompt ending:
gh pr create --title "feat: ..." --body "..." --base main
gh pr merge --squash --auto
npm version patch && npm publish   # if it's a library

MCP config (claude.json)

{
  "cc-agent": {
    "command": "npx",
    "args": ["@gonzih/cc-agent"],
    "env": {
      "CLAUDE_CODE_OAUTH_TOKEN": "sk-ant-oat01-..."
    }
  }
}

How it works

  1. spawn_agent creates a job record (persisted to disk) and returns immediately with a job ID
  2. In background: git clone --depth 1 <repo> into a temp dir
  3. Optionally checks out an existing branch or creates a new one
  4. Runs claude --print --output-format stream-json --verbose --dangerously-skip-permissions --max-budget-usd <N> <task>
  5. Streams stdout/stderr into the job's output log (in memory + disk)
  6. Tool calls are captured from the stream-JSON and stored in tool_calls[]
  7. On exit: job marked done/failed, workdir cleaned up after 10 minutes
  8. Jobs expire from memory after 1 hour (log file remains on disk)
  9. Pending jobs are promoted automatically every 3 seconds when their dependencies complete

Environment variables

VariableDescription
CLAUDE_CODE_TOKENClaude OAuth token or Anthropic API key
CLAUDE_CODE_OAUTH_TOKENClaude OAuth token (alternative)
ANTHROPIC_API_KEYAnthropic API key (alternative)

Requirements

  • Node.js 18+
  • claude CLI: npm install -g @anthropic-ai/claude-code
  • Git

Related

Ver o original no GitHub

Bom para

Relacionados