calvana/README.md

pi-vs-cc

A collection of Pi Coding Agent customized instances. Why? To showcase what it looks like to hedge against the leader in the agentic coding market, Claude Code. Here we showcase how you can customize the UI, agent orchestration tools, safety auditing, and cross-agent integrations.

---

Prerequisites

All three are required:

Tool	Purpose	Install
Bun ≥ 1.3.2	Runtime & package manager	bun.sh
just	Task runner	brew install just
pi	Pi Coding Agent CLI	Pi docs

---

API Keys

Pi does not auto-load .env files — API keys must be present in your shell's environment before you launch Pi. A sample file is provided:

cp .env.sample .env   # copy the template
# open .env and fill in your keys

.env.sample covers the four most popular providers:

Provider	Variable	Get your key
OpenAI	OPENAI_API_KEY	platform.openai.com
Anthropic	ANTHROPIC_API_KEY	console.anthropic.com
Google	GEMINI_API_KEY	aistudio.google.com
OpenRouter	OPENROUTER_API_KEY	openrouter.ai
Many Many Others	***	Pi Providers docs

Sourcing your keys

Pick whichever approach fits your workflow:

Option A — Source manually each session:

source .env && pi

Option B — One-liner alias (add to ~/.zshrc or ~/.bashrc):

alias pi='source $(pwd)/.env && pi'

Option C — Use the just task runner (auto-wired via set dotenv-load):

just pi           # .env is loaded automatically for every just recipe
just ext-minimal  # works for all recipes, not just `pi`

---

Installation

bun install

---

Extensions

Extension	File	Description
pure-focus	extensions/pure-focus.ts	Removes the footer bar and status line entirely — pure distraction-free mode
minimal	extensions/minimal.ts	Compact footer showing model name and a 10-block context usage meter [###-------] 30%
cross-agent	extensions/cross-agent.ts	Scans .claude/, .gemini/, .codex/ dirs for commands, skills, and agents and registers them in Pi
purpose-gate	extensions/purpose-gate.ts	Prompts you to declare session intent on startup; shows a persistent purpose widget and blocks prompts until answered
tool-counter	extensions/tool-counter.ts	Rich two-line footer: model + context meter + token/cost stats on line 1, cwd/branch + per-tool call tally on line 2
tool-counter-widget	extensions/tool-counter-widget.ts	Live-updating above-editor widget showing per-tool call counts with background colors
subagent-widget	extensions/subagent-widget.ts	/sub <task> command that spawns background Pi subagents; each gets its own streaming live-progress widget
tilldone	extensions/tilldone.ts	Task discipline system — define tasks before starting work; tracks completion state across steps; shows persistent task list in footer with live progress
agent-team	extensions/agent-team.ts	Dispatcher-only orchestrator: the primary agent delegates all work to named specialist agents via dispatch_agent; shows a grid dashboard
system-select	extensions/system-select.ts	/system command to interactively switch between agent personas/system prompts from .pi/agents/, .claude/agents/, .gemini/agents/, .codex/agents/
damage-control	extensions/damage-control.ts	Real-time safety auditing — intercepts dangerous bash patterns and enforces path-based access controls from .pi/damage-control-rules.yaml
agent-chain	extensions/agent-chain.ts	Sequential pipeline orchestrator — chains multiple agents where each step's output feeds into the next step's prompt; use /chain to select and run
pi-pi	extensions/pi-pi.ts	Meta-agent that builds Pi agents using parallel research experts for documentation
session-replay	extensions/session-replay.ts	Scrollable timeline overlay of session history - showcasing customizable dialog UI
theme-cycler	extensions/theme-cycler.ts	Keyboard shortcuts (Ctrl+X/Ctrl+Q) and /theme command to cycle/switch between custom themes

---

Usage

Run a single extension

pi -e extensions/<name>.ts

Stack multiple extensions

Extensions compose — pass multiple -e flags:

pi -e extensions/minimal.ts -e extensions/cross-agent.ts

Use just recipes

just wraps the most useful combinations. Run just with no arguments to list all available recipes:

just

Common recipes:

just pi                     # Plain Pi, no extensions
just ext-pure-focus         # Distraction-free mode
just ext-minimal            # Minimal context meter footer
just ext-cross-agent        # Cross-agent command loading + minimal footer
just ext-purpose-gate       # Purpose gate + minimal footer
just ext-tool-counter       # Rich two-line footer with tool tally
just ext-tool-counter-widget # Per-tool widget above the editor
just ext-subagent-widget    # Subagent spawner with live progress widgets
just ext-tilldone           # Task discipline system with live progress tracking
just ext-agent-team         # Multi-agent orchestration grid dashboard
just ext-system-select      # Agent persona switcher via /system command
just ext-damage-control     # Safety auditing + minimal footer
just ext-agent-chain        # Sequential pipeline orchestrator with step chaining
just ext-pi-pi              # Meta-agent that builds Pi agents using parallel experts
just ext-session-replay     # Scrollable timeline overlay of session history
just ext-theme-cycler       # Theme cycler + minimal footer
just all                    # Open every extension in its own terminal window

The open recipe allows you to spin up a new terminal window with any combination of stacked extensions (omit .ts):

just open purpose-gate minimal tool-counter-widget

---

Project Structure

pi-vs-cc/
├── extensions/          # Pi extension source files (.ts) — one file per extension
├── specs/               # Feature specifications for extensions
├── .pi/
│   ├── agent-sessions/  # Ephemeral session files (gitignored)
│   ├── agents/          # Agent definitions for team and chain extensions
│   │   ├── pi-pi/       # Expert agents for the pi-pi meta-agent
│   │   ├── agent-chain.yaml # Pipeline definition for agent-chain
│   │   ├── teams.yaml   # Team definition for agent-team
│   │   └── *.md         # Individual agent persona/system prompts
│   ├── skills/          # Custom skills
│   ├── themes/          # Custom themes (.json) used by theme-cycler
│   ├── damage-control-rules.yaml # Path/command rules for safety auditing
│   └── settings.json    # Pi workspace settings
├── justfile             # just task definitions
├── CLAUDE.md            # Conventions and tooling reference (for agents)
├── THEME.md             # Color token conventions for extension authors
└── TOOLS.md             # Built-in tool function signatures available in extensions

---

Orchestrating Multi-Agent Workflows

Pi's architecture makes it easy to coordinate multiple autonomous agents. This playground includes several powerful multi-agent extensions:

Subagent Widget (/sub)

The subagent-widget extension allows you to offload isolated tasks to background Pi agents while you continue working in the main terminal. Typing /sub <task> spawns a headless subagent that reports its streaming progress via a persistent, live-updating UI widget above your editor.

Agent Teams (/team)

The agent-team orchestrator operates as a dispatcher. Instead of answering prompts directly, the primary agent reviews your request, selects a specialist from a defined roster, and delegates the work via a dispatch_agent tool.

• Teams are configured in .pi/agents/teams.yaml where each top-level key is a team name containing a list of agent names (e.g., frontend: [planner, builder, bowser]).
• Individual agent personas (e.g., builder.md, reviewer.md) live in .pi/agents/.
• pi-pi Meta-Agent: The pi-pi team specifically delegates tasks to specialized Pi framework experts (ext-expert.md, theme-expert.md, tui-expert.md) located in .pi/agents/pi-pi/ to build high-quality Pi extensions using parallel research.
  • Web Crawling Fallbacks: To ingest the latest framework documentation dynamically, these experts use firecrawl as their default modern page crawler, but are explicitly programmed to safely fall back to the native curl baked into their bash toolset if Firecrawl fails or is unavailable.

Agent Chains (/chain)

Unlike the dynamic dispatcher, agent-chain acts as a sequential pipeline orchestrator. Workflows are defined in .pi/agents/agent-chain.yaml where the output of one agent becomes the input ($INPUT) to the next.

• Workflows are defined as a list of steps, where each step specifies an agent and a prompt.
• The $INPUT variable injects the previous step's output (or the user's initial prompt for the first step), and $ORIGINAL always contains the user's initial prompt.
• Example: The plan-build-review pipeline feeds your prompt to the planner, passes the plan to the builder, and finally sends the code to the reviewer.

