Pi Coding Agent Design Skill

This skill guides the creation and customization of LLM-based coding agents using the design principles from the Pi project. It covers session modeling, tool integration, deterministic interaction patterns, and minimalistic architecture for code assistants.

Core Workflow

Pi operates as a loop-based autonomous agent that iteratively runs an LLM on a structured session object. It strictly controls context, uses deterministic tools, and enforces opinionated design constraints for reproducibility and user trust.

1. Agent Loop Architecture

The agent operates in a deterministic REPL loop:

session → LLM → Thought → Tool Call → Result → Append → next LLM loop

Each turn includes:

• •Thought: LLM response with action and thought.
• •Tool Call: Executes the action (read, write, edit, bash, etc.).
• •Result: Output from tool is stored.
• •Session: Updated and passed to next round.

Use scripts/session_loop.ts (see bundled resources) to implement and replay session turns.

Session Modeling

Sessions are modeled as JSON state logs with messages, actions, results, and files. Everything Pi does is append-only, enabling full reproducibility and "time travel".

Example session structure

{
  "messages": [{ "role": "user", "content": "Create a Next.js app" }],
  "actions": [{ "tool": "bash", "input": "npx create-next-app@latest" }],
  "results": [{ "output": "...log output..." }],
  "files": [{ "path": "app/page.tsx", "content": "..." }]
}

Tools: Minimal and Deterministic

Pi supports a fixed set of tools. They are opinionatedly limited to reduce ambiguity and increase predictability:

Each tool returns a JSON output. Agent only emits tools; no "freeform" suggestions are allowed outside actions.

Tool usage is fully reproducible. Results are always added to session.

Context Engineering

Rather than stuffing transcripts, Pi carefully crafts prompts using only what’s needed:

• •Includes: system prompt, recent messages, files, past actions/results
• •Does not replay entire transcript — avoids stale or misaligned state

Prompt construction is deterministic and template-driven: See references/prompt_template.md for format.

Multi-Model Support

Pi supports multiple models (e.g. Claude, GPT-4) in the same session:

• •The session tracks which model generated each action
• •models/ folder defines capabilities and request builders for each model

This makes it easy to test behavior across models with the same input, enabling model ablation experiments or hybrid strategies.

Design Philosophy

Pi is intentionally opinionated and minimal. Its principles:

• •🧱 No plugins, no ambiguity – all tools are deterministic and pre-defined
• •🛤 Reproducibility over intelligence – session log can always be replayed
• •🧠 LLM is an agent, not a genie – structured actions > freeform outputs
• •🧹 Minimal prompt bloat – avoids runaway context
• •🤖 Composable and inspectable – sessions can be inspected, replayed, diffed, stored

Suggested Usage Patterns

Use this skill when:

• •Designing a new LLM coding agent with reproducible sessions
• •Creating tool-based agent loops for scripting or project generation
• •Needing a structured format for context control and multi-turn sessions
• •Wanting to integrate multiple models in the same session
• •Replaying or debugging agent outputs deterministically

Bundled Resources

• •scripts/session_loop.ts: Pi-style REPL loop runner
• •scripts/replay_session.ts: Reconstruct and replay full session
• •references/prompt_template.md: Base prompt template for context engineering
• •references/tools_spec.md: JSON specs for read, write, edit, bash, search

For example tool specs, see:

## Example Tool Format

```json
{
  "tool": "write",
  "input": {
    "path": "app/page.tsx",
    "content": "<tsx code here>"
  }
}