How to Build a Harness

A hands-on course that walks you through building a minimal coding agent (like pi) that talks to Anthropic Claude and edits your code — in ~400 lines of TypeScript.

Advanced English 20 chapters

claude agent-harness typescript anthropic tool-use

A hands-on course that walks you through building a minimal coding agent (like pi) that talks to Anthropic Claude and edits your code.

Inspired by:

How to Build an Agent (Amp, Go, ~300 lines)
The Emperor Has No Clothes (Mihail Eric, Python, ~200 lines)

Reference implementation: pi-mono · Provider: Anthropic Claude (anthropic-messages API) · Language: TypeScript / Node.js

Part 1 — The Mental Model

1. What Is a Harness?

Understand the loop: prompt → LLM → tool calls → results → repeat.

A harness is a program that:

Sends a user message to an LLM
The LLM replies — sometimes with text, sometimes with tool calls
Your program executes those tool calls (read a file, edit code, run a command)
The results are sent back to the LLM
Repeat until the LLM says “I’m done” (no more tool calls)

That’s the whole architecture. The LLM never touches your filesystem. It only asks for things to happen, and your code makes them happen.

Both reference blogs emphasize this: the core loop is ~100 lines. Everything else is tooling around it.

File: packages/agent/src/agent-loop.ts L155-232

async function runLoop(
  currentContext: AgentContext,
  newMessages: AgentMessage[],
  config: AgentLoopConfig,
  signal: AbortSignal | undefined,
  emit: AgentEventSink,
  streamFn?: StreamFn
): Promise<void> {
  let hasMoreToolCalls = true;

  while (hasMoreToolCalls || pendingMessages.length > 0) {
    // Stream assistant response
    const message = await streamAssistantResponse(currentContext, config, signal, emit, streamFn);
    newMessages.push(message);

    // Check for tool calls
    const toolCalls = message.content.filter((c) => c.type === "toolCall");
    hasMoreToolCalls = toolCalls.length > 0;

    if (hasMoreToolCalls) {
      const toolResults = await executeToolCalls(currentContext, message, config, signal, emit);
      for (const result of toolResults) {
        currentContext.messages.push(result);
        newMessages.push(result);
      }
    }
  }
}

The key insight: the inner loop continues while hasMoreToolCalls is true. Each iteration streams a response, checks if the LLM wants to use tools, executes them, and loops again.

Part 1 — The Mental Model

2. The Message Protocol

UserMessage, AssistantMessage, ToolResultMessage — the conversation wire format.

Every conversation is a flat array of three message types. This is the wire format between your harness and the LLM.

File: packages/ai/src/types.ts L194-223

export interface UserMessage {
  role: "user";
  content: string | (TextContent | ImageContent)[];
  timestamp: number;
}

export interface AssistantMessage {
  role: "assistant";
  content: (TextContent | ThinkingContent | ToolCall)[];
  api: Api;
  provider: Provider;
  model: string;
  usage: Usage;
  stopReason: StopReason;
  errorMessage?: string;
  timestamp: number;
}

export interface ToolResultMessage<TDetails = any> {
  role: "toolResult";
  toolCallId: string;
  toolName: string;
  content: (TextContent | ImageContent)[];
  isError: boolean;
  timestamp: number;
}

export type Message = UserMessage | AssistantMessage | ToolResultMessage;

A typical conversation flows: user → assistant(toolCall) → toolResult → assistant(toolCall) → toolResult → assistant(text).

The AssistantMessage.content array is the critical piece. It can contain:

TextContent — the model’s text response
ThinkingContent — extended thinking / reasoning (Claude’s chain-of-thought)
ToolCall — a request to execute a tool

File: packages/ai/src/types.ts L169-175

export interface ToolCall {
  type: "toolCall";
  id: string;
  name: string;
  arguments: Record<string, any>;
}

Each ToolCall has an id (unique per call), a name (which tool), and arguments (JSON the LLM generated). Your harness must match each ToolResultMessage.toolCallId back to the original ToolCall.id.

