An Agent Harness is the software infrastructure surrounding a language model that enables it to perform actions.

The harness is responsible for:

• Building the model's context.
• Communicating with the LLM.
• Providing tools to the LLM.
• Executing requested tool calls.
• Returning tool results to the model.
• Managing conversations and sessions.
• Controlling the execution lifecycle.

The LLM provides reasoning capabilities.

The harness provides the environment in which that reasoning can be translated into actions.

A traditional chatbot generally follows this pattern:

flowchart LR
    A["User"] --> B["Prompt"]
    B --> C["LLM"]
    C --> D["Response"]

An AI coding agent adds an execution environment:

flowchart TD
    A["User"] --> B["Pi Agent"]
    B --> C["LLM"]
    C --> D{"Tool needed?"}
    D -->|Yes| E["Execute Tool"]
    E --> F["Return Result"]
    F --> C
    D -->|No| G["Final Response"]

Example:

Chatbot: "Here is Python code that calculates expenses."

Pi: "I created the Python files, executed the program, ran tests, and fixed an error."

The important difference is the ability to interact with an actual environment.

Minimalism:

• Keep the core relatively small.
• Avoid unnecessary abstractions.
• Build on existing operating system tools.

Extensibility:

• Create custom tools.
• Build extensions.
• Use reusable skills.
• Connect external services.

Model Independence:

• Use different LLM providers.
• Switch models within the same environment.
• Compare model behavior.

Transparency:

• Observe model responses.
• Inspect tool executions.
• Review modifications.
• Examine session history.

A basic Pi setup does not require:

• A vector database.
• A separate orchestration server.
• Kubernetes.
• Docker.
• A complex multi-agent framework.
• A custom backend application.

For a basic demo, a terminal, a supported LLM, and a local directory are sufficient.

flowchart TB
    USER["Developer"]

    subgraph PI["Pi Coding Agent"]
        UI["Terminal Interface"]
        CORE["Agent Runtime"]
        CONTEXT["Context Manager"]
        SESSION["Session Manager"]
        TOOLS["Tool Execution"]
        EXT["Extensions / Skills"]
        API["LLM API Abstraction"]
    end

    subgraph MODELS["LLM Providers"]
        OPENAI["OpenAI"]
        ANTHROPIC["Anthropic"]
        GOOGLE["Google"]
        LOCAL["Local Models"]
    end

    subgraph SYSTEM["Development Environment"]
        FILES["File System"]
        BASH["Shell"]
        GIT["Git"]
        TESTS["Tests"]
    end

    USER <--> UI
    UI <--> CORE

    CORE <--> CONTEXT
    CORE <--> SESSION
    CORE <--> TOOLS
    CORE <--> API

    EXT --> CORE

    API <--> OPENAI
    API <--> ANTHROPIC
    API <--> GOOGLE
    API <--> LOCAL

    TOOLS <--> FILES
    TOOLS <--> BASH
    TOOLS <--> GIT
    TOOLS <--> TESTS

This is a conceptual architecture, showing the major responsibilities rather than every internal dependency.

Pi is developed as a collection of TypeScript packages.

flowchart TD
    USER["Developer"]
    TUI["pi-tui"]
    CODING["pi-coding-agent"]
    CORE["pi-agent-core"]
    AI["pi-ai"]
    LLM["LLM Providers"]

    USER <--> TUI
    TUI <--> CODING
    CODING <--> CORE
    CORE <--> AI
    AI <--> LLM

    CODING --> FS["Tools"]
    CODING --> SESSION["Sessions"]
    CODING --> EXT["Extensions"]

The same agent infrastructure can also be used through non-interactive interfaces.

Example:

"Create a Python application that tracks expenses."

Pi receives this request through its terminal interface.

Before contacting the LLM, Pi prepares the context.

This can include:

• System instructions.
• User request.
• Active conversation history.
• Available tools.
• Project instructions from AGENTS.md.
• Skill descriptions.
• Relevant file content.
• Model configuration.

The active session branch determines which historical messages are included.

Pi sends the prepared request to the selected LLM provider.

The LLM can produce:

• Natural language text.
• Structured tool calls.
• A combination of both.

Example tool request:

Tool: write File: expenses.py Content: Python source code

The LLM does not directly write the file.

It requests that Pi execute the operation.

Pi receives the requested tool call.

The tool executor performs the action.

Examples:

• Read a file.
• Write a file.
• Modify code.
• Execute a shell command.

Pi then captures the result.

The output is returned to the agent runtime.

Example:

Tool: bash Command: python expenses.py

Result: Traceback: NameError …

The result becomes part of the context available to the LLM.

The LLM may decide to:

• Call another tool.
• Modify the code.
• Run additional tests.
• Provide a final answer.

Pi repeats the process while more execution is required.

This interaction is the foundation of agentic behavior.

Three responsibilities are separated:

1. LLM: Generates reasoning and proposes actions.
2. Agent Harness: Coordinates execution and manages context.
3. Tools: Perform operations in the environment.

This architecture is also fundamental to many other AI agent implementations.

Read file contents.

Example prompt:

"Read app.py and explain its structure."

Create or overwrite files.

Example prompt:

"Create a Python program that prints Hello TechHive."

Modify existing files.

Example prompt:

"Modify the program to accept a username."

Execute shell commands.

Example prompt:

"Run the program and display the result."

