ai-harness/docs/00-overview.md

AI Coding Harness — Design Overview

A terminal AI coding harness written in Rust, modeled on opencode (engine, tools, permissions) and oh-my-opencode-slim (multi-agent orchestration), with one deliberate departure: agent behavior is defined entirely in config + markdown files, not hardcoded prompts.

Goals

• Interface v1: ratatui TUI. The core is a library with a serializable event stream, so a future HTTP server (SSE) + web client slots in without rearchitecting.
• Providers: GitHub Copilot (OAuth device flow), OpenAI (API key), Anthropic (API key). Hand-written HTTP clients — no SDK dependency — normalized to a single LlmEvent stream type.
• Multiagent: full orchestration in the oh-my-opencode-slim style — a task tool spawning subagent child sessions, background/parallel subagents, a job board injected into the orchestrator's context each turn, session reuse by alias, subagent depth limits. All agents (including the bundled defaults) are markdown definitions users can override, replace, or disable.
• Integrations: MCP client (stdio), LSP diagnostics after edits, markdown-defined slash commands and skills.
• Permissions: opencode-style rulesets {permission, pattern, action: allow|deny|ask} with last-match-wins wildcard evaluation and an async "ask" that blocks tool execution until the user replies in the TUI (once / always / reject).

Document map

Doc	Contents
01-architecture.md	Cargo workspace layout, crate boundaries, dependencies, domain model, event bus, channel topology
02-engine.md	The agent loop (outer/inner), permission engine, retry, doom-loop guard, cancellation, compaction seam
03-providers.md	Provider trait, wire codecs, Copilot/OpenAI/Anthropic specifics, auth flows and storage, cost accounting
04-multiagent.md	Agent definitions and registry, task tool, background jobs, job board, session reuse, depth limits
05-tools.md	Built-in tools, truncation, edit replacer strategy, permission keys
06-config.md	Config files, precedence, schema, agent/command/skill markdown loading
07-tui.md	Screen layout, event loop, streaming markdown rendering, modals, keybinds
08-storage.md	SQLite schema, storage actor, write cadence, session resume
09-integrations.md	MCP client, LSP diagnostics, commands and skills
10-milestones.md	Phased milestone plan, testing strategy, risks, reference files

Reference codebases

Findings in these documents come from direct exploration of:

• ~/repos/opencode — TypeScript, Effect-based. Core loop in packages/opencode/src/session/{prompt,processor}.ts, tools in packages/opencode/src/tool/, permissions in packages/opencode/src/permission/index.ts, providers in packages/opencode/src/plugin/{github-copilot,openai}/ and packages/llm/.
• ~/repos/oh-my-opencode-slim — opencode plugin. Orchestration in src/hooks/task-session-manager/, src/utils/background-job-board.ts; agent prompts in src/agents/*.ts.