Part 1 — The Mental Model

3. The Model Object

How to describe a Claude model to your harness.

Before calling the API you need a Model object that describes which Claude model to use, its capabilities, and pricing.

File: packages/ai/src/types.ts L389-412

export interface Model<TApi extends Api> {
  id: string; // e.g., "claude-sonnet-4-20250514"
  name: string; // e.g., "Claude Sonnet 4"
  api: TApi; // "anthropic-messages"
  provider: Provider; // "anthropic"
  baseUrl: string; // "https://api.anthropic.com"
  reasoning: boolean; // true if model supports extended thinking
  input: ("text" | "image")[]; // input modalities
  cost: {
    input: number; // $/million tokens
    output: number;
    cacheRead: number;
    cacheWrite: number;
  };
  contextWindow: number; // e.g., 200000
  maxTokens: number; // e.g., 64000
}

For a minimal harness you hardcode one model:

const model: Model<"anthropic-messages"> = {
  id: "claude-sonnet-4-20250514",
  name: "Claude Sonnet 4",
  api: "anthropic-messages",
  provider: "anthropic",
  baseUrl: "https://api.anthropic.com",
  reasoning: true,
  input: ["text", "image"],
  cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
  contextWindow: 200000,
  maxTokens: 64000,
};

Part 2 — Talking to Claude

4. API Key & Client Setup

Read ANTHROPIC_API_KEY, create the SDK client.

The simplest path: read ANTHROPIC_API_KEY from the environment.

File: packages/ai/src/env-api-keys.ts L63-73

export function getEnvApiKey(provider: string): string | undefined {
  if (provider === "anthropic") {
    return process.env.ANTHROPIC_OAUTH_TOKEN || process.env.ANTHROPIC_API_KEY;
  }
  // ...other providers
}

Then create the Anthropic SDK client:

File: packages/ai/src/providers/anthropic.ts L622-637

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey,
  baseURL: model.baseUrl,
  dangerouslyAllowBrowser: true,
  defaultHeaders: {
    accept: "application/json",
    "anthropic-dangerous-direct-browser-access": "true",
    "anthropic-beta": "fine-grained-tool-streaming-2025-05-14",
  },
});

For your minimal harness, this is just:

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic(); // reads ANTHROPIC_API_KEY automatically

Part 2 — Talking to Claude

5. Streaming a Response

Send a prompt, stream text back token-by-token.

The core of talking to Claude: build params, call the streaming API, process SSE events.

File: packages/ai/src/providers/anthropic.ts L216-467

The production code handles thinking blocks, tool call JSON deltas, usage tracking, and error recovery. The minimal version is:

const anthropicStream = await client.messages.stream({
  model: "claude-sonnet-4-20250514",
  max_tokens: 8192,
  system: "You are a coding assistant.",
  messages: convertedMessages,
  tools: convertedTools,
  stream: true,
});

The stream emits these SSE event types (relevant to a minimal harness):

Event	Meaning
`message_start`	New response started
`content_block_start` (type `text`)	Text block starting
`content_block_start` (type `tool_use`)	Tool call starting
`content_block_delta` (`text_delta`)	Text chunk
`content_block_delta` (`input_json_delta`)	Tool arguments streaming
`content_block_stop`	Block finished
`message_delta`	Stop reason revealed

File: packages/ai/src/providers/anthropic.ts L285-441

for await (const event of anthropicStream) {
  if (event.type === "content_block_start") {
    if (event.content_block.type === "text") {
      // New text block
    } else if (event.content_block.type === "tool_use") {
      // New tool call -- capture id and name
    }
  } else if (event.type === "content_block_delta") {
    if (event.delta.type === "text_delta") {
      // Append text chunk to current block
    } else if (event.delta.type === "input_json_delta") {
      // Accumulate tool arguments JSON
    }
  } else if (event.type === "message_delta") {
    if (event.delta.stop_reason) {
      // "end_turn" -> stop, "tool_use" -> execute tools
    }
  }
}

