A library of progressively-complex, copy-paste-portable AI agent harness templates, written in TypeScript and organised as an Nx monorepo — one app per harness. Read them as a tutorial that builds from a barebones chat loop up to complex, service-exposed agents, or lift a single harness out as a starting point for a project.
See docs/product_requirements_document.md for the design
and tasks/todo.md for the build status.
Each harness adds one concept on top of the last. Every harness is built — each row links to its app.
Progress: 14 of 14 built — the ladder is complete (01–12, 20, 30).
| # | Harness | Concept | Status |
|---|---|---|---|
| 01 | chat-basic |
Streaming chat loop + TUI | ✅ built |
| 02 | chat-tools |
Tool calling (manual agentic loop) | ✅ built |
| 03 | chat-memory |
Model-curated long-term memory (memory.md) |
✅ built |
| 04 | rag-vector |
Vector RAG (local Ollama embeddings) | ✅ built |
| 05 | rag-graph |
Graph RAG (knowledge-graph extraction + traversal) | ✅ built |
| 06 | middleware |
Middleware pipeline + guardrails (industry-aligned, local) | ✅ built |
| 07 | mcp |
MCP client + server (stdio, all three primitives) | ✅ built |
| 08 | orchestration |
Multi-agent / subagents (orchestrator-workers, parallel) | ✅ built |
| 09 | multimodal |
Multimodal input — images + PDFs (vision/documents) | ✅ built |
| 10 | code-sandbox |
Code interpreter (Anthropic server-side sandbox) | ✅ built |
| 11 | computer-use |
Computer use (drives an isolated containerized desktop) | ✅ built |
| 12 | voice |
Voice chat (local STT/TTS, push-to-talk) | ✅ built |
| 20 | coding-agent |
A Claude-Code-like coding agent (tools, checkpoints, memory, subagent, MCP) | ✅ built |
| 30 | service-api |
Runs as a service — Next.js HTTP API + streaming chat UI (multi-provider) | ✅ built |
pnpm install
cp .env.example .env # then add your ANTHROPIC_API_KEYnx serve chat-basic # 01 — barebones streaming chat loop
nx serve chat-tools # 02 — tool calling
nx serve chat-memory # 03 — persistent memory + compaction
nx serve rag-vector # 04 — vector RAG (needs Ollama; see its README)
nx serve rag-graph # 05 — graph RAG (builds a knowledge graph on first run)
nx serve middleware # 06 — middleware pipeline + guardrails
nx serve mcp # 07 — MCP client + server (spawns the server over stdio)
nx serve orchestration # 08 — multi-agent orchestrator-workers (parallel subagents)
nx serve multimodal # 09 — attach images + PDFs and ask about them
nx serve code-sandbox # 10 — Claude writes and runs Python in a sandbox
nx serve computer-use # 11 — Claude drives an isolated desktop (needs Docker; build the image first)
nx serve voice # 12 — voice chat: tap space to talk (local STT/TTS; download the model first)
nx serve coding-agent # 20 — Claude-Code-like coding agent (tools + checkpoints + memory; --dir for a real repo)
nx serve service-api # 30 — Next.js service: streaming chat API + UI (multi-provider; http://localhost:3000)Harness 11 needs Docker and a one-time image build — see its
README (nx run computer-use:sandbox-build, then watch at
localhost:6080).
If a terminal-UI feature misbehaves under Nx, run the harness directly (same result, raw TTY):
pnpm tsx apps/01-chat-basic/src/main.tsapps/ one app per harness, numbered by complexity
01-chat-basic/ streaming chat loop + TUI
02-chat-tools/ tool calling
03-chat-memory/ model-curated long-term memory (memory.md)
04-rag-vector/ vector RAG over a local corpus (Ollama embeddings)
05-rag-graph/ graph RAG (knowledge-graph extraction + traversal)
06-middleware/ middleware pipeline + guardrails (input/output rails)
07-mcp/ MCP client + server (docs knowledge base over stdio)
08-orchestration/ multi-agent orchestrator-workers (parallel subagents)
09-multimodal/ multimodal input — attach images + PDFs, ask about them
10-code-sandbox/ code interpreter — Claude runs Python in Anthropic's sandbox
11-computer-use/ computer use — Claude drives an isolated containerized desktop (Docker)
12-voice/ voice chat — push-to-talk, local STT (whisper.cpp) + TTS (macOS say)
20-coding-agent/ Claude-Code-like coding agent — tools, shadow-git checkpoints, memory, subagent, MCP
30-service-api/ Next.js service — streaming chat HTTP API + web UI (multi-provider)
libs/
tui/ shared terminal kit (the only shared lib)
Assistant replies render as Markdown while they stream: each completed block (paragraph, list,
code fence) commits formatted and scrolls normally, while only the in-progress block repaints live
— headings, bold, lists, syntax-highlighted code. See libs/tui/src/stream.ts.
Each app is standalone apart from libs/tui: it carries its own src/client.ts
(an LLMClient interface + an Anthropic implementation) so you can lift it out and swap the
provider by editing one file. All harnesses default to claude-opus-4-8 with adaptive thinking
and streaming.
Two harnesses go further by design: 20-coding-agent adds runtime Claude / Ollama (local + cloud) /
OpenAI-compatible provider switching, and 30-service-api is a standalone Next.js app — its own
build, no libs/tui — because it's the "run as a service" harness rather than a terminal app.
- TypeScript ESM, run with
tsx(no build step for development). - The Anthropic SDK is used directly — every part of the agent loop is visible.
- Use the SDK's own types (
Anthropic.MessageParam,Anthropic.Message, …); never mock data.
Nx · pnpm · TypeScript (ESM) · tsx · @anthropic-ai/sdk · a tui kit built on
chalk / figlet / gradient-string / chalk-animation / nanospinner / @inquirer/prompts, with
Markdown rendering via marked / marked-terminal. Requires Node ≥ 22.
MIT — lift any harness out and use it freely.