Anatomy
of an Agent.

If you walked into Varahi's office at 305, Delta Square last Saturday morning at ten o'clock, you would have found the kind of room India's AI scene rarely produces: fifteen serious builders, no panel, no powerpoint, just a long table, two agentic codebases on a screen, and a kettle that didn't stop steaming for the next three hours. This is what happened.

The room had no obvious centre of gravity. There were consultants who'd spent the last decade architecting enterprise software, cybersecurity engineers who think about agents the way locksmiths think about doors, full-stack developers shipping AI features into production, and a few founders quietly nursing larger plans. What pulled them into the same conversation wasn't a job title — it was a shared, unfinished question.

Everyone is shipping "agents." Very few people have actually read how a production-grade agentic system is wired.

The session was built around closing exactly that gap. Not with a lecture, not with a tutorial, but by reading two real agentic coding CLIs side by side — pi-mono, the open-source MIT-licensed monorepo by Mario Zechner, and Claude Code, Anthropic's official CLI assistant whose archived source has been the subject of much architectural curiosity in the AI engineering community. We didn't compare them to crown a winner. We compared them to extract the patterns that any serious agentic system has to solve.

The thirty minutes from 10:00 to 10:30 turned out to be the most underrated part of the morning. Builders walked in with chai and small plates of sandwiches, traded one-line introductions, and quickly found the people in the room they'd been Twitter-mutuals with for years. The crowd skewed senior and skewed honest — most introductions started with "I've been struggling with…" rather than "I've been building…", which set a tone of mutual problem-pooling that lasted right through to one o'clock.

By the time the first slide went up — well, the first video — every laptop in the room was already open and most attendees had cloned at least one of the two repos.

The session opened with Mario Zechner's "I Hated Every Coding Agent, So I Built My Own" — a thirty-minute talk that doubles as the design rationale for pi-mono. Zechner is the kind of engineer who'd rather show you a 200-line tool loop than tell you about agentic architecture, and the talk is structured exactly that way: here's what's broken with existing agents, here's the smallest thing that fixes it, here's the next-smallest thing.

The video wasn't there to be watched in the way a webinar gets watched — passively, in silence, with chat reactions. It was there to be discussed. Whenever someone in the room had a point worth making, the video paused and the conversation took over for a few minutes before it resumed. By the end of the half-hour, we'd covered the talk's core ideas with our own examples layered on top, which is exactly how a piece of source material should be used in a working session.

The phrase that anchored the rest of the day came out of one of these discussions:

An agent harness isn't the model. It's everything around the model that decides what the model gets to see, do, and remember.

Once that framing landed, the room had a shared vocabulary. The harness — the LLM client, tool loop, permission gate, context manager, event bus, UI layer, persistence — became the lens through which we looked at every line of code for the next two hours.

Parth Pandya walked us through his personal AI workspace — built on Obsidian, with a custom pi-driven CLI handling the agent layer, and a hybrid setup that uses local LLMs alongside an OpenAI Codex subscription for daily operations.

The setup runs a mix of personal and small company-level automations — note-taking, content workflows, a few internal task automations. What made the walkthrough useful for the room wasn't any single feature; it was the underlying philosophy the demo demonstrated:

Don't build agents to replace your work. Build a harness that makes your existing work compoundable.