Part 2 — Talking to Claude

6. The EventStream Class

A generic push-based AsyncIterable for streaming events.

pi wraps all streaming in a generic EventStream<T, R> that implements AsyncIterable. This lets any consumer use for await...of.

File: packages/ai/src/utils/event-stream.ts L4-66

export class EventStream<T, R = T> implements AsyncIterable<T> {
  private queue: T[] = [];
  private waiting: ((value: IteratorResult<T>) => void)[] = [];
  private done = false;

  push(event: T): void {
    if (this.done) return;
    const waiter = this.waiting.shift();
    if (waiter) {
      waiter({ value: event, done: false });
    } else {
      this.queue.push(event);
    }
  }

  end(result?: R): void {
    this.done = true;
    while (this.waiting.length > 0) {
      this.waiting.shift()!({ value: undefined as any, done: true });
    }
  }

  async *[Symbol.asyncIterator](): AsyncIterator<T> {
    while (true) {
      if (this.queue.length > 0) {
        yield this.queue.shift()!;
      } else if (this.done) {
        return;
      } else {
        const result = await new Promise<IteratorResult<T>>((resolve) => this.waiting.push(resolve));
        if (result.done) return;
        yield result.value;
      }
    }
  }
}

The pattern: producer calls push() to emit events, consumer uses for await (const event of stream). If the consumer is slower than the producer, events queue up. If the consumer is faster, it awaits via a Promise.

The specialized AssistantMessageEventStream extends this:

File: packages/ai/src/utils/event-stream.ts L68-82

export class AssistantMessageEventStream extends EventStream<AssistantMessageEvent, AssistantMessage> {
  constructor() {
    super(
      (event) => event.type === "done" || event.type === "error",
      (event) => {
        if (event.type === "done") return event.message;
        if (event.type === "error") return event.error;
        throw new Error("Unexpected event type");
      }
    );
  }
}

Part 3 — Tools: Giving the LLM Hands

7. Defining a Tool

The Tool interface: name, description, JSON schema.

Both reference blogs agree: you need 3–4 tools to build a working coding agent: read, edit/write, and optionally bash. pi ships 7 tools; the core 4 are read, bash, edit, write.

File: packages/coding-agent/src/core/tools/index.ts L110

export const codingTools: Tool[] = [readTool, bashTool, editTool, writeTool];

A tool is a name, a description (tells the LLM when/how to use it), and a JSON schema for its arguments.

File: packages/ai/src/types.ts L227-231

export interface Tool<TParameters extends TSchema = TSchema> {
  name: string;
  description: string;
  parameters: TParameters;
}

The agent layer adds execute:

File: packages/agent/src/types.ts L291-306

export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any> extends Tool<TParameters> {
  label: string;
  execute: (toolCallId: string, params: Static<TParameters>, signal?: AbortSignal) => Promise<AgentToolResult<TDetails>>;
}

pi uses TypeBox (@sinclair/typebox) for JSON Schema generation. The schema is defined as a TypeBox Type.Object, which is both a runtime JSON Schema object and a compile-time TypeScript type.

Part 3 — Tools: Giving the LLM Hands

8. The `read` Tool

Let Claude read files from disk.

Lets Claude see file contents. This is the most important tool — without it, the LLM is blind.

File: packages/coding-agent/src/core/tools/read.ts L17-21

const readSchema = Type.Object({
  path: Type.String({ description: "Path to the file to read (relative or absolute)" }),
  offset: Type.Optional(Type.Number({ description: "Line number to start reading from (1-indexed)" })),
  limit: Type.Optional(Type.Number({ description: "Maximum number of lines to read" })),
});

The execute function reads from disk, adds line numbers, and truncates large files:

// Minimal read tool implementation
async execute(_toolCallId, { path, offset, limit }) {
  const absolutePath = resolve(cwd, path);
  const buffer = await readFile(absolutePath);
  const content = buffer.toString("utf-8");
  // Add line numbers, truncate if needed
  return { content: [{ type: "text", text: numberedContent }] };
}