flowchart TD
    A["User: Fix the bug"]
    B["LLM analyzes request"]
    C["read: Inspect code"]
    D["edit: Fix code"]
    E["bash: Run tests"]
    F{"Tests pass?"}
    G["Final response"]

    A --> B
    B --> C
    C --> D
    D --> E
    E --> F
    F -->|No| B
    F -->|Yes| G

Additional built-in tools and extensions may be available depending on the version and configuration.

Context is the information supplied to the LLM for a model request.

It may include:

• Current user request.
• Conversation history.
• Tool results.
• System instructions.
• Project instructions.
• Skill descriptions.
• Referenced file content.

Pi does not automatically load every file in a repository into the LLM context.

It selects and assembles context based on the session and configured resources.

AGENTS.md is a project instruction file.

Example:

# Project Instructions

This project is for a coding-agent workshop.

Guidelines:
- Use Python.
- Prefer the standard library.
- Keep code simple.
- Write readable functions.
- Add tests for new features.
- Explain major changes.

These instructions help guide the agent's behavior within the project.

Pi maintains conversation sessions.

Sessions can include:

• User messages.
• Assistant messages.
• Tool calls.
• Tool results.
• Model changes.
• Context compaction events.

Persistent sessions use JSONL files.

Pi supports a tree-based conversation structure.

flowchart TD
    A["Start Session"]
    B["Create Application"]
    C["Add Data Storage"]

    D["CSV Approach"]
    E["SQLite Approach"]

    F["Test CSV"]
    G["Test SQLite"]

    A --> B
    B --> C
    C --> D
    C --> E
    D --> F
    E --> G

Branches allow exploration of alternative approaches from earlier conversation states.

Long conversations can exceed a model's context window.

Pi can summarize older context to reduce the amount of information sent in future model requests.

Command:

/compact

Compaction helps manage context size but can lose some details from older messages.

The original session entries can remain in the stored session history.

flowchart TD
    USER["Developer"]
    PI["Pi Agent"]
    API["Unified Model Interface"]

    USER --> PI
    PI --> API

    API --> A["OpenAI"]
    API --> B["Anthropic"]
    API --> C["Google"]
    API --> D["Local Model"]

Advantages:

• Flexibility.
• Model comparison.
• Provider choice.
• Cost optimization.
• Experimentation.

Model capabilities and compatibility can vary.

Project-specific instructions.

Reusable prompts for recurring activities.

Examples:

• Code review.
• Documentation.
• Test generation.
• Refactoring.

Reusable instructions and supporting resources for specialized workflows.

Examples:

• Python testing workflow.
• Deployment workflow.
• Documentation generation.
• API development.

TypeScript-based customization.

Extensions can:

• Define custom tools.
• Register commands.
• React to lifecycle events.
• Integrate external services.
• Customize interactive behavior.

MCP stands for Model Context Protocol.

It provides a standardized way for applications to access external tools and resources.

Modern Pi versions provide built-in MCP support.

Example integrations:

• GitHub.
• Databases.
• Internal applications.
• Remote services.

Launch the terminal interface.

pi

Execute a prompt and print its response.

pi -p "Explain Python decorators"

Stream structured agent events.

pi --mode json -p "Explain this project"

Control Pi using JSONL messages through standard input and output.

Embed Pi agent capabilities in TypeScript applications.

flowchart TD
    CORE["Pi Agent Runtime"]

    CORE --> A["Interactive TUI"]
    CORE --> B["Print / JSON"]
    CORE --> C["RPC"]
    CORE --> D["TypeScript SDK"]

    A --> E["Developer"]
    B --> F["Automation Scripts"]
    C --> G["External Application"]
    D --> H["Custom Agent Application"]

macOS / Linux:

curl -fsSL https://pi.dev/install.sh | sh

Windows PowerShell:

irm https://pi.dev/install.ps1 | iex

Alternative using npm:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

The npm installation requires Node.js 22.19 or newer.

Inside Pi:

/login

Select a supported provider and authenticate.

Then:

/model

Select the model you want to use.

Prompt:

Inspect the current directory.

Explain what files are present.

Do not modify anything.

Concept: File-system exploration and read operations.

Prompt:

Create a simple Python expense tracker.

Requirements:
- Add an expense.
- List expenses.
- Calculate total expenses.
- Store expenses in a CSV file.
- Use only the Python standard library.

Keep the implementation simple.

Concept: Code generation and file creation.

Prompt:

Run the application.

Create three example expenses.

Verify that the total is calculated correctly.

Concept: Shell execution and result observation.

Prompt:

Create unit tests using Python unittest.

Test expense creation and total calculation.

Run the tests and fix any errors.

Concept: Autonomous testing and iterative correction.

Prompt:

Add a feature to group expenses by category.

Display the total for each category.

Update the tests and run them.

Concept: Code modification and context retention.

Commands:

/session /tree /model

Concept: Session history, branching, and model switching.

Minimal, extensible coding-agent harness.

Strengths:

• Customization.
• Multiple LLM providers.
• Tool execution.
• Session management.
• Extensibility.

Coding agent with an integrated set of development tools and workflows.

Coding agent designed to work with codebases, terminal commands, and development workflows.

Frameworks for developing custom LLM applications and agentic workflows.

Pi is primarily a ready-to-use and extensible agent harness, rather than a general-purpose workflow-graph framework.