Chapter One
Architectural Foundations
The Terminal as Agent Runtime — Why the CLI Won
After a decade in which IDEs grew heavier, the command line has re-emerged as the center of gravity for AI-assisted coding — and for AI agency more broadly. Between February 2025 and early 2026, every major AI lab shipped a terminal-native agent runtime: Anthropic with Claude Code, OpenAI with Codex CLI, Google with Gemini CLI, Block with Goose, Sourcegraph with Amp. The open-source ecosystem — Aider, Cline, Plandex, Continue.dev, OpenCode — expanded in parallel, driven by a user base that demands model flexibility and Unix composability that locked-in IDEs cannot provide.
The underlying shift is architectural. These tools are not glorified autocomplete plugins. They are agent loops: they read the filesystem, execute shell commands, manage git history, call external APIs, spawn subprocesses, and act across multi-file codebases with minimal human intervention. The terminal is their native habitat because it is where all of those capabilities already live.
Composability Over Convenience
The terminal was built for long-running processes, parallel sessions, scriptable workflows, piped I/O, and composable tools. These properties align precisely with what autonomous agents need. Claude Code makes this explicit in its documentation: you can pipe git diff output into it, pipe its output into jq, or chain it with make targets. An IDE plugin operates within the IDE's extension API — expressive for code intelligence, but structurally ill-suited to orchestrating shell commands, managing processes, or running headlessly in a CI pipeline.
The Unix philosophy scales to the agent layer: build a tool that does one thing well, accept input on stdin, emit structured output on stdout, and let the human (or orchestrator) compose the rest. CLI agents inherit this composability for free. Web UIs do not.
Context Quality at Scale
IDE plugins typically operate on the current file or function. The terminal, by contrast, gives agents access to the full project tree, .git history, environment variables, test runners, build systems, and any other shell-accessible resource. The agents that excel — Claude Code on 500,000-line legacy codebases, Plandex on multi-session rewrites — do so because the terminal context is richer and less artificially bounded than what an IDE plugin can access.
The Universal Agent Loop
Every terminal-native agent shares a common execution structure. The agent receives a task, enters a loop of: (1) reasoning about what to do, (2) calling a tool (read file, write file, run command, call API), (3) observing the result, and (4) deciding whether the task is complete or another tool call is needed. The loop terminates on completion or an error condition requiring human input.
The tool interface maps cleanly to the Unix process model: tools are invoked as subprocess calls or function calls, returning structured output the model can reason over. This is architecturally simpler than the callback-heavy event models of browser extensions or the sandboxed JS worker threads of VS Code extensions.
File System Access
File access is the primitive capability every CLI agent exposes. The standard pattern is directory-scoped: the agent can read and write any file under the project root, with the boundary enforced by either convention or by OS-level sandboxing. Tools like read_file, write_file, list_files, and search_files are implemented as thin wrappers around POSIX system calls. This gives the agent the exact same file access model a developer would have in the same directory.
Loop Termination
The loop terminates on one of three conditions: task completion (agent decides it's done and signals completion), error requiring human input (ambiguous task, permission denied, tool failure), or budget exhaustion (token limits, timeouts, or explicit stop signals). In production use with an agentic harness like DSSO, the harness manages termination via STATE.json — clean completion transitions to the next phase, while error conditions trigger a RESUME block for human or fallback intervention.
Headless and Autonomous Operation
A critical capability that web UIs structurally cannot provide is headless execution: running an agent without a human in the session. This unlocks CI/CD integration, scheduled autonomous work, and agent-to-agent orchestration. Practical applications include:
- Piping git diff into Cline for automated code review on pull request open
- Running Claude Code in GitHub Actions to fix failing tests and commit the result
- Scheduling Aider to apply dependency upgrades overnight and open PRs
- Chaining Codex CLI outputs into deployment scripts
The growing availability of `--headless` flags, `--print` (non-interactive) modes, and environment-variable-driven configuration across these tools reflects a deliberate architectural choice: the CLI is the primitive; the UI is a convenience wrapper. For DSSO, headless operation is non-negotiable — the state machine invokes agents through deterministic one-shot calls (`claude -p "task"`, `aider --model sonnet "task"`, `continue review --pr`), parses structured output, and transitions state without any interactive session.
Chapter Two
Claude Code CLI — The Proprietary Reference Implementation
Market Position and Architecture
Claude Code is Anthropic's agentic coding tool that launched as GA on May 22, 2025, reached $2.5 billion in annualized revenue by February 2026, and now has 130,000+ GitHub stars. It runs in the terminal, the desktop app, and VS Code extension — all sharing the same underlying engine, so CLAUDE.md files, settings, and MCP servers configured in the CLI work across all surfaces. As of v2.1.162 (June 3, 2026), the recommended install uses the platform-native binary via curl, brew, or winget. The npm package (@anthropic-ai/claude-code) was deprecated in v2.1.113.
The Seven Extensibility Primitives
Claude Code separates memory, hooks, skills, subagents, plugins, and MCP into distinct architectural layers. Each layer changes what the model can see or do:
- CLAUDE.md — The agent's constitution for your repository. Read every session start to anchor conventions, no-touch zones, build commands, and quality gates.
- Skills — A SKILL.md file with frontmatter under `.claude/skills//`. Supports `/name` invocation and autonomous invocation by Claude. Domain logic with shipped files.
- Subagents — Specialized instances with their own context windows. Verbose work stays isolated so your main conversation stays focused. Auto-delegate or `@agent-name` invocation.
- Slash Commands — Typed shortcuts starting with `/`. Built-ins include `/init`, `/compact`, `/context`, `/review`, `/security-review`. Also commands from `~/.claude/commands/`.
- Hooks — Deterministic scripts that fire at defined lifecycle points. PreToolUse is the primary security checkpoint before any tool runs. Enforces rules without hallucination.
- MCP Servers — Model Context Protocol connects Claude Code to GitHub, databases, and browsers. Configured via `.mcp.json` or `claude mcp add`. The server handles integration; Claude reasons about what to do.
- Plugins — A plugin is a versioned bundle of skills, subagents, commands, hooks, and MCP definitions. One `/plugin` command installs the whole set — sharing setups across teams.
Rule of Thumb
Use a slash command for a prompt template. Use a skill for domain logic with shipped files. Use a subagent for isolated, parallel tasks. Use a hook for deterministic lifecycle enforcement. Use an MCP server for external service integration. Use a plugin when you need to share all of the above as a single installable unit.
Session Management and CLI Flags
The CLI is the most capable surface — it gets new features fastest, supports the full flag set, and runs natively in any terminal environment.
Core CLI Flags
| Flag | What it does |
|------|-------------|
| `claude` | Start interactive mode |
| `claude "task description"` | Run a one-time task and return to shell |
| `claude -p "query"` | Non-interactive: run query and exit (for pipes/scripts) |
| `claude -c` or `--continue` | Resume most recent conversation |
| `claude -r` or `--resume` | Open conversation picker |
| `claude --permission-mode plan` | Plan mode: read and propose, no edits |
| `claude --worktree ` | Start session in new git worktree |
| `claude --bg "task"` | Launch background agent session |
| `claude agents` | View all running/blocked/completed sessions |
| `claude -p "q" --output-format json` | JSON output for scripting |
| `claude mcp list` | List configured MCP servers |
Inside a Running Session
| Command | What it does |
|---------|-------------|
| `/help` | Show all available commands |
| `/clear` | Clear conversation history |
| `/compact` | Compress context to free up tokens mid-session |
| `/model` | Change model for current session |
| `/effort` | Set effort level: low, medium, high, xhigh, max |
| `/usage` | Show token and cost usage |
| `/loop` | Repeat a prompt on a recurring interval |
| `/recap` | Summarize context for returning to a session |
| Shift+Tab | Toggle plan mode or cycle permission modes |
Permission Modes
Claude Code offers a spectrum of permission modes. Default mode asks before each file write and shell command — safest for first-time users and unfamiliar codebases. Plan mode explores and proposes without executing — ideal for scoping work before committing edits. Auto Mode (research preview) uses a separate Sonnet 4.6 classifier to review each action: safe actions proceed, risky ones get blocked or escalated. The permission mode is set per-session, and developers typically start in default for trust-building, then graduate to auto mode for routine work on well-understood codebases.
Claude Code vs Codex CLI vs Gemini CLI
All three major labs shipped terminal-native agents, but they differ significantly in model lock-in, cost structure, and architectural choices.
| Dimension | Claude Code | Codex CLI | Gemini CLI |
|-----------|-------------|-----------|------------|
| Model lock-in | Claude only (Haiku, Sonnet, Opus) | OpenAI only | Gemini only |
| License | Proprietary | Open-source | Open-source |
| Language | TypeScript | Rust | — |
| Free tier | No | Through subscription | 1,000 req/day |
| Context window | Extended thinking | 128K standard | 1M tokens |
| MCP support | Native | Native | Native |
| Headless/CI | Yes | Yes | Yes |
Claude Code is locked to Anthropic's Claude models and is proprietary. OpenAI's Codex CLI is built in Rust for speed — noticeably faster than Claude Code's TypeScript core — and open-source. Google's Gemini CLI offers the most generous free tier (60 requests per minute, 1,000 per day) and a 1-million-token context window, making it attractive for large-context reasoning tasks and cost-sensitive developers.
For DSSO integration, the key consideration is headless operation support — all three support it. But Claude Code's deeper agentic loop (hooks, subagents, MCP plumbing, permission modes) makes it the most capable "think" phase agent. Codex CLI's speed advantage makes it attractive for "do" phase work. Gemini CLI's free tier makes it ideal for prototyping and exploration.
Chapter Three
Aider — The Open-Source Model-Flexible Standard
Position and Architecture
Aider is the largest deployed open-source coding CLI by usage, with 39,000+ GitHub stars, 4.1 million installations, and 15 billion tokens processed per week as of early 2026. It started shipping in mid-2023 — well before the current generation of CLI agentic coders existed. By the time Claude Code, Cursor, and Codex CLI arrived, Aider already had a repo-map, edit modes, voice support, and a meaningful contributor community.
Aider supports virtually every LLM — Claude, GPT-4o, DeepSeek, Gemini, Mistral, and any local model served via Ollama or LM Studio — making it the default choice for teams that want model flexibility without vendor lock-in. It integrates tightly with git, generating automatic commit messages for every change. Supports 100+ programming languages, voice-to-code via Whisper, and IDE watch mode. Apache 2.0 licensed. Users pay their model provider directly.
Why Aider's Architecture Matters
Aider is permissively licensed, the model layer is bring-your-own, and the entire pipeline is auditable in a single Python codebase. Every prompt template, every edit-format parser, every retry loop, and every cost calculation is in the open. When something misbehaves in your repo, you can read exactly why — an advantage no closed-source competitor offers.
The cost story is the other reason teams pick Aider. Closed agentic coders bundle the model bill into a subscription that covers UI, telemetry, and brand. Aider charges you nothing and pays the model provider directly at API rates. For teams that already run Anthropic or OpenAI keys, switching to Aider for a class of work can cut spend dramatically with no quality loss — the same Sonnet token is the same Sonnet token.
Repo-Map, Edit Modes, and Voice Loop
Aider's engineering strength is in what Claude Code explicitly doesn't optimize for: the boring parts done right.
Repo-Map Context Generation
Aider generates repository context without scanning every file. Using tree-sitter, it builds a structural index of the codebase — understanding imports, class hierarchies, function signatures, and file relationships. The agent knows what symbols exist and where before it reads a single file. This is more efficient than naive full-tree traversal and more accurate than relying on the model's training data to guess the project structure.
Four Edit Modes
Aider offers four distinct edit modes that let you match risk to task:
- Diff mode — Minimal, targeted edits. Applies surgical changes to specific lines. Safest option for routine work and code review.
- Whole mode — Rewrites entire files. Highest risk but necessary for significant refactoring or file rewrites. Use with git auto-commits enabled.
- Architect mode — Proposes architectural plans without editing code. Delegates implementation to another mode or agent. Ideal for design discussions and phase planning.
- Ask mode — Read-only queries. The agent reads files and answers questions about the codebase without making changes. Zero risk — purely analytical.
Voice Coding
Aider's voice coding loop, built on OpenAI Whisper, genuinely changes how interactive coding feels. Speak changes, Aider implements them. The loop is: speak → Whisper transcribes → Aider plans edits → edits applied → git commit → ready for next instruction. This mode is most useful during focused refactoring sessions where typing would break flow.
Git Auto-Commit
Aider generates automatic commit messages for every change — not just "update file" but semantically meaningful messages describing what changed and why. Each commit granularly represents one agent turn, making review and rollback straightforward. For DSSO integration, the `--no-auto-commits` flag disables this behavior so the harness manages the git history.
Setup and Configuration
Aider has three supported install paths. All converge to a single `aider` binary on PATH that respects model environment variables.
Install Paths
- pip: `pip install aider-chat` — canonical route. Works on macOS, Linux, and WSL. Pair with pipx for isolation. Cleanest upgrade story.
- uv tool: `uv tool install aider-chat` — faster installer for teams already using uv. uv resolves dependencies in seconds. Upgrades: `uv tool upgrade aider-chat`.
- Docker: `docker run -it --user $(id -u):$(id -g) --volume $(pwd):/app paulgauthier/aider-full` — isolates Aider from host Python, sandboxes file access to a single bind mount. The install path most enterprises adopt. Trade-off: voice mode is harder to wire through a container boundary.
Model Configuration
Aider reads `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `DEEPSEEK_API_KEY`, `OPENROUTER_API_KEY`, and many more provider keys from environment variables. The model is picked with `--model` or in `.aider.conf.yml`. Aliases like `--sonnet` and `--haiku` short-circuit to sensible defaults.
The recommended default for a fresh team: Sonnet on diff mode. Sonnet is a consistent top-tier performer on Aider's Polyglot Coding Leaderboard, cost is predictable, and failure modes are well documented. If cost-sensitive, swap Sonnet for DeepSeek or Haiku-class models — you lose a touch of edit quality and gain a meaningful cost reduction. For air-gapped environments, Aider works with local models via Ollama: `aider --model ollama/qwen3`.
One-Time Setup Checklist
1. Set your model key as an environment variable
2. Drop `.aider.conf.yml` at repo root with a `model:` entry and `auto-commits: true`
3. Create a `CONVENTIONS.md`, `CLAUDE.md`, or `.aider-rules.md` for constitutional memory
4. (Optional) Enable lint checking with `lint: true` to automatically run linters on generated code
Chapter Four
Continue.Dev CLI — The Async CI/CD Agent Model
The Pivot to Continuous AI
Continue.dev transformed from a VS Code autocomplete extension into a CLI-first Continuous AI platform that runs async agents on every pull request — making it one of the most interesting open-source developer tools in 2026. With 26,000+ GitHub stars as of March 2026, it stands out from proprietary alternatives like GitHub Copilot by being entirely free — your only costs are LLM API fees and compute.
The new architecture centers on two modes:
- Headless mode — Cloud agents that integrate with CI/CD pipelines and GitHub workflows. They run asynchronously, process PRs automatically, and post review comments without any developer interaction.
- TUI mode — Interactive terminal sessions for developers who prefer CLI-based workflows. Run `continue` in your terminal to start an interactive session tied to your current repository context.
Rather than suggesting code inline as you type, Continue.dev agents run asynchronously, review pull requests against team-defined rules, flag issues silently, and propose fixes with full diffs. This is a fundamental shift in positioning: the old Continue.dev helped you write code faster; the new Continue.dev reviews code after it's written and enforces your team's standards automatically.
The Conceptual Shift
Continue.dev is addressing a fundamentally different question than Claude Code or Aider. Claude Code asks "what should I write?" Aider asks "how should I change this code?" Continue.dev asks "does this code meet our standards?" — and answers it automatically, every time. That makes it the most natural fit for the CI/CD pipeline: the agent that runs when you push, not when you type.
Async PR Agents and Rule Enforcement
Continue.dev's Continuous AI architecture delivers three core capabilities that set it apart from traditional coding assistants — and from both Claude Code and Aider.
Async PR Agents
Agents monitor every pull request and enforce coding rules your team defines — flagging security issues, style violations, and architectural mismatches without interrupting developer flow. They integrate natively with GitHub, Sentry (error tracking), Snyk (security scanning), Supabase, Slack, and standard CI/CD pipelines. The agent doesn't need to be watching — it runs when the PR is opened, posts its findings, and disappears.
Rule Enforcement Engine
Rules are defined in `.continue/rules.yaml` using YAML with natural language descriptions alongside regex and AST patterns. Teams codify standards in code rather than docs: define rules once, and every PR gets checked automatically. Example rules: "No hardcoded credentials" (regex + AST check), "API routes must have input validation" (AST pattern), "Error messages must be wrapped" (natural language with type-checking context).
Initial rule setup takes 30-60 minutes for most teams. Subsequent rules take minutes each.
Diff-Based Suggestions
Rather than vague warnings ("this function is too long"), Continue.dev agents propose specific fixes with full diffs. The change to the code review experience is dramatic — from "find the problem" to "approve the solution." This directly addresses the trust gap where 66% of developers say AI output is "almost right, but not quite."
Local Model Support
Continue.dev's Ollama integration is its strongest privacy differentiator. Running with a local model means zero code leaves your infrastructure — critical for regulated industries. The cost comparison is stark: a 10-person team pays $200-400/month for GitHub Copilot versus $20-80/month for Continue.dev in API fees.
Competitive Positioning
Understanding where Continue.dev fits in the 2026 landscape requires recognizing a key fact: Continue.dev complements Claude Code and Aider rather than competing with them directly.
Cursor handles real-time coding. Claude Code handles complex multi-step refactoring. Continue.dev handles automated PR review and standards enforcement. They operate at different points in the development lifecycle and answer different questions.
The Three-Tool Stack
Many high-performing teams run all three:
| Tool | When | What it asks |
|------|------|-------------|
| Cursor | During coding | "What should I write next?" |
| Claude Code | During refactoring | "How do I restructure this?" |
| Continue.dev | After code is written | "Does this meet our standards?" |
| Aider | Any phase | "Make this change with any model" |
The Continue.dev Trade-Off
Continue.dev's biggest learning curve versus Copilot is conceptual: it is not a real-time autocomplete tool. Developers expecting inline suggestions will be disappointed. The power comes from async pipeline integration, not keystroke-level assistance. But that same quality makes it the most natural DSSO integration point for the "check" phase — it's the only CLI agent designed from the ground up to operate without a human on the other end.
Chapter Five
Practical Usage Guide — Getting the Most from Each Tool
Claude Code — Production-Grade Setup
The setup investment for Claude Code is real. One Reddit user on r/ClaudeAI reported it "took 2–3 weeks to dial in" for a production-grade setup. But that upfront investment pays off fast: "The CLAUDE.md rules prevent it from going off the rails. Without this, the agent would 'helpfully' refactor my auth code while fixing an unrelated bug."
CLAUDE.md Configuration
Place CLAUDE.md in your project root (or `~/.claude/CLAUDE.md` for global defaults). Claude reads it at the start of every session — before your first prompt. Things that belong in it:
- Coding standards: "Use async/await, not callbacks. No console.log in production code."
- Architecture decisions: "Auth is in src/auth/. Don't modify without a security review."
- No-touch zones: "Never modify migrations/ or config/production.js."
- Quality gates: "Always run npm test after edits. If tests fail, fix them before committing."
- Build commands: "Run npm run build to compile, npm run dev for local dev server."
Modular Rule Files
Create `.claude/rules/` for modular rule files. This keeps CLAUDE.md focused while enabling granular rule sets per project area. Additional conventions can live in `.cursorrules`, `.windsurfrules`, `AGENTS.md` (Codex CLI convention), or `CONTRIBUTING.md`.
Permission Mode Cycling
Developers typically cycle through modes depending on task risk: plan mode → scope the work and get approval; default mode → execute cautiously, approving each write; auto mode (research preview) → trusted tasks bypass approval gates. For routine work on well-understood codebases, auto mode eliminates friction. For unfamiliar or high-risk changes, plan mode prevents costly mistakes.
Hygiene
Use `/compact` every 30-50 interactions to prevent context degradation. `/usage` to track token consumption. `/model` to switch between Haiku (cheap), Sonnet (balanced), and Opus (expensive but most capable). `/effort` to scale reasoning depth — high/max for complex architectural decisions, low/medium for routine edits.
Aider — Recommended Workflows and Model Routing
Aider's flexibility across models and modes means the best configuration depends heavily on task type and budget sensitivity.
Default Workflow
For primary interactive coding: `aider --sonnet` in diff mode. Sonnet provides consistent top-tier performance on Aider's Polyglot Coding Benchmark, diff mode minimizes unintended side effects, and auto-commits create clean per-turn git history. For codebase queries without edits: `aider --ask` (read-only, zero risk). For architectural planning: `aider --architect` — proposes plans, delegates implementation to diff mode.
Cost-Sensitive Bulk Work
For large-scale refactoring (parameter renames across hundreds of files, import reorganization, test scaffolding), use cheaper models: `aider --deepseek` or `aider --model claude-3-haiku` with `--no-auto-commits`. The quality loss on mechanical tasks is negligible, and the cost reduction is dramatic — DeepSeek can be 1/10th the cost of Sonnet for equivalent output on routine transformations. After bulk execution, review with `aider --sonnet --ask` to audit changes.
Air-Gapped Work
For security-sensitive or offline environments: `aider --model ollama/qwen3` (or `ollama/llama3`, `ollama/deepseek-coder`) with a locally-served Ollama instance. Zero data leaves the machine. This is the only viable option for regulated industries requiring air-gapped development tooling.
Voice Mode
`aider --voice` enables the speak-implement loop via Whisper. Most useful for focused refactoring sessions where typing breaks flow or during code review walkthroughs.
DSSO-Ready Configuration
For integration with DSSO, use `--no-auto-commits` and disable lint (`--no-lint`). Let DSSO manage the git history through its state machine, and let lint checking happen either in Continue.dev (if configured) or as a post-phase DSSO task. Add `--yes` to suppress interactive prompts for fully automated headless use.
Continue.Dev — Team Workflow Integration
Continue.dev's integration pattern is fundamentally different from Claude Code or Aider because it operates in a different part of the development lifecycle: after the code is written, not during its creation.
Initial Setup
1. Install: `npm install -g continue`
2. Connect your GitHub repository
3. Configure your LLM backend in `~/.continue/config.json` (OpenAI, Anthropic, or local Ollama)
4. Define rules in `.continue/rules.yaml`
5. Enable Headless mode via `continue github connect`
Rule Definition
Rules cover three categories:
- Security: "No hardcoded API keys," "No eval() with user input," "SQL queries must use parameterized statements"
- Style: "Import order: standard library, third-party, local," "Maximum function length: 60 lines"
- Architecture: "Repository layer must not call repository layer," "API handlers must validate input"
Team Workflow
The key mindset shift: Continue.dev is not asking "what should I write?" but "does this code meet our standards?" Most engineering teams use Headless mode as the core workflow (runs on every PR automatically) and TUI mode for exploratory sessions during active development. Integrations with Sentry enable error-pattern alerts that feed back into rule definitions, creating a continuous improvement loop.
DSSO Integration
Continue.dev Headless fits the DSSO "check" phase naturally. After DSSO+ClaudeCode or DSSO+Aider completes execution and submits a PR, DSSO invokes Continue.dev Headless to verify the changes against team rules. The rule check result feeds back into STATE.json as a quality gate — pass proceeds to the next phase, fail triggers a fix phase. This creates a closed loop: plan → execute → verify → iterate.
Chapter Six
Agentic Orchestration — DSSO Integration
The Orchestration Problem
The CLI agents described in previous chapters are powerful within a single context window. But real engineering work spans hours, days, or weeks — multiple context resets, multiple agent invocations, staggered parallel work. This is the orchestration problem that no single CLI agent solves on its own.
The market is responding. Plandex ships with a 2-million-token effective context window and 20-million-token indexing via Tree-sitter parsing. Continue.dev's Headless mode runs agents asynchronously without human supervision. The Zylos Research report on CLI agent frameworks identifies "parallel agent orchestration" as the next architectural evolution underway in 2026 — running multiple CLI agents simultaneously on different files, tasks, or subsystems, with a coordination layer managing state and dependency resolution.
But none of these tools provide a deterministic state machine for multi-session work. Claude Code's subagents are an early version of this — isolated instances with their own context windows — but they don't persist state across system restarts or externalize their decision trees in a machine-readable format. Continue.dev's Headless agents run in parallel but have no protocol for coordinating with other agents. The orchestration gap is real, and it's the problem that DSSO was designed to solve.
DSSO Architecture Overview
DSSO (Deterministic State Space Orchestration) is a file-driven state machine for multi-session autonomous agent work. It solves the fundamental problem that all CLI coding agents face but none address natively: context is volatile, but files are durable.
Core Architecture
The durable meta-layer consists of four files:
- STATE.json — The single source of truth for current phase, completed items, blocked items, and next actions. Rewritten atomically on every phase transition. Never appended — if the agent crashes mid-write, the previous complete state is preserved.
- ROADMAP.md — Task decomposition into phases, chapters, and subsections. Human-readable and agent-readable. The ROADMAP is the plan; STATE.json is the progress tracker.
- GLOSSARY.json — Domain-specific terms, acronyms, and conventions. Prevents drift in terminology across sessions and agents.
- FROZEN_CACHE.context — A compressed summary of the most important context for deterministic resumption. Read by the next agent to avoid re-learning the domain.
Session-Log Append + RESUME BLOCK Protocol
Every agent session appends its decisions, code changes, and blockers to a session log. At the end of each phase, the agent writes a RESUME BLOCK to STATE.json — a no-prose-required instruction that tells the next agent exactly what to do without requiring it to re-read the full session history:
```
Phase 2 complete. 45/50 checklist items done.
Remaining items: C-7, D-12, E-3, F-8, G-1.
These require manual review for Payment Services domain logic.
C-7: Implement validation for SWIFT MT103 field 32A (Value Date).
```
The next agent reads this and continues deterministically. No context needed from the previous session.
Three-Way Reconciliation Engine
DSSO's reconciliation engine takes three inputs: (A) broken legacy code, (B) Jira tickets describing required behavior, and (C) domain knowledge from subject matter experts. It synthesizes these into correct output — a problem that single CLI agents cannot solve because they lack cross-referencing capability across these dimensions. This was the core innovation in DSSO v2, built for the UFT VBScript migration at the Federal Reserve Bank of Kansas City.
Independent Discovery
DSSO was built for the Mughal Ralph project before June 2026 — structually identical to what Anthropic published in November 2025 as an agentic orchestration pattern. This convergent evolution from first principles on a Raspberry Pi 4 with real context-window constraints validates the pattern as a natural solution, not an idiosyncratic invention.
Key Distinction from MCP
DSSO is an agentic harness — a state machine for self-orchestration. MCP (Model Context Protocol) is an API integration layer for external services. They solve different problems. DSSO manages what to do and in what order; MCP manages how to access external resources. In practice, they complement each other: DSSO can expose STATE.json through an MCP server, making it directly readable by any MCP-compatible CLI agent.
DSSO Integration Pattern
The DSSO + CLI Agent integration follows a four-phase loop that maps each tool to its optimal role. The pattern is: think → do → check → orchestrate.
Phase 1: Explore (Claude Code)
Claude Code in plan mode for the deep reasoning phase. The task: "Read ROADMAP.md, analyze STATE.json, review remaining items, and produce a detailed implementation plan for Phase N." Claude Code's deeper agentic loop handles ambiguity better than any other CLI agent. Its MCP connections can pull in external context (Jira tickets, database schemas, API docs) to inform the plan. Output: Updated ROADMAP.md and STATE.json with phase plan.
Phase 2: Act (Aider)
Aider for cost-sensitive bulk execution. The task: "Read STATE.json Phase N plan, implement changes, update FEATURE_CHECKLIST.json." Aider runs with `--no-auto-commits --yes --model deepseek` so DSSO manages the git history and the model cost stays low. For complex implementation work, route to Sonnet: `aider --sonnet --no-auto-commits --yes`. Output: Modified source files, updated FEATURE_CHECKLIST.json.
Phase 3: Verify (Continue.dev Headless)
Continue.dev Headless for CI/CD enforcement. The task: "Review the changes in this PR against team rules in .continue/rules.yaml." Continue.dev runs asynchronously, checks every PR rule, and produces a diff of violations. DSSO reads the result: pass proceeds to the next phase, fail triggers a fix task back to Phase 2. Output: Rule check pass/fail in STATE.json.
Phase 4: Persist (DSSO)
DSSO checks STATE.json, writes the RESUME BLOCK, and transitions to the next phase or marks the project complete. The agent-agnostic interface means any CLI agent is a drop-in replacement at any phase — swap Claude Code for Codex CLI, swap Aider for any other bulk editor, swap Continue.dev for a manual review step. The harness doesn't care which agent implements each phase as long as the contract ("read STATE.json → execute task → write STATE.json") is satisfied.
Key Patterns for CLI Agent Harnessing
Five patterns emerged from practical DSSO deployment (Mughal Ralph project, UFT VBScript migration) that are essential for reliable multi-tool orchestration.
1. Atomic State Writes
STATE.json is rewritten on every phase transition, never appended. This is the most important rule. If the agent crashes mid-write, the previous complete state is preserved. No partial state, no corruption, no "what was I doing?" recovery headaches. Atomicity is enforced by writing to a temp file and renaming: `write STATE.json.tmp` → `mv STATE.json.tmp STATE.json`.
2. No-Prose-Required Resume Blocks
The RESUME BLOCK must be self-contained — the next agent should be able to continue without reading any prior session context. This means including explicit checklist states, exact file paths, function signatures, and concrete next instructions. Vague prose like "continue where you left off" is forbidden. The block must answer: what's done, what's remaining, and what's the next action — in machine-readable format.
3. Model-Agnostic Agent Interface
The contract is: read STATE.json → execute task → write STATE.json. Any CLI agent that can read JSON, execute shell commands, and write JSON satisfies this contract. Claude Code, Aider, Codex CLI, Gemini CLI, Goose — all are drop-in replacements. This model-agnostic design is critical when a particular model's API goes down or pricing changes. The harness stays stable; only the agent primitive changes.
4. Explore-Plan-Act Loop
DSSO's three-phase loop maps directly to CLI agent capabilities:
- Explore = Claude Code's plan mode or Aider's architect mode — understand the problem, no edits
- Plan = Structured output to ROADMAP.md via any agent — write the plan, track dependencies
- Act = Bulk execution by any execution-capable agent — implement the plan, update checklists
5. Context Budget Management
DSSO tracks token usage per phase, alerting when a phase approaches the budget ceiling. This enables preemptive context compaction (`claude -p "/compact"`) before the agent's context window fills. For multi-session work spanning days, DSSO records token consumption in STATE.json metrics, enabling retrospective cost analysis and model selection optimization across phases.
Chapter Seven
Tool Comparison and Future Convergence
Head-to-Head Comparison Matrix
| Dimension | Claude Code | Aider | Continue.Dev |
|-----------|-------------|-------|-------------|
| Philosophy | Proprietary deep agentic loop | Open-source model-flexible standard | Async CI/CD enforcement |
| License | Proprietary (Anthropic) | Apache 2.0 (open-source) | MIT (open-source) |
| Model lock-in | Claude only | Any LLM (100+) | Any LLM |
| Cost | API/Max plan ($20-30+/mo equiv) | Free (BYO API key) | Free (BYO API key) |
| Offline support | No | Yes (Ollama/local models) | Yes (Ollama/local models) |
| Agentic depth | Deepest (hooks, subagents, MCP, plugins, auto mode, checkpoints) | Moderate (repo-map, 4 edit modes, git auto-commits, voice) | Shallow but specialized (rule enforcement, diff-based fixes) |
| Setup complexity | 2-3 weeks for production-grade | ~5 minutes | 30-60 minutes |
| Best-fit use case | Complex multi-step reasoning | Cost-sensitive bulk work, model experimentation | Team standards enforcement, PR quality gates |
The Venn Diagram
All three tools support Claude models (Claude Code natively, Aider via API key, Continue.dev via backend config). The overlap is meaningful — if you standardize on Claude as your reasoning model, you can use any of these three tools as the interaction surface depending on the task. The optimal multi-tool configuration in 2026 is: Claude Code for "think" phases, Aider for "do" phases, Continue.dev for "check" phases, and DSSO for "remember and orchestrate."
MCP and Standardization
Three parallel standardization efforts are converging to make CLI agents interoperable — a critical development for DSSO and any agentic orchestration system.
MCP — Model Context Protocol
MCP is becoming the universal tool extension protocol across all major CLI agents. It provides a JSON-RPC bridge to external services. Claude Code has native MCP support via `.mcp.json` or `claude mcp add`. Codex CLI and Gemini CLI both support MCP. Aider has partial MCP support — file system tools are native, but MCP integration is less mature than Claude Code's.
Block contributed Goose to the Linux Foundation's Agentic AI Foundation in December 2025, pushing MCP-as-standard across the ecosystem. The result: any MCP-compatible agent can use the same external tool interfaces — GitHub operations, database queries, browser automation — regardless of which lab built the agent.
AGENTS.md
Codex CLI launched with AGENTS.md as a repository-level agent instruction convention. It's functionally similar to CLAUDE.md but vendor-neutral. Other tools are adopting it alongside their own conventions. The competition between CLAUDE.md, AGENTS.md, `.cursorrules`, and `.aider-rules.md` is resolving into emerging convergence: agents read the conventions they recognize, and forward-thinking teams include multiple convention files in their repositories.
Implications for DSSO
For DSSO, this standardization means the harness can standardize on MCP for tool exposure and AGENTS.md/CLAUDE.md for per-repo instructions, making any CLI agent a drop-in replacement. DSSO can expose STATE.json, ROADMAP.md, and FEATURE_CHECKLIST.json through an MCP server, making them directly readable by any MCP-compatible CLI agent without custom parsing. The fragmentation of 2025 is giving way to convergence in 2026 — the terminal remains the agent runtime, but the agents themselves increasingly interoperate through shared conventions rather than competing walled gardens.
Decision Framework
The practical question is not "which tool should I use?" but "which tool for which phase, and how do I orchestrate them together?"
Single-Session Decisions
For a single session with a well-defined task:
- One-shot task, need answer now: `claude -p "fix this bug"` or `aider --sonnet "refactor this function"`
- Complex multi-file refactoring: Claude Code in plan mode, then execute in default mode
- Cost-sensitive bulk change: Aider with DeepSeek or Haiku
- Codebase query, no edits: `aider --ask` or Claude Code's plan mode
- PR quality check: Continue.dev Headless
Multi-Session Decisions (DSSO)
For work spanning days or weeks with multiple agents:
- Think phase: Claude Code in plan mode — deepest reasoning, MCP-integrated external context
- Do phase: Aider with model chosen by task complexity (Sonnet for complex, DeepSeek for mechanical)
- Check phase: Continue.dev Headless — automated rule enforcement, diff-based fixes
- Orchestrate: DSSO — STATE.json, atomics writes, resume blocks, model-agnostic agent interface
Budget Scenario
- High budget, maximum quality: Claude Code for all phases (most expensive, deepest agentic loop)
- Medium budget, balanced: Claude Code for thinking + Aider with Sonnet for doing + Continue.dev for checking
- Low budget, maximum efficiency: Aider with DeepSeek for doing + Continue.dev with Haiku for checking + DSSO for orchestration
The Takeaway
The fragmentation of CLI coding agents in 2025 has given way to a functional multi-tool stack in 2026. No single tool does everything well. The optimal configuration is a pipeline: one agent for deep reasoning, one for cost-efficient execution, one for automated quality enforcement, and a state machine to orchestrate them all. The terminal won as the agent runtime. DSSO wins as the agent harness. The only question is which agents you plug into it.