Coding agents are often slow, bloated and inscrutable. Complex for complexity's sake. Can you name all of Claude Code's features? How long does it take to compile Codex from source? (Hint: almost an hour on macOS and over an hour on Linux.)
Some coding agents purport to follow the Unix philosophy, but fall short of being a serious, real-world replacement for most use cases. Instead, we took a ground-up approach. What's the most portable language? C. What's the most portable, high-level runtime that is implemented in C? Lua.
The result is a coding agent that has superpowers for free. A 6 MB binary via the Cosmopolitan C library that runs on macOS, Linux and Windows without modification. A coding agent that runs on Haiku, *BSD, or your iPhone via iSH.
psi has no shortage of features, including:
- support for many LLM backends, including Codex OAuth, OpenRouter, Ollama
- full session tree, forking and queue management
- skills
- interactive (CLI, TUI) and non-interactive use
- extensions and a self-documenting Lua runtime that can be modified on the fly
Features we don't implement:
- No sandboxing. If you want it sandboxed, run it in a container or a VM.
- No plugin marketplace, hosted backend, telemetry, or auto-update service.
$ nix run github:siraben/psi-codeFor local development:
$ nix develop
$ make
$ ./build/psi --helpThe same binary supports the TUI, REPL, one-shot print mode, Lua eval, session compaction, and direct agent turns:
$ ANTHROPIC_API_KEY=... ./build/psi
$ ./build/psi --repl
$ ./build/psi --print 'hello'
$ ./build/psi --agent 'Read README.md and summarize.'
$ ./build/psi --eval 'psi.tool_call("read", {path = "README.md"})'
$ ./build/psi --session /tmp/s.jsonl --compact 12
$ ./build/psi --model openai-codex/gpt-5.5 --thinking xhigh --agent '...'The TUI follows pi's current startup and editing model: a compact branded help
screen expands with Ctrl-O, Shift-Tab cycles thinking effort, Ctrl-P /
Ctrl-Shift-P cycle models, Ctrl-T toggles thinking blocks, and the prompt border
tracks the active effort color. Thinking visibility is sticky via
hideThinkingBlock in ~/.config/psi/settings.json (or
$XDG_CONFIG_HOME/psi/settings.json). Up/Down stay in the editor and its
history; PgUp/PgDn scroll the transcript in frame/fullscreen mode. Normal-screen
chat mode leaves mouse-wheel scrollback to the terminal, while
PSI_TUI_ALT_SCREEN=1 enables application-owned wheel scrolling and Alt-wheel
acceleration. Startup shows the name and version (psi v…), without a graphic logo.
The default pi-dark / pi-light palettes exactly match released Pi 0.87.1
(the same palette used by 0.84.4). The dark / light aliases and existing
theme, theme.name, and tui.theme settings are also supported.
In the TUI or REPL, ! command runs a local shell command without calling the
model and includes its result in subsequent model context. !! command runs
it but excludes the result from model context (it is still saved locally).
The TUI streams output, reports exit status, and supports Escape cancellation.
Shell commands entered while another operation is busy stay in the editor.
Informational, settings, and extension slash commands execute and render in the
transcript while the agent is working or thinking. Commands that would replace
or rewrite active session state instead render a warning and wait for the active
operation to finish.
psi aims to be:
- The most portable and extensible coding agent in the world.
- Fully auditable (via a Software Bill of Materials)
- Practical (we daily drive psi)
- Open source
psi is heavily inspired by the pi coding agent. Like pi, psi aims to implement only the base functionality in-tree, and then defer features to Lua extensions written by the user, such as the TUI rendering, queue management, even the agent loop itself.
The extension language is Lua because of the following reasons we've observed:
- LLMs can write good, idiomatic Lua
- Lua's runtime has minimal dependencies
- Lua is reasonably fast and can support modern programming styles and abstractions.
We chose C89 for the base implementation because of its extreme portability. Most platforms, even non-POSIX ones, have a compiler for C89.
Things that have to be fast (e.g. networking) are done in C89 with minimal dependencies. We use:
- libedit
- ncurses
- curl with mbedTLS
- wcwidth-compatible Unicode cell-width handling
- zlib
- cJSON
- a C compiler
- a libc
Optional Make flags default to 1; set them to 0 to disable the feature.
| Flag | Effect |
|---|---|
TUI |
Inline terminal frontend and psi.tui_* host primitives |
ANSI |
ANSI SGR emission and parsing. Required by TUI. |
COLOR |
Color SGR emission. Non-color styles can still be used. |
MCP |
Stdio process primitives for protocol clients. |
REPL_EDITLINE |
libedit-backed REPL with history. Falls back to fgets. |
Run the build-matrix check when optional dependencies or preprocessor guards change:
$ make check-build-configsDependency SBOM generation and vulnerability gating are available with:
$ nix run .#audit-sbomWe've tested on the following operating systems (on i686, x86_64, aarch64, riscv64 where available):
Linux, macOS, Windows, Haiku, OpenBSD, FreeBSD.
Really, any operating system that supports a POSIX-like API surface can run psi.
Beyond just being able to run psi, we also support a wide variety of ways to compile and link psi. For the clib layer, we've tested glibc, musl, cosmopolitan, fil-c, c-ward. For the C compiler itself, we've tested gcc (4.6 through 15), clang, CompCert, TCC.
See docs/portability.md.
psi supports multiple model providers. Choose a provider and model with
--model <provider>/<name>, set PSI_PROVIDER, or save defaults.provider
and defaults.model in settings. Without an explicit choice, psi selects from
available credentials. See provider selection
for the precedence and fallback rules. Built-in providers include:
- Anthropic
- Ollama
- OpenRouter
- OpenAI Codex
- Moonshot (Kimi For Coding)
Ask the running agent for live provider metadata:
psi> /apropos provider:
psi> /describe provider:anthropic
See docs/providers.md.
read, write, edit, bash, grep, find, ls, and lua are registered
out of the box. Extensions add more with psi.tools.register.
Drop a Lua file in any of:
$PSI_EXTENSIONS_DIR(colon-separated, loaded first)~/.config/psi/extensions/./.psi/extensions/
It runs at boot with the psi global available. Register tools, subscribe to
events, add slash commands, customize themes, or hook the TUI. Extensions are
trusted local code with the same filesystem and process access as psi itself;
project-local extensions load only after the workspace is trusted. Interactive
sessions prompt once; non-interactive modes skip untrusted project resources.
Use --trust or --no-trust to override that decision for one run.
See docs/extensions.md.
Put each skill's SKILL.md under ~/.config/psi/skills/<name>/ or
./.psi/skills/<name>/ (use $XDG_CONFIG_HOME/psi/skills/ when set).
The file needs frontmatter with a single-line description and may set name.
Psi lists skill names, descriptions, and file paths in the system prompt;
the agent reads the full file with read when a task matches. Project skills
load only after the workspace is trusted. Set disable-model-invocation: true
to keep a skill out of the model's list. Skill packages, /skill:name, and
.agents/skills discovery are not implemented.
Sessions are append-only JSONL in pi's v3 schema: typed entries, parent pointers, cache markers, file-op provenance, custom entries, custom model-context messages, compaction summaries, and branch summaries. The Pi 1.4 context projection applies branch-local context edits and compaction boundaries while preserving original message IDs. System sections and historical tool declarations are checkpointed; only locally registered tools execute. Unknown fields and entry types survive save/export; unrecognized entry types remain opaque state outside model context. Prompt sections refresh from psi's local resources, tool set, and trust policy when continuing a session. Pi extensions, packages, credentials, and provider configuration are not imported.
A session started under one provider can be resumed under another.
Provider-specific thinking and signature blocks may be downgraded during replay.
Without --session FILE, psi assigns a path under
$XDG_STATE_HOME/psi/sessions or ~/.local/state/psi/sessions.
Use /tree to show the session tree or /tree <entry-id> --summarize to switch
branches while preserving the branch you leave as summary context. /branch
and /branches remain text aliases for quick inspection and switching.
src/main.c entry point and CLI dispatch
src/core/ abort signal, process spawn, HTTP, sessions, TLS
src/runtime/ CLI parser, print/repl/agent dispatch, TUI mode
src/lua/vm.c Lua VM and C/Lua bridge
include/psi/ public host headers
scripts/embed.c build-time deflate of Lua sources and docs
lua/boot.lua Lua bootstrap; wires psi.* and loads extensions
lua/psi/ tools, prompts, sessions, scheduler, markdown, TUI
lua/psi/tools/ built-in tool implementations
lua/psi/providers/ Anthropic, Ollama, OpenRouter, OpenAI Codex adapters
lua/psi/extensions/ bundled extensions
docs/architecture.md runtime model and host/runtime boundaries
docs/portability.md porting principles and per-OS notes
docs/port-status.md audit against pi-mono
docs/extensions.md extension API and event catalog
docs/providers.md provider configuration
tests/ Python harnesses for smoke, bench, and valgrind runs
There is no published eval suite yet. The repository uses smoke tests,
build-matrix checks, benchmark harnesses, and valgrind-oriented tests under
tests/.
psi was supposed to be a fork of pi that used Scheme as the extension language (hence psi), but owing to the complexity of runtimes and in pursuit of a more minimal, perfect coding agent, we ultimately chose Lua instead.
The project is MIT licensed.