Pi Crystal is a fork of the Pi agent harness (earendil-works/pi). It grew out of running Pi against local models (llama-server) in long iterative sessions, and the changes reflect that: copying multiline text out of the terminal stays free of whitespace padding, compaction keeps the provider KV cache valid as much as possible, and every message in the session, including thinking blocks, can be edited, forked, or continued at will.
/edit [N | substring | swipe [N]]loads messages into the editor as<pi_edit>blocks (an XML-like form that preserves reasoning blocks and tool calls; inner tags need no escaping, the parser figures out the structure around them, so copying and pasting stays easy). Sending the blocks rewrites history without calling the model. Editing the latest message creates a new swipe version instead of replacing it in place; older messages are edited in place./edit swipe [N]edits a specific swipe version in place via<pi_swipe>blocks, never creating a version and never changing its position./copy [N | substring | text]copies the last message, an indexed message, every message matching a substring, or arbitrary typed text./delete [N | substring | swipe [N]]soft-deletes the last N deletable units of the visible context - each tool result, each tool call (removed while keeping the message and its text), the message itself once no tool calls remain, and each compaction boundary, which un-compacts the summarized range - keeping them recoverable in the session file. A substring targets a single message./delete swipe [N]marks the selected swipe versions deleted./restore [N | swipe [N]]brings back soft-deleted units (latest deletion first) or deleted swipes of the current context./shred [N | substring | swipe [N]]removes the same units permanently with no undo./fork [N | substring]branches the session from any message, user or assistant./continueresumes generation without adding a user message. It can also continue a partial assistant message (prefill continuation), even mid-thought, on supported OpenAI-completions providers: currently llama.cpp-f3zz1k-prefill, which adds the prefill API and also resumes interrupted tool calls. An aborted or edited trailing message is picked up as a prefill continuation candidate./swiperegenerates the latest response (the only regeneration entry point) and navigates its versions:/swipe Ngoes to version N,/swipe +N//swipe -Njump relative,/swipe prev//swipe nextstep by one. The reasoning block, content block, and all related tool calls count as one message; versions root at assistant entries that share the same parent./swipe list [section] [selector] [+chars]prints a summary (first chars of reasoning and content, onename(args)line per tool call; section iscontent,reasoning, ortool, and the char count defaults to theswipeSummaryCharssetting), and/swipe search|isearch [selector] "string" [charspec]finds matches across reasoning, content, and tool call arguments. Selectors are comma-separated integers,a-branges, and-N./schedulesends a message later: with no parameters it fires after the current task completes; it can also fire after N messages, after a duration (1h 30m), at a local time, or as a delayed continue or edit+continue.-Ncancels./heartbeatsends a message or continue repeatedly: every duration (3h) or daily at a local time (15:23).list(or no arguments) lists entries with time left or paused,cancel <id>cancels one,pause/continuetoggle,save/loadpersist to and restore from HEARTBEAT.md,-Ncancels the last N./compactcompacts the session. Parameters set the budget as the number of recent messages to keep or as tokens (10,20K,1M; when both apply, the smaller budget wins), plus optional free-text focus for the summary. A/compactqueued during streaming runs at the turn boundary, andcancelcancels a queued or in-progress compact.
Retries are unlimited by default for prompts, /continue, /compact, and auto-compaction, with exponential backoff capped at 30 seconds, so when the model server goes down Pi Crystal keeps retrying and continues the turn once it is back, local or remote. When the server dies mid-stream, prefill continuation of the interrupted response takes priority over queued steering messages, and with llama.cpp-f3zz1k-prefill an echo check verifies the provider actually continued the same text before trusting it.
The summarization request carries exactly what the chat contains - system prompt plus unaltered history, with any previous summary in its natural position - minus only the preserved tail, plus the instruction at the end, so provider KV caches stay valid across compactions. The summary becomes a normal user/assistant message pair at the cut point, followed by the kept messages. Ctrl+O on a compaction summary shows the full model-visible context, and a failed or cancelled compaction restores the kept messages.
Rendered lines carry only their own content: no padding by default and no inserted line breaks, so copying multiline text with the mouse produces exactly what was written, and code blocks render verbatim. The upstream look is one setting away: padLines (full-width padding), wrapLines (wrap with newlines at the terminal width), messageBackground, and messageSeparator.
The footer shows the session's token usage and context state on the status line. Each item reads as follows: ↑ is total input tokens, ↓ total output tokens, R prompt-cache read tokens, W prompt-cache write tokens, CH the latest prompt-cache hit rate, and $ the estimated cost. The context indicator shows the current context over the model's context window with the percentage, e.g. 89k/256k (34.7%), so the current context length is directly readable; ? means the count is unknown (e.g. right after compaction, before the next response). The k/M suffixes divide by the tokenCountBase setting (default 1024, matching model context windows: a 256K window renders as 256k; set it to 1000 for decimal), which can be changed in /settings.
The $ cost is computed from the model's per-million-token rates, so it stays absent (no $) for local models unless you give them a cost. To track energy or hardware cost for a local model, set its cost in ~/.pi/agent/models.json; for example { "input": 1, "output": 3, "cacheRead": 0.1, "cacheWrite": 0.5 } sets rates in dollars per million tokens, with an optional tiers array for cheaper rates above an inputTokensAbove threshold. See packages/coding-agent/docs/models.md for the full schema.
The default system prompt is a factual reference: a tool inventory and the documentation locations. The effective system prompt and skill set are saved with each session and restored verbatim on resume, so the model's prefill cache survives edits to APPEND_SYSTEM.md; pass --update-system-prompt to force a rebuild from current files. /update [all|system-prompt|skills] reloads the prompt and/or skills from current files, and /system-prompt shows, sets, or clears it. Compaction and summary prompts use neutral direction labels (INCOMING/OUTGOING/TOOL). The incomingMessagePrefix setting prepends text to each user message when it is sent to the model; the session file keeps the typed text.
Cloud providers work by default exactly as upstream (same API keys and /login flows). To hide them from the model list for a local-only setup, set PI_DISABLE_CLOUD_PROVIDERS=1. The retry backoff cap is retry.maxBackoffMs (default 30000, i.e. 30 seconds).
Pi Crystal started as a personal project for myself and my wife, tuned for long sessions on local models. When some people on Reddit showed interest in /edit and the other slash commands, I decided to share it. You are welcome to use the code for any purpose, including upstreaming any parts into Pi itself if you find them useful. Issues and pull requests are welcome.
- Read the documentation - most of it still applies to Pi Crystal, except the fork features described above; you can also ask the agent to explain itself
- Visit pi.dev - website of the project Pi Crystal is forked from, big thanks to the original author for making Pi open source
| Package | Description |
|---|---|
| @earendil-works/chord | Typed host runtime for hot-reloadable plugins, contracts, replicated state, and RPC over JSON links |
| @earendil-works/pi-telemetry | Vendor-neutral telemetry contracts, reference adapter, conformance tests, and typed schemas |
| @earendil-works/pi-ai | Unified multi-provider LLM API (OpenAI, Anthropic, Google, etc.) |
| @earendil-works/pi-durable | Durable conversation, task, and document runtime |
| @earendil-works/pi-agent-core | Agent runtime with tool calling and state management |
| @earendil-works/pi-coding-agent | Interactive coding agent CLI |
| @earendil-works/pi-tui | Terminal UI library with differential rendering |
| @earendil-works/pi-env | Remote execution environments and SSH daemon transport |
The repo also carries internal workspace packages not in the table: packages/client, packages/protocol, packages/server, packages/orchestrator, packages/session-backends, and packages/evals. For Slack/chat automation see earendil-works/pi-chat.
This fork retains the agent harness, Node and experimental subpath exports and the client/protocol/server/SQLite workspace stack removed from upstream releases. These consumers migrate to the current Chord contracts/hosts API rather than retaining the obsolete Chord services implementation. Package versions follow the merged upstream release; fork-specific functionality remains described above.
Imported released changelog sections describe upstream releases. Fork retention described here takes precedence where upstream removed experimental surfaces. Crystal also retains its configured summary output/reserve budgets and visible foreign-reasoning replay as text; adopting upstream release metadata does not remove those behaviors.
Pi Crystal, just like the mainline Pi, does not include a built-in permission system for restricting filesystem, process, network, or credential access. By default, it runs with the permissions of the user and process that launched it.
If you need stronger boundaries, containerize or sandbox Pi. See packages/coding-agent/docs/containerization.md for three patterns:
- Gondolin extension: keep
piand provider auth on the host while routing built-in tools and!commands into a local Linux micro-VM. - Plain Docker: run the whole
piprocess in a local container for simple isolation. - OpenShell: run the whole
piprocess in a policy-controlled sandbox.
See CONTRIBUTING.md for contribution guidelines and AGENTS.md for project-specific rules. Longer term plans for Pi can also be found in RFCs.
npm install --ignore-scripts # Install all dependencies without running lifecycle scripts
npm run build # Refresh model data, then build all packages
npm run build:offline # Rebuild using existing model data without network access
npm run check # Lint, format, and type check
./test.sh # Run tests (skips LLM-dependent tests without API keys)
./pi-test.sh # Run pi from sources (can be run from any directory)./test.sh isolates credentials and leaves paid-provider E2E tests disabled. Explicit PI_DISABLE_CLOUD_PROVIDERS=0 ./test.sh enables bundled catalog metadata; the final === TOTAL === includes Node and Vitest results.
Direct AI-package E2E runs require PI_E2E_TESTS=1. With the catalog flag unset, this opt-in also enables bundled provider catalogs so model probes are registered. Explicit catalog settings remain authoritative. Offline collection regressions deny network access and collect credential-free probes without executing them.
Build every public package into one coherent local artifact set:
npm run pack:packages -- --out .artifacts/pi-packagesThis refreshes model data before building pi-ai. To avoid network access when
model data is already hydrated, pass --offline-model-data.
The direct node scripts/pack-packages.mjs --out <dir> and node scripts/local-release.mjs entrypoints also work without an npm parent. On Windows they resolve npm-cli.js from npm_execpath, beside Node, or from an npm installation on PATH, and invoke it with Node without a command shell.
Local packing skips the release-daemon completeness check and announces that
limitation. It supports installation and import testing without preparing the
eight-platform pi-env daemon matrix, but does not certify a deployable
pi-env release. Environment startup still needs the matching daemon assets
under packages/env/bin/; see pi-env development.
Publication retains the strict complete-asset check.
Then configure an external project to consume one package and resolve all of its Pi dependencies from the same artifact set. npm is the default:
node scripts/use-local-packages.mjs \
--manifest .artifacts/pi-packages/manifest.json \
--consumer ../my-project \
--package @earendil-works/pi-durable \
--package @earendil-works/pi-agent-core
cd ../my-project
npm install --ignore-scriptsFor a pnpm project, point --consumer at the workspace root:
node scripts/use-local-packages.mjs \
--manifest .artifacts/pi-packages/manifest.json \
--consumer ../my-project \
--package @earendil-works/pi-agent-core \
--package-manager pnpm
cd ../my-project
pnpm install --ignore-scriptsRepeat --package for each direct dependency. The command updates the
consumer's package.json with content-addressed local file: references. It
writes transitive overrides to package.json for npm or pnpm-workspace.yaml
for pnpm. Keep the artifact directory available while installing or updating
the consumer. Re-run both commands after changing Pi source.
GitHub releases include a versioned source archive covered by the release's SHA256SUMS file. Extract it and run the same build script used for the official standalone binaries:
VERSION="<release-version>"
tar -xzf "pi-${VERSION}-source.tar.gz"
cd "pi-${VERSION}"
./scripts/build-binaries.sh --offline-model-data --platform linux-x64 --out "$PWD/out"The archive includes release model data and native prebuilds. --offline-model-data uses that model data without refreshing provider catalogs. The script installs dependencies and builds the executable with its runtime assets; pass --skip-install if dependencies are already provided.
We treat npm dependency changes as reviewed code changes.
- Direct registry dependencies, including internal workspace dependencies, are pinned to exact versions.
.npmrcsetssave-exact=trueandmin-release-age=2to avoid same-day dependency releases during npm resolution.package-lock.jsonis the dependency ground truth. Pre-commit blocks accidental lockfile commits unlessPI_ALLOW_LOCKFILE_CHANGE=1is set.npm run checkverifies pinned direct deps, native TypeScript import compatibility, and the generated coding-agent install lock.- The pi.dev installer installs from
packages/coding-agent/install-lock/, generated from the root lockfile, to pin transitive deps. The npm package does not pin transitive deps. - Local release smoke tests and npm publication use the same tarball packer; npm publishes the validated tarballs rather than repacking workspace directories.
- Local release installs, documented npm installs, and
pi update --selfuse--ignore-scriptswhere supported. - CI installs with
npm ci --ignore-scripts, and a scheduled GitHub workflow runsnpm audit --omit=devplusnpm audit signatures --omit=dev. - Install lock generation has an explicit allowlist for dependency lifecycle scripts; new lifecycle-script deps fail checks until reviewed.
If you use Pi or other coding agents for open source work, please share your sessions.
Public OSS session data helps improve coding agents with real-world tasks, tool use, failures, and fixes instead of toy benchmarks.
For the full explanation, see this post on X.
To publish sessions, use badlogic/pi-share-hf. Read its README.md for setup instructions. All you need is a Hugging Face account, the Hugging Face CLI, and pi-share-hf.
MIT