Reference Implementations
Studying existing harnesses is one of the best ways to learn how to build one. Here are the key implementations to study, what to learn from each, and where to look.
Open Source Harnesses
| Harness | Language | Focus | What to Learn | Link |
|---|---|---|---|---|
| OpenCode | TypeScript | General purpose coding agent CLI/TUI | Modern architecture, TUI, sub-agents, permissions, MCP | github.com/opencode-ai/opencode |
| Claude Code | TypeScript/Node | Anthropic's coding agent | Polished UX, tool design, sub-agents, context management | Closed source but widely used |
| Codex CLI | TypeScript/Rust | OpenAI's coding agent | Clean design, sandboxing, approval modes | github.com/openai/codex-cli |
| Aider | Python | Git-focused coding agent | Simple architecture, git integration, cost tracking | github.com/Aider-AI/aider |
| Continue | TypeScript | IDE extension + CLI | IDE integration, context providers, rules | github.com/continuedev/continue |
| Cline/RooCode | TypeScript | VSCode extension | Plan/act modes, browser use, MCP, task management | github.com/cline/cline |
| LangGraph CLI | Python/TypeScript | Agent framework CLI | Graph-based orchestration, debugging | github.com/langchain-ai/langgraph |
What to Study By Component
| Component | Best Reference | Notes |
|---|---|---|
| Agent Loop | OpenCode, Codex CLI | Clean loop implementations |
| Tool Registry | OpenCode | Well-structured tool system with schemas |
| Permission System | Claude Code patterns, Cline | Sophisticated permission models |
| Sub-Agents | Claude Code, OpenCode | Task delegation patterns |
| TUI/CLI UX | OpenCode | Excellent terminal UI with Ink/React |
| Context Building | Continue, Aider | Smart context selection |
| MCP Integration | Cline, OpenCode | MCP client implementation |
| Git Integration | Aider | Deep git workflow integration |
| Checkpointing/State | LangGraph | State management patterns |
Studying Tips
1. Start with the Entry Point
Look at main/CLI entry to understand flow: - How does it parse args? - How does it initialize components? - How does it start the agent loop?
2. Trace a Simple Task
Pick "read a file" and trace through: 1. User input parsing 2. Context building 3. Model call 4. Tool call detection 5. Permission check 6. Tool execution 7. Result handling 8. Next iteration
3. Focus on Key Files
In most harnesses, look for:
- agent/ or agent.ts - Core agent logic
- tools/ - Tool implementations
- session/ - Session management
- prompt/ or system/ - System prompts
- permissions/ - Permission system
4. Understand the Data Flow
Map how messages flow through the system: - User message → Context builder → Model → Response parsing → Tool execution → State update
OpenCode Deep Dive
OpenCode is particularly good to study because it's open source and well-architected:
opencode/
├── packages/
│ ├── cli/ # CLI/TUI entry
│ ├── core/ # Core agent logic
│ ├── web/ # Web UI
│ └── sdk/ # SDK
Key patterns to look at: - Session management - Tool registry pattern - Sub-agent implementation - Permission modes - Provider abstraction
Aider Deep Dive
Aider is simpler and easier to understand:
- Clean Python codebase
- Good git integration patterns
- Cost tracking implementation
- Message history management
- Simple but effective loop
Building Your Own
After studying, build incrementally:
- Week 1: Minimal loop + read/write tools
- Week 2: Add permissions and bash
- Week 3: Add context building and history
- Week 4: Add sub-agents or better UX
- Iterate: Use it on real tasks and improve
Common Patterns to Copy
| Pattern | Implementation Idea |
|---|---|
| Tool Result Formatting | Consistent format across all tools |
| Error Handling | Graceful degradation with clear messages |
| Streaming | Real-time feedback during long operations |
| Diff Preview | Show file changes before applying |
| Task Tracking | Todo list management |
| Auto-Compact | Summarize when approaching context limit |
Questions to Ask While Studying
- How do they structure the agent loop?
- How do they handle permissions?
- How do they build context?
- How do they manage state?
- How do they handle errors?
- How do they implement sub-agents?
- What's their UX philosophy?
- What would I do differently?
Related Notes
- Minimal Harness — Build from scratch
- Implementation Guide — Detailed implementation
- Harness Architecture — Architecture patterns
- Tool Registry — Tool system
- Sub Agents — Sub-agents
Sources
- OpenCode GitHub Repository
- Cline GitHub Repository
- Aider GitHub Repository
- Continue GitHub Repository
- Codex CLI GitHub Repository
- Various engineering blog posts about agent harnesses