The Amp blog’s read_file is identical in spirit: read from disk, return as string. The pi version adds line numbering and truncation for production use.

Part 3 — Tools: Giving the LLM Hands

9. The `edit` Tool

Let Claude edit files with string replacement.

The blog posts converge on the same design: string replacement. Find oldText, replace with newText.

File: packages/coding-agent/src/core/tools/edit.ts L31-51

const replaceEditSchema = Type.Object({
  oldText: Type.String({
    description: "Exact text for one targeted replacement. Must be unique in the file.",
  }),
  newText: Type.String({ description: "Replacement text for this targeted edit." }),
});

const editSchema = Type.Object({
  path: Type.String({ description: "Path to the file to edit (relative or absolute)" }),
  edits: Type.Array(replaceEditSchema, {
    description: "One or more targeted replacements.",
  }),
});

pi’s edit tool supports batched edits (multiple replacements in one call), which is more powerful than the single-replacement version in the blog posts. The core logic is the same: read file → replace strings → write file.

Part 3 — Tools: Giving the LLM Hands

10. The `write` Tool

Let Claude create new files.

Creates new files or overwrites existing ones.

File: packages/coding-agent/src/core/tools/write.ts

const writeSchema = Type.Object({
  path: Type.String({ description: "Path to the file to write (relative or absolute)" }),
  content: Type.String({ description: "Content to write to the file" }),
});

The Amp blog combines write into edit_file (empty old_str = create file). pi separates them for clarity.

Part 3 — Tools: Giving the LLM Hands

11. The `bash` Tool

Let Claude run shell commands.

Lets Claude run arbitrary shell commands. This is optional but dramatically increases capability.

File: packages/mom/src/tools/bash.ts L18-34

const bashSchema = Type.Object({
  label: Type.String({ description: "Brief description of what this command does" }),
  command: Type.String({ description: "Bash command to execute" }),
  timeout: Type.Optional(Type.Number({ description: "Timeout in seconds (optional)" })),
});

The execute function spawns a child process and captures stdout/stderr:

execute: async (_toolCallId, { command, timeout }, signal?) => {
  const result = await exec(command, { timeout, signal });
  return {
    content: [{ type: "text", text: result.stdout + result.stderr }],
  };
};

With bash, the LLM can install packages, run tests, check git status — anything you can do in a terminal.

Part 4 — The Agent Loop

12. Converting Tools for the API

Translate your Tool[] into Anthropic's tools parameter.

Your internal Tool[] must be converted to Anthropic’s API format before each call.

File: packages/ai/src/providers/anthropic.ts L911-932

function convertTools(tools: Tool[]): Anthropic.Messages.Tool[] {
  return tools.map((tool) => {
    const schema = tool.parameters as { properties?: unknown; required?: string[] };
    return {
      name: tool.name,
      description: tool.description,
      input_schema: {
        type: "object",
        properties: schema.properties ?? {},
        required: schema.required ?? [],
      },
    };
  });
}

This is the bridge between TypeBox schemas (your side) and Anthropic’s JSON Schema format (API side). For your minimal harness, this is a direct mapping.

Part 4 — The Agent Loop

13. The Inner Loop

Stream response → check for tool calls → execute → feed results back → repeat.

This is the heart of the harness. The agent loop from pi:

File: packages/agent/src/agent-loop.ts L155-232

// Simplified from pi's runLoop()
while (true) {
  // 1. Stream assistant response
  const message = await streamAssistantResponse(context, config, signal);

  // 2. Check if LLM wants to use tools
  const toolCalls = message.content.filter((c) => c.type === "toolCall");

  if (toolCalls.length === 0) {
    // No tool calls -- LLM is done, break the loop
    break;
  }

  // 3. Execute each tool call
  for (const toolCall of toolCalls) {
    const tool = context.tools.find((t) => t.name === toolCall.name);
    const result = await tool.execute(toolCall.id, toolCall.arguments);

    // 4. Add tool result to conversation
    context.messages.push({
      role: "toolResult",
      toolCallId: toolCall.id,
      toolName: toolCall.name,
      content: result.content,
      isError: false,
      timestamp: Date.now(),
    });
  }

  // 5. Loop -- the LLM will see the tool results and decide what to do next
}