A few patterns from the setup made it onto laptops in the room: Obsidian as the canonical knowledge surface; pi as the agent that reads and writes that surface; local models (running through pi's vLLM integration) for cheap, private, latency-sensitive operations; and a Codex subscription reserved for workloads that genuinely need frontier-model reasoning. That tiering — local for volume, frontier for depth — was a useful framing for anyone who'd been treating "the model" as a single-tier decision.

The first deep-read was led jointly by Anuj Nalawade and Dattatray Salunkhe, who walked the room through the pi-mono codebase from our session fork. They opened with the layered dependency graph and didn't move on until the room agreed on what each layer was for.

The four-layer stack

Anuj's framing of pi-mono's architecture was the clearest summary of the morning. The codebase is a monorepo of seven npm packages, but conceptually it's four layers, each with one job and one rule about what it doesn't know:

// pi-mono · the layered stack

pi-coding-agent  // composition root — the "pi" CLI
       │
       ▼
pi-agent-core    // Agent class, tool loop, event bus, AgentMessage
       │          // has NO UI knowledge
       ▼
pi-ai            // unified LLM API · 10+ providers
                  // has NO agent concepts

pi-tui           // generic terminal toolkit, used in parallel
                  // has NO LLM knowledge

The discipline of those negative constraints — pi-ai doesn't know what an agent is, pi-agent-core doesn't know what a UI is, pi-tui doesn't know what an LLM is — is what makes the codebase teachable. You can ship pi-ai inside any TypeScript project that just wants multi-provider LLM access. You can ship pi-agent-core inside a Slack bot, a web UI, or a CLI without rewriting it. The composition is what changes; the layers don't.

CLI vs TUI — the distinction we kept coming back to

One of the longer side-discussions started here. The room's reflex assumption was that "CLI" and "TUI" were the same thing. They aren't, and pi-mono's separation makes the difference operational rather than semantic.

This matters because pi treats them as output modalities of the same engine, not as separate products. The same Agent and event bus drives both — the only thing that changes is who consumes the event stream. InteractiveMode renders deltas through pi-tui; runPrintMode converts them to stdout; runRpcMode serialises them as JSON-RPC. One core, four faces.

Agent context — what the model actually sees

The most consequential conversation in the pi-mono walkthrough was about context. The room had been (politely) using "context" to mean three different things: the conversation history, the system prompt, and everything pi-coding-agent stitches into the LLM call before it goes out. Once Dattatray pulled that apart on the screen, the architecture clicked.

• Messages — AgentMessage, a superset of the LLM's user/assistant/toolResult shape, with declaration merging so any extension can add fields. Persisted as JSONL, one file per session per cwd.
• System prompt — assembled from a layered template engine. Project-level rules in AGENTS.md get stitched in; user settings, model profile, active skills, and current cwd state all contribute.
• Tool schemas — generated from each tool's TypeScript definition; only the active subset is shipped. Tools are added/removed at session boundaries, not mid-turn.
• Compaction — when the window starts to fill, compaction/ triggers a summarisation strategy that's swappable per session.

The takeaway most builders wrote down: "context" is not a thing — it's an assembly process. Understanding which strategy assembles which slice of context is half the battle of building a serious agent harness.

The pi advantage — said carefully

By the time we'd been inside pi-mono for forty-five minutes, the room had a clear picture of what pi gets right. We took pains to frame this as pi's advantages for a particular kind of builder, not as "pi beats Claude Code" — which would be both unfair and untrue depending on the use-case.

The rough consensus by 12:05 was that pi is the harness you build a product on top of. Claude Code is the product you reach for when you want everything wired up already. Both choices are legitimate; they're just different decisions about where the seams should be.

The Claude Code walkthrough was led by Avanish Jain and Suryabhan, who'd done the painstaking work of mapping a 1,900-file, 512,000-line codebase down to a teachable shape. The framing they opened with set the tone perfectly:

Claude Code is a React app in your terminal. Every piece of UI is a React component with hooks — it's just rendered to characters instead of pixels.

Four files do most of the work

The architecture brief Avanish brought to the room is worth quoting in full because it's a small marvel of compression. A 512,000-line codebase reduced to four files:

If you only have an hour to understand Claude Code, those four files are the hour. Everything else — the 40 tools, the 85 commands, the 80 hooks, the bridge layer, the coordinator, the skills — is layered around them.

The buildTool factory · uniformity as a discipline

The single design pattern that landed hardest with the room was the buildTool() factory. Every Claude Code tool — from BashTool to WebSearchTool to the multi-agent AgentTool — conforms to one shape:

export const MyTool = buildTool({
  name: 'MyTool',
  aliases: ['my_tool'],
  description: 'What this tool does',
  inputSchema: z.object({ param: z.string() }),

  // the work
  async call(args, context, canUseTool, parentMessage, onProgress) {
    return { data: result, newMessages: [...] }
  },

  // safety
  async checkPermissions(input, context) { /* … */ },
  isConcurrencySafe(input) { /* parallel-safe? */ },
  isReadOnly(input) { /* non-destructive? */ },

  // presentation
  prompt(options) { /* system-prompt injection */ },
  renderToolUseMessage(input, options) { /* UI for invocation */ },
  renderToolResultMessage(content, progress, options) { /* UI for result */ },
})

This is the discipline that lets the QueryEngine stay agnostic. The engine doesn't care what BashTool does or what WebFetchTool does — it dispatches every tool through the same shape, validates inputs against the same Zod schemas, runs them through the same permission gate, and renders results through the same UI hook. One factory, forty tools, zero special cases in the core loop.

Permissions as a first-class subsystem

The room spent ten minutes on src/hooks/toolPermission/ — the centralised gate that every tool call passes through before execution. Four modes:

• default — prompt the user on each potentially destructive operation.
• plan — show the full plan first, approve once, then execute.
• auto — an ML-based classifier decides when to ask.
• bypassPermissions — auto-approve everything (the dangerous one).

Combined with a wildcard rule language (Bash(git *), FileEdit(/src/*), FileRead(*)), this gives you a permission system that's expressive enough for a senior engineer and conservative enough for an enterprise rollout. Suryabhan made the point that this is one of the most under-discussed parts of Claude Code's design — most agent harnesses bolt permissions on as a guard rail; Claude Code treats them as first-class subsystem.

MCP, twice over

Claude Code is both an MCP client (consumes external tools) and an MCP server (exposes its own). This bidirectional posture is the architectural choice that makes it interoperable with the broader agent ecosystem — Cursor, Claude Desktop, custom orchestrators. Few harnesses are this honest about being part of a larger graph.

The build-time trick · feature flags that strip code

The detail that made the room laugh and then take notes was Bun's bun:bundle feature flag system. When VOICE_MODE is disabled at build time, the entire voice subsystem — every component, every hook, every dependency — is physically removed from the bundle. One codebase, many shipped variants.

import { feature } from 'bun:bundle'

if (feature('VOICE_MODE')) {
  // this entire block — and everything it imports —
  // is stripped from the binary when VOICE_MODE is off
  const voiceCommand = require('./commands/voice/index.js').default
}

This is how Anthropic ships a single source tree that compiles to internal-only builds, enterprise builds, public builds, and IDE-bridge-enabled builds. Most teams reach for monorepos to solve this. Claude Code reaches for compiler flags.

The compare-and-extract block was where the morning's reading paid off. Stripped of marketing and stripped of style, the two systems converge on a remarkably similar set of decisions:

The agent harness is settling. The seven concerns above are now standard. What's still open is which seams you expose to your application — and that's where the philosophical fork between pi and Claude Code matters most.

The session closed with Amit Chavan walking the room through spec-driven development — and specifically, why GitHub's spec-kit represents the right operating system for vibe coding in an agentic AI world.

The argument Amit made, distilled, was this: vibe coding — where you describe what you want and an agent builds it — fails the moment your codebase or your team grows beyond a certain threshold. Not because the agent gets worse at coding, but because the agent has no shared specification of what "right" means. Without a spec, every agent run is a re-discovery of intent. Spec-kit fixes this by making the spec a first-class, version-controlled artifact that the agent reads before it writes.

The four core concepts

Why this matters for agentic AI · the long view

The single most useful thing Amit said — the line a few people in the room wrote down verbatim — was about the relationship between specifications and trust:

An agent without a spec is an intern with confidence. An agent with a spec is a colleague with constraints. The specification is what turns "useful tool" into "trustworthy collaborator."

Spec-driven development matters for agentic AI for four reasons that compounded over the rest of the discussion:

1. 01 → Reproducibility. The same spec + the same model + the same constitution should produce equivalent outputs. Without specs, every agent run is non-deterministic in the worst way.
2. 02 → Reviewability. A reviewer can check "does this change match the spec" much faster than they can check "is this change correct in the absolute." Specs are the unit of code review when agents are involved.
3. 03 → Compoundability. Specs persist across agent runs and across model upgrades. When GPT-6 arrives, your specs still apply. Your prompt-engineered context-stuffing does not.
4. 04 → Multi-agent coordination. When two agents work on the same codebase, the spec is the only artifact they can both reference. Without it, you don't have collaboration — you have collision.

If pi-mono and Claude Code answer the question of how to build an agentic system, spec-kit and the spec-driven philosophy answer the question of what to build with one. The room's consensus by the close of the morning was that anyone shipping agentic AI to production in 2026 without a spec layer is shipping debt by another name.

One of the side-conversations — the kind that only happens in rooms small enough to interrupt — was about deploying AI models locally on mobile devices. Two surprisingly practical tools came up. Termux, the Android terminal emulator that's quietly become a serious mobile development environment, was the first; you can run pi-mono inside Termux on a sufficiently capable phone, with local Ollama models providing inference. Google's AI Edge Gallery was the second, alongside NVIDIA's catalog of optimized AI models for edge deployment. The combination — Termux for the harness, on-device inference for the model — is genuinely usable today for small agentic workflows that don't want to leave the phone.

None of this made the agenda. All of it ended up in three or four laptops by the end of the morning.

Reading is one thing. Building is the other. Here's the work to do — at your own pace, in your own week, before Session 02. The repos you'll need:

The exercise we sent everyone home with was deliberately small, because the point isn't to ship a product — it's to feel where the seams are.

# Quick-start scaffold (TypeScript + pi-ai)

mkdir my-agent && cd my-agent
npm init -y
npm install @mariozechner/pi-ai zod

# Then write ~100 lines that:
#  1. Define one tool with a Zod input schema
#  2. Stream a chat completion from any provider via pi-ai
#  3. Handle one tool_use → tool_result round-trip
#  4. Print streamed deltas to stdout
#  5. Loop until the model stops calling tools

# Reference: pi-mono/packages/pods/src/agent/main.ts
# That's a working ~150-line agent in one file.