psi GitHub

C at the core. Lua in your hands.

Your terminal.
Your models.
Your agent.

Meet psi, the portable coding agent. Small enough to understand. Open enough to make your own. Built to run wherever you do.

Get started Read the source

Open source · MIT licensed · No telemetry

THE PORTABLE CODING AGENT01 / ψ
C89 CORELUA RUNTIME
One small binary.
A world of possibilities.
AT HOME ONLinuxmacOSWindowsFreeBSDOpenBSDHaikuand beyond ↗

01 — A smaller foundation

Less between you
and the work.

A coding agent should be a tool you can understand, carry with you, and change. psi starts with a small C core and puts the high-level behavior in Lua.

The agent loop, terminal interface, tools, and providers are all open to inspection. Keep the parts you need. Build the parts you’re missing.

Explore the architecture
01 /

Choose your model.

Anthropic, OpenAI Codex, OpenRouter, or local models with Ollama. Resume a session with a different provider.

02 /

Keep your context.

Branch a conversation, explore another approach, and return. Sessions are append-only JSONL with a full tree.

03 /

Work your way.

An interactive TUI, a simple REPL, one-shot prompts, and Lua evaluation. At your keyboard or in your scripts.

02 — Take it with you

Portable by design.
Not by accident.

C89 and Lua are a deliberate choice. psi runs on familiar desktops and less-traveled systems, with a Cosmopolitan build that runs on Linux, macOS, and Windows.

Read the portability notes
TESTED OPERATING SYSTEMSSTATUS
  • LinuxTested
  • macOSTested
  • WindowsTested
  • FreeBSD / OpenBSDTested
  • HaikuTested

Across i686, x86_64, aarch64, and riscv64 where available. See the porting notes for build details.

03 — Make it yours

A little Lua.
A lot of possibility.

Add a slash command. Register a tool. Subscribe to the agent lifecycle. Your extensions are ordinary Lua files, loaded straight from disk.

Even the agent loop and terminal rendering live in Lua. Customization goes all the way down.

Explore the extension API
~/.config/psi/extensions/hello.luaLUA
-- A command, in a few lines.
return function(psi)
  psi.commands.register("greet", function(rest)
    return psi.records.new_command_action(
      "print", "hi, " .. (rest ~= "" and rest or "friend")
    )
  end)
end
psi> /greet worldhi, world

04 — Start here

Small tool.
Big range.

Bring a model provider and a project.
psi brings the rest.

nix run github:siraben/psi

Requires Nix with flakes enabled.

Configure your provider before the first agent turn. Provider setup ↗

Yours to run.
Yours to understand.
Yours to change.

Build with psi