Compare with the Amp blog’s loop:

// Amp (Go) -- same structure
for _, content := range message.Content {
    switch content.Type {
    case "tool_use":
        // Execute tool, add result to conversation
    case "text":
        // Print response
    }
}
// If stop_reason == "tool_use", loop again

And Mihail Eric’s Python version:

# Mihail Eric -- same structure
while True:
    response = execute_llm_call(conversation)
    tool_invocations = extract_tool_invocations(response)
    if not tool_invocations:
        break  # No tools, done
    for name, args in tool_invocations:
        result = TOOL_REGISTRY[name](**args)
        conversation.append({"role": "user", "content": f"tool_result({result})"})

All three are the same loop. The LLM decides what to do, you execute it, feed the result back, repeat.

Part 4 — The Agent Loop

14. Tool Argument Validation

Validate LLM-provided arguments against your JSON schema.

The LLM generates JSON arguments. They might be malformed. Validate before executing.

File: packages/ai/src/utils/validation.ts L64-93

export function validateToolArguments(tool: Tool, toolCall: ToolCall): any {
  const validate = ajv.compile(tool.parameters);
  const args = structuredClone(toolCall.arguments);

  if (validate(args)) {
    return args; // Valid -- AJV may have coerced types
  }

  const errors = validate.errors?.map((err) => `  - ${err.instancePath || "root"}: ${err.message}`).join("\n");

  throw new Error(
    `Validation failed for tool "${toolCall.name}":\n${errors}\n\n` + `Received arguments:\n${JSON.stringify(toolCall.arguments, null, 2)}`
  );
}

pi uses AJV to compile TypeBox schemas into validators. When validation fails, the error message is sent back to the LLM as a ToolResultMessage with isError: true, so Claude can try again.

File: packages/agent/src/agent-loop.ts L491-493

const preparedToolCall = prepareToolCallArguments(tool, toolCall);
const validatedArgs = validateToolArguments(tool, preparedToolCall);

Part 4 — The Agent Loop

15. Stop Reasons & When to Loop

stop, toolUse, error, aborted — what each means.

The Anthropic API returns a stop_reason that tells you why the model stopped generating.

File: packages/ai/src/providers/anthropic.ts L934-954

function mapStopReason(reason: string): StopReason {
  switch (reason) {
    case "end_turn":
      return "stop"; // Model finished naturally
    case "max_tokens":
      return "length"; // Hit token limit
    case "tool_use":
      return "toolUse"; // Wants to call tools
    default:
      throw new Error(`Unhandled: ${reason}`);
  }
}

File: packages/ai/src/types.ts L192

export type StopReason = "stop" | "length" | "toolUse" | "error" | "aborted";

The loop decision:

StopReason	Action
`"toolUse"`	Execute tools, loop again
`"stop"`	Model is done, break the loop
`"length"`	Hit token limit, might need to continue
`"error"`	Something went wrong, stop
`"aborted"`	User cancelled, stop

File: packages/agent/src/agent-loop.ts L194-198

if (message.stopReason === "error" || message.stopReason === "aborted") {
  await emit({ type: "turn_end", message, toolResults: [] });
  await emit({ type: "agent_end", messages: newMessages });
  return; // Stop the loop
}

const toolCalls = message.content.filter((c) => c.type === "toolCall");
hasMoreToolCalls = toolCalls.length > 0; // Continue if tools requested

Part 5 — The System Prompt

16. Building the System Prompt

Tell Claude what tools it has, how to behave, what directory it's in.