---

Safety Auditing & Damage Control

The damage-control extension provides real-time security hooks to prevent catastrophic mistakes when agents execute bash commands or modify files. It uses Pi's tool_call event to intercept and evaluate every action against .pi/damage-control-rules.yaml.

• Dangerous Commands: Uses regex (bashToolPatterns) to block destructive commands like rm -rf, git reset --hard, aws s3 rm --recursive, or DROP DATABASE. Some rules strictly block execution, while others (ask: true) pause execution to prompt you for confirmation.
• Zero Access Paths: Prevents the agent from reading or writing sensitive files (e.g., .env, ~/.ssh/, *.pem).
• Read-Only Paths: Allows reading but blocks modifying system files or lockfiles (package-lock.json, /etc/).
• No-Delete Paths: Allows modifying but prevents deleting critical project configuration (.git/, Dockerfile, README.md).

---

Extension Author Reference

Companion docs cover the conventions used across all extensions in this repo:

• COMPARISON.md — Feature-by-feature comparison of Claude Code vs Pi Agent across 12 categories (design philosophy, tools, hooks, SDK, enterprise, and more).
• RESERVED_KEYS.md — Pi reserved keybindings, overridable keys, and safe keys for extension authors.
• THEME.md — Color language: which Pi theme tokens (success, accent, warning, dim, muted) map to which UI roles, with examples.
• TOOLS.md — Function signatures for the built-in tools available inside extensions (read, bash, edit, write).

---

Hooks & Events

Side-by-side comparison of lifecycle hooks in Claude Code vs Pi Agent.

Category	Claude Code	Pi Agent	Available In
Session	SessionStart, SessionEnd	session_start, session_shutdown	Both
Input	UserPromptSubmit	input	Both
Tool	PreToolUse, PostToolUse, PostToolUseFailure	tool_call, tool_result, tool_execution_start, tool_execution_update, tool_execution_end	Both
Bash	—	BashSpawnHook, user_bash	Pi
Permission	PermissionRequest	—	CC
Compact	PreCompact	session_before_compact, session_compact	Both
Branching	—	session_before_fork, session_fork, session_before_switch, session_switch, session_before_tree, session_tree	Pi
Agent / Turn	—	before_agent_start, agent_start, agent_end, turn_start, turn_end	Pi
Message	—	message_start, message_update, message_end	Pi
Model / Context	—	model_select, context	Pi
Sub-agents	SubagentStart, SubagentStop, TeammateIdle, TaskCompleted	—	CC
Config	ConfigChange	—	CC
Worktree	WorktreeCreate, WorktreeRemove	—	CC
System	Stop, Notification	—	CC

Resources

Pi Documentation

Doc	Description
Mario's Twitter	Creator of Pi Coding Agent
README.md	Overview and getting started
sdk.md	TypeScript SDK reference
rpc.md	RPC protocol specification
json.md	JSON event stream format
providers.md	API keys and provider setup
models.md	Custom models (Ollama, vLLM, etc.)
extensions.md	Extension system
skills.md	Skills (Agent Skills standard)
settings.md	Configuration
compaction.md	Context compaction

Master Agentic Coding

Prepare for the future of software engineering

Learn tactical agentic coding patterns with Tactical Agentic Coding

Follow the IndyDevDan YouTube channel to improve your agentic coding advantage.