Meta Harness Design

Claude Code as Autonomous Agent Infrastructure

The Core Idea

Claude Code (the claude CLI) is not just a coding assistant. It is a general-purpose intelligence substrate that can be wrapped, orchestrated, and composed into autonomous infrastructure. The meta harness is the architecture for doing that at production scale — persistent, self-healing, multi-agent, zero-credential.

The harness turns a local development tool into an always-on autonomous workforce.

Architecture Overview

launchd (KeepAlive: true)
  └── cc-tg  ← coordinator / Telegram bridge
        └── Claude Code (--continue, project context)
              └── cc-agent MCP  ← worker spawner
                    └── claude subprocess  ← ephemeral task agent
                          └── more subagents...

Three tiers. Each tier has a distinct responsibility.

Tier 1 — The Coordinator (cc-tg)

What it is: A Node.js process managed by launchd with KeepAlive: true. It bridges Telegram messages to a persistent Claude Code session running --continue in the target project directory.

What it does:

Receives messages from a Telegram bot
Routes them to a persistent claude --continue subprocess
Flushes Claude's responses back to Telegram and Redis
Stays alive forever — launchd respawns it on crash

Why this matters: The coordinator holds the project context. It runs with cwd=/Users/feral/money-brain so it picks up all project-scoped MCP configs, CLAUDE.md instructions, and memory. The context is stateful — it carries the conversation across days.

Restart rule: Never launchctl unload. Kill with pkill — launchd respawns cleanly with --prefer-online, pulling the latest package.

Tier 2 — The Worker Spawner (cc-agent)

What it is: An MCP server that exposes tool calls to the coordinator's Claude session. The coordinator uses it to spawn, monitor, and retrieve results from autonomous work agents.

Protocol:

spawn_agent(repo_url, task, create_branch, branch, claude_token)
  → job_id

list_jobs() → [{job_id, status, repo, branch}]

get_job_output(job_id) → stdout/stderr log

cancel_job(job_id) → bool (false for interrupted jobs — use Redis SET)

Job lifecycle:

PENDING → RUNNING → COMPLETED
                 ↘ FAILED
                 ↘ INTERRUPTED (use Redis SET to cancel)

The branch rule: Every agent task runs on a branch. Never main. Pattern: feat/, fix/, mvp/. Nothing is done until the full cycle completes: implement → test → commit → push → PR → merge → publish/deploy.

Tier 3 — Task Agents (ephemeral subagents)

What they are: Isolated Claude Code sessions spawned into a fresh worktree of the target repo. Each gets a task prompt and runs to completion.

What they do:

Clone the repo, create the branch
Implement the task (code, tests, config)
Run tests, fix failures
Commit, push, open a PR via gh pr create
Optionally: npm publish, cargo publish, git tag, service restart

Prompt contract: Every agent prompt ends with terminal steps:

gh pr create --title "<title>" --body "<what and why>" --base main
gh pr merge --squash --auto
npm version patch && npm publish --access public

Agents that don't ship are not done.

Communication Protocol

Redis as the nervous system:

Channel / Key	Purpose
`cca:notify:<project>`	pub/sub — agent completion notifications to Telegram
`cca:chat:log:<project>`	append-only log of all Telegram↔Claude exchanges
`whiteh:auto_send_queue`	disclosure email queue (white-hat scanner)
`whiteh:disclosures`	rolling list of discovered vulnerabilities
`whiteh:sent_emails`	sent email log (capped at 500)
`whiteh:dead_letter_emails`	failed sends after MAX_REQUEUE_ATTEMPTS

Notification flow:

agent task completes
  → cc-agent publishes to cca:notify:money-brain
  → cc-tg receives notification
  → flushes to Telegram + appends to Redis log

The Prompt Trick

Problem: Services need to call tools (send emails, write to Slack, hit APIs) without storing credentials in the service code. Credentials must not appear in npm packages, environment variables baked into build artifacts, or anywhere that could leak.

Solution: The service spawns a Claude Code subprocess with cwd set to the project directory that has the relevant MCPs configured. Claude inherits the MCP session and can call the tool. The service only passes the prompt — credentials never touch the service code.

spawnSync('claude', ['--print', '--dangerously-skip-permissions', '-p', prompt], {
  cwd: '/Users/feral/money-brain',  // ← inherits gmail-personal MCP
  env: { ...process.env, CLAUDE_CODE_OAUTH_TOKEN: token },
  timeout: 60_000,
})

~/.claude.json holds project-scoped MCP configs:

{
  "projects": {
    "/Users/feral/money-brain": {
      "mcpServers": {
        "gmail-personal": { "command": "npx", "args": ["-y", "gmail-mcp-imap"] }
      }
    }
  }
}

Zero credentials in published code. No SMTP passwords. No API keys. The Claude OAuth token is the only secret, and it lives in the environment.

Service Deployment

All services deploy as npm packages pulled via npx --prefer-online. Never from local artifacts.

agent builds → tests → npm version patch → npm publish → pkill service → launchd respawns → npx pulls latest

The deploy cycle is atomic: launchd always runs the latest published version on next spawn.

Design Philosophy

1. Intelligence over orchestration The coordinator is not a workflow engine. It is a Claude session. Tasks are described in natural language, not YAML pipelines. The intelligence adapts to failure, ambiguity, and changing requirements without reconfiguration.

2. Self-healing by default KeepAlive: true in launchd means every service is always on. Crashes are events, not incidents. The system restores itself without human intervention.

3. Zero credentials in code The prompt trick means tools are accessed through Claude's credential chain, not the service's. npm publish is safe. The codebase is publishable by default.

4. Ship as the definition of done An agent that researches but doesn't commit, commits but doesn't PR, or PRs but doesn't merge — is not done. Terminal steps (PR, merge, publish, restart) are part of every task definition.

5. Composability through MCP Services expose capabilities as MCP tools. Other services consume them. The harness grows by adding MCPs, not by rewriting orchestration code. New capability = new MCP server.

6. Ephemerality with persistence Task agents are ephemeral — they run, ship, and exit. The coordinator is persistent — it holds state, routes work, and remembers context. The separation keeps agents cheap and stateless while keeping the coordinator deep and contextual.

The Full Cycle

Telegram message
  → cc-tg coordinator (persistent Claude session)
  → spawn_agent via cc-agent MCP
  → task agent clones repo, creates branch
  → implements, tests, commits
  → PR opened, merged
  → npm publish, service restart
  → launchd spawns new process with latest package
  → Redis notification
  → Telegram reply

One message. Full stack. No human in the loop.

This is the infrastructure pattern, not the product. The product is whatever the agents build.

Gonzih/meta-harness-design.md

Select an option

No results found