The system prompt tells Claude what it is, what tools it has, and how to behave.

File: packages/coding-agent/src/core/system-prompt.ts L28-172

export function buildSystemPrompt(options: BuildSystemPromptOptions = {}): string {
  // Build tools list
  const tools = selectedTools || ["read", "bash", "edit", "write"];
  const toolsList = tools
    .filter((name) => !!toolSnippets?.[name])
    .map((name) => `- ${name}: ${toolSnippets![name]}`)
    .join("\n");

  let prompt = `You are an expert coding assistant operating inside pi, a coding agent harness.

Available tools:
${toolsList}

Guidelines:
${guidelines}`;

  // Add date and working directory
  prompt += `\nCurrent date: ${date}`;
  prompt += `\nCurrent working directory: ${promptCwd}`;

  return prompt;
}

For your minimal harness:

const systemPrompt = `You are a coding assistant. You can read, edit, and create files.

Available tools:
- read: Read a file from disk
- edit: Edit a file using string replacement
- write: Create or overwrite a file
- bash: Run a shell command

Current directory: ${process.cwd()}
Current date: ${new Date().toISOString().split("T")[0]}`;

Part 5 — The System Prompt

17. Project Context & Skills

Load AGENTS.md, skill files, and inject them into the prompt.

pi loads project-specific instructions from AGENTS.md files and skill files.

File: packages/coding-agent/src/core/system-prompt.ts L154-165

// Append project context files
if (contextFiles.length > 0) {
  prompt += "\n\n# Project Context\n\n";
  for (const { path: filePath, content } of contextFiles) {
    prompt += `## ${filePath}\n\n${content}\n\n`;
  }
}

File: packages/coding-agent/src/core/skills.ts L339-364

export function formatSkillsForPrompt(skills: Skill[]): string {
  const lines = [
    "\n\nThe following skills provide specialized instructions.",
    "Use the read tool to load a skill's file when the task matches.",
    "",
    "<available_skills>",
  ];
  for (const skill of skills) {
    lines.push("  <skill>");
    lines.push(`    <name>${skill.name}</name>`);
    lines.push(`    <description>${skill.description}</description>`);
    lines.push(`    <location>${skill.filePath}</location>`);
    lines.push("  </skill>");
  }
  lines.push("</available_skills>");
  return lines.join("\n");
}

For a minimal harness, you can skip skills entirely and just read AGENTS.md from the working directory if it exists.

Part 6 — From Loop to Agent

18. The Agent Class

Stateful wrapper: owns transcript, emits events, handles abort.

The raw loop is stateless. The Agent class wraps it with state: transcript history, streaming state, abort handling, event listeners.

File: packages/agent/src/agent.ts L158-207

export class Agent {
  private _state: MutableAgentState;
  private readonly listeners = new Set<(event: AgentEvent) => Promise<void> | void>();
  private readonly steeringQueue: PendingMessageQueue;
  private readonly followUpQueue: PendingMessageQueue;
  private activeRun?: ActiveRun;

  constructor(options: AgentOptions = {}) {
    this._state = createMutableAgentState(options.initialState);
    this.convertToLlm = options.convertToLlm ?? defaultConvertToLlm;
    this.streamFn = options.streamFn ?? streamSimple;
    // ...
  }

  /** Start a new prompt */
  async prompt(input: string): Promise<void> {
    if (this.activeRun) throw new Error("Already processing");
    const messages = this.normalizePromptInput(input);
    await this.runPromptMessages(messages);
  }

  /** Abort the current run */
  abort(): void {
    this.activeRun?.abortController.abort();
  }

  /** Subscribe to agent events */
  subscribe(listener: (event: AgentEvent) => void): () => void {
    this.listeners.add(listener);
    return () => this.listeners.delete(listener);
  }
}

The key design: Agent owns the message array and exposes it via state.messages. It creates an AbortController per run so you can cancel mid-stream. Event listeners let the UI react to streaming updates.

Part 6 — From Loop to Agent

