ham-autocode

ham-autocode

Coordinate multiple AI agents to autonomously complete entire software projects — saving 82% token cost.

v4.2 | CHANGELOG | Architecture | Guide | Roadmap | 中文文档

What is it?

Claude Code (Opus) is powerful but expensive and quota-limited. ham-autocode solves this by splitting tasks and routing them to free/low-cost agents while maintaining quality:

PLAN.md → DAG → Opus writes spec → Route to agent → Execute → Quality gate → Commit → Next wave

One command runs the full loop unattended:

ham-cli execute full-auto              # Run all phases autonomously
ham-cli execute full-auto --push       # Auto git push when done
ham-cli execute full-auto --dry-run    # Preview without executing

The architecture is informed by Harness Engineering practices (OpenAI, Anthropic, Stripe, Hashimoto) — used as methodology, not as goal. The project follows a Skill-First principle: community skills (gstack, GSD, Superpowers) are preferred; self-built modules only cover what they don't — multi-agent dispatch, DAG scheduling, and quality gates for autonomous execution.

What's new in v4.2

• Routing v2 — 7 agent targets with decision tree R1-R6. New cc-sonnet / cc-haiku sub-agents via claude -p --model fill the gap between free gpt models and Opus; R2 random archive (opencode vs cc-haiku) feeds offline A/B data
• gpt-5.4-mini replaces gpt-5.3-codex as codexfake backing model (slightly stronger, same github-copilot/openai providers)
• Hierarchical CONTEXT.md via LSP — zero-dep LSP client spawns typescript-language-server, builds per-directory symbol trees under .ham-autocode/state/context/tree/. Injected into every agent task. 101 files / 877 symbols built in 1.7s
• MCP stripping for cc-sub agents — claude -p --strict-mcp-config --mcp-config '{"mcpServers":{}}' → sub-agent cold-start -80% duration (26s → 5s real measurement)
• auto-runner.ts split — 980-line single file → 6 modules under runner/, max 369 lines, API fully backward compatible
• migrate auto-patches .gitignore — idempotent allowlist block injection, no manual editing for new projects
• RunContext + ab-log closure — explicit context object replaces 2 module-level state vars; R2 random results recorded to state/routing/ab-log.jsonl with route ab-stats CLI

See CHANGELOG.md for full breakdown and per-metric impact.

7-Layer Architecture

Layer	What it solves	Key Modules
Context Engine	Right context for right agent — per-target templates, 40% Smart Zone budget	context-template.ts summary-cache.ts
DAG Orchestration	Task dependency scheduling — topo sort, wave parallelism, CPM, runtime editing	parser.ts graph.ts scheduler.ts critical-path.ts merge.ts
Validation Gates	Layered quality assurance — L0-L4 gates, failure diagnosis, L4 auto-retry (v4.0)	quality-gate.ts review-gate.ts diagnosis.ts
Recovery Engine	Fault tolerance — git checkpoint, worktree isolation, fallback chain	recovery/checkpoint.ts recovery/worktree.ts
Agent Routing	Cost-optimal dispatch — 5-target scoring, quota tracking, static rules	router.ts scorer.ts quota.ts
Spec Engine	Spec quality drives success — Opus generation, feedback loop, TDD requirements (v4.0)	spec-generator.ts spec/reader.ts spec/enricher.ts
Knowledge Compounding	Cross-session learning — project brain, code entities, auto-learn after each task	project-brain.ts code-entities.ts auto-learn.ts

Each layer is detailed in ARCHITECTURE.md.

Three-Layer Framework

gstack thinks → GSD stabilizes → Superpowers executes