Architecture¶

Four ideas explain the design¶

1. The agent is replaceable. Everything shared lives outside the agent; adding one is a single config file in config/agents/, not a change to common code.
2. Knowledge is stored in tiers. Fast in memory, durable in LevelDB, reviewable as git-tracked JSON exports.
3. Enforcement happens before execution. Constraints are PreToolUse hooks, so a bad call is blocked rather than reported.
4. Supervision is layered. Watchdog, coordinator, verifier and service health escalate progressively instead of one monitor trying to catch everything.

Where things live¶

Read next¶

Health Monitoring for the supervision layers, Data Flow for how information moves between systems, and LLM Routing for how a model is chosen for a piece of work.

Agent-agnostic by construction¶

Claude Code, Copilot CLI, OpenCode and Pi all run on identical infrastructure. That is enforced structurally rather than by convention: the shared behaviour lives in layers none of the agents own.

From the outside in — the agent itself; a tmux wrapper providing the status bar, nesting guard and I/O capture; a per-agent config file of 10–30 lines; a shared orchestration script handling Docker detection, service startup and session management; and beneath those the shared services and a thin adapter interface resolved by naming convention.

The proof that the seam is real: config/agents/opencode.sh is 25 lines and buys full integration. Adding an agent touches nothing else.

Where knowledge is kept¶

Three tiers, chosen for different failure modes:

• Runtime — an in-memory Graphology graph, fast enough to query mid-session.
• Persistent — LevelDB, which survives restarts.
• Reviewable — JSON exports committed to git, so knowledge changes show up in diffs and can be reverted like anything else.

Enforcement happens before the tool runs¶

flowchart LR
    A[Agent tool call] --> B[PreToolUse hook]
    B --> C[Constraint monitor]
    C -->|Violation| D[BLOCK + suggested fix]
    C -->|Clean| E[ALLOW]
    E --> F[Tool executes]

Constraints are declarative — an id, a pattern, a severity and the message shown when they fire — and a blocked call can be overridden deliberately by naming the constraint, which keeps the escape hatch explicit and auditable rather than tempting you to reword around the rule.

Supervision in layers¶

Each layer assumes the one below it may be wrong, which is why a wedged process that still answers ps is caught — the layer above notices it has stopped producing work.

How it is deployed¶

Services run as HTTP/SSE endpoints in Docker containers; the host-side agent CLI reaches them through stdio proxies. coding --claude brings the whole stack up, so Docker must be running before you launch.

Adding an agent¶

Create config/agents/<name>.sh with AGENT_NAME, AGENT_COMMAND and any optional hook functions. Detection, launcher routing and tmux wrapping follow automatically. The Agent Integration Guide has the full contract.

System design principles and patterns for the coding infrastructure.

Key Principles¶

1. Agent-Agnostic Design¶

The architecture supports multiple AI coding assistants through a unified adapter pattern:

Layers:

1. Agent Layer - AI assistants (Claude Code, GitHub CoPilot, OpenCode, future agents)
2. Tmux Wrapper Layer - Unified session wrapping via tmux-session-wrapper.sh — status bar, nesting guard, env propagation, optional pipe-pane I/O capture
3. Config Layer - Agent definitions in config/agents/<name>.sh (10-30 lines each)
4. Orchestration Layer - launch-agent-common.sh handles all shared startup (Docker detection, service startup, monitoring, session management)
5. Common Setup Layer - Shared initialization (agent-common-setup.sh)
6. Shared Services - VKB, Semantic Analysis, Constraint Monitor, LSL
7. Adapter Layer - Abstract interface + agent implementations (dynamic import by convention)

2. Knowledge Persistence¶

Multi-tier storage for reliability and performance:

Runtime (Fast):

• MCP Memory (Claude)
• Graphology Graph (in-memory)

Persistence (Reliable):

• LevelDB (persistent graph storage)
• JSON exports (git-tracked)
• .coding/history/ (session logs)

3. Real-Time Quality Enforcement¶

PreToolUse hooks intercept tool calls BEFORE execution:

flowchart LR
    A[Claude Tool Call] --> B[PreToolUse Hook]
    B --> C[Constraint Monitor]
    C -->|Violation| D[BLOCK]
    C -->|Clean| E[ALLOW]
    E --> F[Tool Execution]

4. 4-Layer Monitoring¶

Progressive escalation for reliability:

Deployment¶

MCP servers run as HTTP/SSE services in Docker containers; the host-side Claude/Copilot CLI talks to them via lightweight stdio proxies. Docker Desktop must be installed and running. The stack is launched automatically by coding --claude. See the Docker Deployment Guide for container details.

Development Patterns¶

Constraint-Based Development¶

Define constraints before implementation:

constraints:
  - id: no-parallel-versions
    pattern: /(v\d+|enhanced|improved|new|fixed)_/
    severity: CRITICAL
    message: Never create parallel versions - edit originals

Agent Detection¶

const detector = new AgentDetector();
const available = await detector.detectAll();
// { claude: true, copilot: true }

const best = await detector.getBest();
// 'claude'

Knowledge Capture¶

# Auto-analysis from git commits and session logs
semantic workflow run wave-analysis --team coding

# Progress of the run it started
semantic workflow status

# Visualization
vkb

Adding New Agents¶

Adding a new agent requires only a single config file — zero changes to shared code.

Create config/agents/<name>.sh defining AGENT_NAME, AGENT_COMMAND, and optional hook functions. Agent detection, launcher routing, and tmux wrapping all happen automatically.

Proof: The OpenCode agent (config/agents/opencode.sh) is a 25-line file providing full integration.

See the Agent Integration Guide for the complete walkthrough, config reference, and API contract.

Related Documentation¶

• Health Monitoring - 4-layer architecture details
• Data Flow - System data flow diagrams
• Integrations - MCP server architectures