AI Coding Harnesses: Architecture, Safety, and Pi

The model proposes the next move. The harness makes that move executable, bounded, observable, and recoverable. It is neither the model nor merely a chat interface: it is the control layer connecting the model, repository, terminal, permissions, and verification workflow.

Minimum Responsibilities

Layer	Responsibility
Loop	Alternate model turns, tool calls, results, and stopping conditions
Context	Select instructions, history, files, and retrieved evidence
Tools	Validate arguments, execute calls, and return structured results
Policy	Enforce scope, permissions, approvals, budgets, and safety boundaries
State	Preserve task progress, artifacts, and resumable checkpoints
Reliability	Handle timeouts, retries, idempotency, cancellation, and failures
Observability	Retain traces, logs, token/cost data, and tool evidence
Evaluation	Test outcomes on representative tasks instead of judging prose alone

An agent that merely loops until the model says “done” has orchestration, but not a dependable harness.

Evidence Boundary

The architectural responsibilities above are a synthesis. Pi behavior is checked against its documentation and source; the DeepSeek comparison remains attributed to the linked video. Those sources can establish a design or documented feature, not that one harness is more reliable or useful.

This note has a deliberate terminal-coding bias. It underrepresents IDE collaboration, browser/computer-use agents, non-English work, organizational governance, and non-coding automation. Use Evidence and Bias to interpret claims and the dated Coding Agent Evaluation for current product selection.

The Inner Control System

Three design notes make the control layer concrete:

• Agent loop patterns separates short in-session turns, fresh-context loops, implement–verify cycles, and evaluator–optimizer workflows. Every loop needs an external success predicate and hard budgets.
• Context engineering treats the model window as a changing working set while plans, evidence, and checkpoints remain durable outside the transcript.
• Tool contracts makes side effects, retries, approvals, and partial failures explicit instead of leaving the model to infer them from a function name.

These layers matter more for small local models: shorten iterations, narrow the tool set, return bounded output, and let deterministic checks decide whether another turn is justified.

Pi: A Programmable Minimal Harness

Pi describes itself as a minimal terminal coding harness. It keeps model calls, the agent loop, tool execution, branchable sessions, and the terminal interface in the core, then leaves workflow-specific behavior to composable resources. By default the model receives only read, write, edit, and bash. grep, find, and ls are also built-in tools, but must be selected explicitly or enabled by configuration.

Beyond the interactive TUI, Pi supports one-shot -p output, a JSON event stream, stdin/stdout RPC, and an SDK for embedding the agent in a Node.js application. Providers can be switched. Sessions are stored as branchable JSONL trees; /tree, /fork, /clone, and /compact cover in-file exploration, separate sessions, and context compression.

The Pi details below were checked on 2026-08-28 against the locally installed Pi 0.84.3 documentation. They are versioned product facts, not a permanent compatibility promise.

What Each Customization Layer Owns

