pixie-pi
An autonomous, tool-using AI coding agent that runs in your terminal — as a single static Rust binary with no runtime dependencies.
pixie-pi reads, writes, and edits code, runs shell commands, searches your
codebase, and follows reusable skills — all streamed from an
Anthropic-compatible endpoint over a hand-rolled SSE decoder (no SDK). It ships
two modes: a one-shot command-line mode and an interactive REPL.
The agent core (SSE streaming, the double agent loop, tool execution, fuzzy edit
matching, LLM-summarizing compaction, skills) is a from-scratch reimplementation
written in the spirit of pi — see
Acknowledgments.
Highlights
- Single static binary. No
node_modules, no runtime, no supply-chain footprint. ~7 MB, cold-starts in ~3 ms (faster than an emptynode -e ""). - No Anthropic SDK. The Messages API, SSE streaming, fine-grained block events, thinking signatures, and tolerant streaming-JSON repair are all implemented directly.
- Seven tools —
read,write,edit,bash,grep,find,ls— with fuzzyeditmatching, unified diffs, process-group bash kills, and gitignore-aware search. - Claude Code–compatible skills. Drop a
SKILL.mdin.claude/skills/and the agent discovers and invokes it on demand (progressive disclosure). - LLM-summarizing compaction with model tiering. Long sessions are summarized to fit the context window — and summaries run on the cheap tier (haiku) by default, regardless of your main model.
- Prompt caching, adaptive/budget thinking, JSONL session persistence with
--continue/--resume.
The command is
pixie-pi. Tip:alias pi=pixie-piif you prefer a shorter invocation.
Requirements
- Rust 1.82+ (to build from source).
- An Anthropic-compatible endpoint. Set a key for the real API, or point at a gateway/proxy that speaks the Anthropic Messages API.
Install
Build from source
Configure credentials
pixie-pi reads the same environment variables Claude Code / the Anthropic SDK
use:
# Pick one auth method:
# sent as x-api-key
# export ANTHROPIC_AUTH_TOKEN=... # sent as Authorization: Bearer (takes precedence)
# Optional: point at a gateway / proxy / Anthropic-compatible endpoint:
# export ANTHROPIC_BASE_URL=https://api.anthropic.com
Quick start
# One-shot (command-line mode)
# Piped stdin is non-interactive
|
# NDJSON event stream (pixie's own event schema, for piping into other tools)
# Claude Code stream-json (drop-in for the `claude` CLI — see below)
# Interactive REPL
Inside the REPL (Ctrl-C interrupts the current run, Ctrl-D or /exit quits):
/help list slash commands
/model <id> switch model (sonnet | opus | haiku)
/thinking <lvl> off|minimal|low|medium|high|xhigh
/compact summarize old messages to fit the context
/tools list enabled tools
/context show estimated token usage
/cost show cumulative token usage + cost
/system show the system prompt
/clear clear the conversation
/exit quit
Conversations persist per-project as JSONL under $PIXIE_PI_AGENT_DIR (default
~/.config/pixie-pi/agent/sessions/<hash>/session.jsonl) and resume with
pixie-pi -c (--continue) or pixie-pi -r (--resume).
Tools
| Tool | Default | Description |
|---|---|---|
read |
on | Read a file (text or image), with offset/limit paging |
write |
on | Create or overwrite a file (creates parent dirs) |
edit |
on | Exact and fuzzy text replacement, multiple per call, with a unified diff |
bash |
on | Run a shell command (timeout, process-tree kill, tail-truncated output) |
grep |
off | Content search (regex/literal, context lines, respects .gitignore) |
find |
off | File glob search (respects .gitignore) |
ls |
off | Directory listing |
grep/find/ls are off by default — the model uses bash for searching
unless you enable them:
The edit tool accepts slightly-imprecise oldText: differences in trailing
whitespace, smart quotes, dashes, and special spaces (NFKC-folded) still match,
so the model rarely fails an edit over cosmetic whitespace.
Skills (Claude Code–compatible)
A skill is a directory <root>/<name>/SKILL.md, where <root> is
.claude/skills (project) or ~/.claude/skills (user). Project skills shadow
user skills of the same name. The SKILL.md has a small YAML frontmatter
(name, description) followed by markdown instructions:
name: deploy
description: Use when the user wants to deploy or ship the project
1. 2.3.
Only the name + description are surfaced up front; the body is loaded into
context only when the model invokes the skill tool (progressive disclosure).
Supporting files referenced by a skill live under its directory and are read with
the read tool. All registered tools remain callable while a skill runs (no
allowlist enforcement).
Context management
- Token estimate & budgeting. Each turn's usage is accumulated; the REPL shows context % and running cost after every turn.
- Auto-compaction. When the transcript nears the context limit (~80%),
pixie-pisummarizes the oldest messages (cut at a user-message boundary, so tool chains stay intact) and keeps the recent tail. It falls back to a plain drop if the summarizer is unavailable, so it never hard-fails. - Model tiering. Summaries run on the cheapest tier by default (
haiku), independent of your main model — so anopussession still compresses cheaply. Override withPIXIE_PI_COMPACT_MODEL=<sonnet|opus|haiku|…>.
Configuration
Environment variables
| Variable | Purpose |
|---|---|
ANTHROPIC_API_KEY |
API key (sent as x-api-key) |
ANTHROPIC_AUTH_TOKEN |
Bearer token (takes precedence over the API key) |
ANTHROPIC_BASE_URL |
Anthropic-compatible endpoint (default https://api.anthropic.com) |
PIXIE_PI_COMPACT_MODEL |
Model used for compaction summaries (default: cheapest tier) |
PIXIE_PI_AGENT_DIR |
Session/config directory (default ~/.config/pixie-pi/agent) |
NO_COLOR |
Disable ANSI colors |
CLI reference
pixie-pi [OPTIONS] [MESSAGE]...
Options:
-p, --print Non-interactive one-shot run
--mode <text|json> Output mode for print runs (default: text)
--output-format <text|stream-json> Claude Code stream-json NDJSON (drop-in for `claude`)
--input-format <text|stream-json> stream-json ⇒ persistent stdin multi-turn driver
--session-id <id> Claude-compatible session id
--permission-mode <mode> Accepted; resolves to allow-all (bypass)
--dangerously-skip-permissions Skip permission prompts (bypass)
--model <id> sonnet | opus | haiku (fuzzy-matched)
--provider <name> (default: anthropic)
--api-key <key> (default: $ANTHROPIC_API_KEY)
--system-prompt <text> Replace the system prompt entirely
--append-system-prompt <text> Append (repeatable)
--thinking <level> off|minimal|low|medium|high|xhigh
--max-tokens <n> Override the model output cap
--no-cache Disable Anthropic prompt caching
-c, --continue Continue the most recent session
-r, --resume Resume a session
--session <path|id> Use a specific session
--no-session Don't persist (ephemeral)
-t, --tools <a,b,c> Enable only these tools
--exclude-tools <a,b> Disable these tools
-n, --no-tools Disable all tools
--no-builtin-tools Disable built-in tools
--verbose Stream model thinking
-h, --help
-V, --version
@file arguments are inlined into the prompt: pixie-pi @notes.md "summarize this".
Claude Code stream-json compatibility
pixie-pi can be spawned in place of the claude CLI: it speaks Claude Code's
stream-json wire protocol, emitting system/assistant/user/result
NDJSON lines that callers (e.g. Pixie)
read off stdout until a result line ends each turn.
# One shot: one turn of stream-json output
# Persistent: multi-turn over one process — read {"type":"user",...} JSONL
# turns from stdin, emit a result line per turn, exit on stdin EOF
The mapper is a pure library function (pixie_pi::compat::map_events) with
no I/O, so SDK consumers can reuse it directly. Permission brokering is
bypass-only by design (matches the daily-driver path): every
--permission-mode and --dangerously-skip-permissions resolves to allow-all.
Unknown permission modes are accepted and treated as bypass rather than
rejected, so a caller's argv never errors. Interactive permission brokering is a
documented future extension — its hook point is already isolated at the
ToolGate in the agent loop.
Architecture
| Layer | Modules |
|---|---|
| AI / provider | src/ai/ — types, stream (SSE + tolerant streaming-JSON), anthropic |
| Agent loop | src/agent/ — agent_loop (double loop), context (events), tool (trait + gate) |
| Tools | src/tools/ — read/write/edit/bash/grep/find/ls/skill + truncate/edit_diff/util |
| Session / skills / prompt | src/session.rs, src/skills.rs, src/prompt.rs, src/config.rs |
Claude stream-json compat |
src/compat/ — pure AgentEvent → Claude NDJSON mapper (map_events, to_ndjson) |
| Library crate | src/lib.rs — public core + re-exports + prelude (the bin is a thin wrapper) |
| Entry / modes | src/main.rs, src/cli.rs, src/app.rs, src/modes/ (print, interactive, stream_json), src/render.rs |
The agent loop streams a response, executes tool calls (parallel by default,
sequential when a tool requests it), feeds results back, and repeats until the
model stops; abort propagates through a CancellationToken; prompt caching
attaches cache_control: ephemeral to the system prompt, last user message, and
final tool definition; adaptive-effort thinking for new models, budget-based for
older ones.
Performance
Because the harness is a compiled binary with no runtime, the non-LLM paths are
essentially free — so pixie-pi is well-suited to scripting, piping, and
resource-constrained setups (measured on macOS, release build):
| pixie-pi | Node node -e "" (floor) |
|
|---|---|---|
| Cold start (full app loaded) | ~2.8 ms | ~8 ms (empty, no modules) |
| Diff: 1-line edit in a 2000-line file | ~80 µs | — |
| Binary size | ~7 MB | node_modules (hundreds of MB) |
A real conversation is dominated by LLM latency, so this matters most for frequent CLI invocations, low-memory containers, and cold-start-sensitive environments — not for interactive chat responsiveness.
Development
The codebase is heavily commented: every non-trivial function carries a rationale note, and each correctness-sensitive path has a guarding test.
License
MIT © white1or1black. See LICENSE.
Acknowledgments
The agent core's algorithms — fuzzy edit matching, compaction, streaming-JSON
repair, truncation, and the overall agent-loop design — are from-scratch
reimplementations of those in pi by
Mario Zechner (earendil-works). This project is an independent reimplementation
written from scratch in a different language; it is not affiliated with, or
endorsed by, pi. pi's MIT license and copyright are reproduced in
THIRD_PARTY_NOTICES.md.