19. Steering & Follow-ups

Inject messages mid-run, queue follow-up prompts.

pi lets you inject messages while the agent is running (steering) or after it finishes (follow-ups).

File: packages/agent/src/agent.ts L252-259

/** Queue a message to be injected after the current assistant turn finishes. */
steer(message: AgentMessage): void {
  this.steeringQueue.enqueue(message);
}

/** Queue a message to run only after the agent would otherwise stop. */
followUp(message: AgentMessage): void {
  this.followUpQueue.enqueue(message);
}

The loop checks for these between turns:

File: packages/agent/src/agent-loop.ts L216-225

pendingMessages = (await config.getSteeringMessages?.()) || [];
// If inner loop exhausted, check for follow-ups
const followUpMessages = (await config.getFollowUpMessages?.()) || [];
if (followUpMessages.length > 0) {
  pendingMessages = followUpMessages;
  continue; // Restart inner loop
}

For a minimal harness, you can skip steering entirely. Just read user input, run the loop, print the result.

Part 6 — From Loop to Agent

20. Putting It All Together

A working minimal harness in ~400 lines.

Here’s the architecture map from pi-mono’s packages to a minimal harness:

pi-mono Package	Role	Minimal Equivalent
`packages/ai`	LLM abstraction (multi-provider)	Direct `@anthropic-ai/sdk` calls
`packages/agent`	Agent loop, tool execution	Your ~100-line loop
`packages/coding-agent`	Tools, system prompt, TUI, extensions	Your 4 tools + simple prompt

Dependencies for your minimal harness:

{
  "dependencies": {
    "@anthropic-ai/sdk": "^0.52.0",
    "@sinclair/typebox": "^0.34.0"
  }
}

The minimal harness in ~400 lines:

Model config (~10 lines) — hardcoded Claude model object
Tool schemas (~40 lines) — TypeBox schemas for read, edit, write, bash
Tool implementations (~120 lines) — fs operations, child_process
API glue (~50 lines) — convert tools/messages to Anthropic format
Agent loop (~80 lines) — stream → check tools → execute → repeat
System prompt (~20 lines) — tell Claude what it can do
CLI wrapper (~80 lines) — readline, print responses, handle ctrl-c

The key files to study in pi-mono:

File	Why
`packages/ai/src/types.ts`	All type definitions
`packages/ai/src/providers/anthropic.ts`	How pi talks to Claude
`packages/ai/src/utils/event-stream.ts`	The streaming abstraction
`packages/agent/src/agent-loop.ts`	The agent loop
`packages/agent/src/agent.ts`	Stateful agent wrapper
`packages/coding-agent/src/core/tools/`	Tool implementations
`packages/coding-agent/src/core/system-prompt.ts`	System prompt construction

Summary

Concept	Blog Equivalent	pi-mono Reference
The Loop	Amp’s `Run()`, Mihail’s `run_coding_agent_loop()`	`packages/agent/src/agent-loop.ts` `runLoop()`
Message types	Anthropic SDK types	`packages/ai/src/types.ts` `Message` union
Tool definition	`ToolDefinition` struct / dict	`packages/ai/src/types.ts` `Tool` interface
Tool execution	`switch content.Type` / `TOOL_REGISTRY[name]`	`packages/agent/src/agent-loop.ts` `executeToolCalls()`
Read file	`ReadFile()` / `read_file()`	`packages/coding-agent/src/core/tools/read.ts`
Edit file	`EditFile()` / `edit_file()`	`packages/coding-agent/src/core/tools/edit.ts`
Stop reason check	`message.StopReason == "tool_use"`	`mapStopReason()` in `providers/anthropic.ts`
System prompt	Hardcoded string	`buildSystemPrompt()` in `core/system-prompt.ts`
Streaming	`client.Messages.New(...stream: true)`	`streamAnthropic()` in `providers/anthropic.ts`
Stateful agent	Not covered in blogs	`Agent` class in `packages/agent/src/agent.ts`