Layer	Typical entry point	Good home for	Do not confuse it with
Project context	AGENTS.md, CLAUDE.md, .pi/SYSTEM.md	stable rules, path boundaries, acceptance commands	a plugin or sandbox
Prompt template	.pi/prompts/review.md → /review	a repeatable, parameterized starting prompt	an automatically executed workflow
Skill	.agents/skills/*/SKILL.md → /skill:name	on-demand procedures, scripts, and references	a permission boundary or separate process
Extension	.pi/extensions/*.ts	new tools, commands, event policy, UI, providers, and session behavior	an inherently safe “lightweight plugin”
Pi package	pi install ..., pi config	distribution of extensions, skills, prompts, and themes through npm, Git, or local paths	isolation or trusted signing
SDK / RPC	createAgentSession(), pi --mode rpc	embedding, tests, or cross-language process integration	a mandatory layer for ordinary repositories

Global resources normally live under ~/.pi/agent/; project resources live under .pi/ or .agents/skills/. A prompt expands text. A skill uses progressive disclosure, keeping only its name and description in default context. An extension changes harness behavior directly. Prefer a skill when the missing piece is a method, a prompt when it is reusable input, and an extension only when a new tool, event hook, or UI is actually required.

For Pi's verified request, Steering, Follow-up, compaction, and session flow, see Bounded Agent Loops. Session branches change the conversation seen by the model; they do not restore files on disk. The practical commands below remain here as an operator reference.

Extensions: Pi's Plugin Layer

An extension is a TypeScript module loaded directly by Pi. It can:

• register model-callable tools and user slash commands;
• hook model turns, tool calls and results, model changes, and session lifecycle events;
• block or rewrite dangerous calls and add protected paths or approval UI;
• customize compaction, session state, terminal components, and rendering;
• register providers, or implement MCP, subagents, plan mode, and sandbox integration.

The last item matters: examples or third-party packages can implement those capabilities, but they are not core defaults. A small core permits competing designs while making the installer responsible for their policy, maintenance, and recovery behavior.

Auto-discovered extensions go in ~/.pi/agent/extensions/ or a trusted project's .pi/extensions/; run /reload after changing them. Use pi -e ./extension.ts for a temporary experiment without installing it. A Pi package can distribute extensions, skills, prompts, and themes together:

pi install npm:@scope/package@1.2.3  # pin a version
pi install ./local-package -l        # project scope
pi list
pi config                            # enable or disable individual resources
pi update --extensions

Extensions execute arbitrary code with the current user's authority, and a skill may instruct the model to run bundled scripts. A package is therefore a distribution unit, not a security boundary. Read source and dependencies before installation, pin versions when useful, and enable only the resources the workflow needs.

Daily Use

An ordinary project does not need a large control plane on day one:

A small project may use only the files it needs:

• AGENTS.md for rules and acceptance commands;
• .pi/prompts/review.md for an optional short repeated prompt;
• .agents/skills/release/SKILL.md for an optional reusable procedure;
• .pi/extensions/policy.ts only when host-level policy requires code.

Common launch patterns:

cd my-project
pi --name "parser repair"             # interactive session
pi -c                                 # continue the latest session
pi --no-session -p "Summarize this repository"  # ephemeral one-shot

# Expose only read-only tools for a review
pi --no-session --tools read,grep,find,ls -p "Review the change"

# Skip discovery and load only the resource under test
pi --no-extensions -e ./.pi/extensions/policy.ts
pi --no-skills --skill ./.agents/skills/release/SKILL.md

The first interactive commands worth remembering are:

Command	Purpose
/model	switch the model
/name, /session	name the session and inspect its file, tokens, and cost
/tree	revisit a previous node and branch inside the same JSONL file
/fork, /clone	copy an earlier point or the active branch to a new session
/compact	lossy compression of old context; the full record remains in the session file
/reload	reload extensions, skills, prompts, themes, and context files
/skill:name, /template	load a skill explicitly or expand a prompt template

Safety Baseline

Pi's project trust decides whether project .pi settings, resources, and executable extensions are loaded. It is not a filesystem or network sandbox. Non-interactive modes do not show the built-in project-trust prompt, so automation must make an explicit --approve decision instead of permanently trusting arbitrary repositories by default.

A conservative starting point is:

1. inspect Git status, AGENTS.md, and the allowed write scope before trusting project resources;
2. use --tools read,grep,find,ls for review work, then widen the tool set only when writes are required;
3. run unfamiliar repositories or dangerous commands in a container or VM, leaving credentials, the Docker socket, and unrelated directories outside;
4. use --no-extensions, --no-skills, and related flags to construct a reproducible minimal resource set;
5. review and pin third-party packages, treating every extension as code with full user authority;
6. judge completion with tests, lint, diffs, and final process state rather than the model's claim that it is done.

This is Pi's central exchange with more productized harnesses: the core is smaller and more malleable, but safety policy and workflow quality do not appear automatically.

Pi and DeepSeek Harness: Who Carries the Complexity?

The Pi walkthrough and the DeepSeek Harness video describe systems that look similar at first. Both can switch models, connect tools, and add plugins. The more useful distinction is not feature count, but when complexity appears and who has to manage it.

Pi starts with a small core. If a user wants plan mode, subagents, MCP, or a specialized interface, they assemble that capability when it becomes useful. This keeps the default system understandable, but leaves compatibility, permissions, and maintenance with the user.

The DeepSeek Harness video starts from "Everything is a plugin." Models, tools, interfaces, and workflows share one composition surface. That can make repeated workflows easier to reuse across a team, while moving dependency, version, and debugging work into the plugin platform.

Neither approach removes complexity. Pi delays it and gives it to the person building the workflow; the design shown in the DeepSeek video concentrates more of it in the platform. For my current workflow, Pi should stay small. Only capabilities that recur and have already stabilized are worth turning into shared components. A unified plugin workbench becomes useful when those components are numerous enough to be difficult to maintain separately.

Product comparisons belong in Frontier

This page uses Pi and the DeepSeek Harness video as design cases. The dated cross-product matrix, selection advice, and replay protocol live in Choosing an AI Coding Agent, where they can be refreshed without changing the durable harness model.

Practical Design Order

1. Define the outcome and an external success check.
2. Expose the smallest useful tool set.
3. Separate read-only actions from writes and irreversible actions.
4. Preserve artifacts and evidence outside the conversational transcript.
5. Add time, token, retry, and concurrency limits.
6. Trace model turns and tool calls with sensitive-data controls.
7. Replay representative tasks before changing the default model, harness, or reasoning level.

The harness and workflow own quality gates; the model is replaceable. A stronger model may reduce retries, but it does not remove the need for evidence, permissions, and end-to-end checks. Fast-changing model and pricing choices belong in the dated Model & API Radar; current public test results and tool-specific failure modes live in the Coding Agent Evaluation.

Follow the reading route · Opened notes are remembered in this browser.