Content
# pi-elixir
`pi-elixir` is the pi extension for BEAM-native, verifiable Elixir development.
It gives pi an isolated BEAM control plane plus explicit project, application, and attached-runtime eval modes, so an agent can inspect runtime state, make syntax-aware Elixir edits, and verify changes with real project checks. The model-facing surface stays intentionally small: eval for runtime truth, ExAST tools for structural code work, and normal Mix/LSP/shell commands for everything else.
## What it gives pi
- **Persistent project eval** — `elixir_eval` defaults to a dependencyless target-project VM that keeps bindings while avoiding application startup side effects.
- **Explicit runtime modes** — opt into managed application startup or attach to an existing distributed BEAM node to inspect live processes and ETS state.
- **Stateful IEx-like cells** — bindings, aliases, imports, and requires persist per pi execution path via sidecar snapshots; failed compilation/eval keeps the last good state.
- **Structural Elixir tools** — `elixir_ast_search` and `elixir_ast_replace` use [ExAST](https://hex.pm/packages/ex_ast) patterns instead of text/regex matching.
- **Syntax-aware review orientation** — `AST.diff(changed: true)` / `CodeMap.reflect(changed: true)` summarize changed modules/functions before the agent reads a large `git diff`.
- **OTP-backed sessions and agents** — optional BEAM sessions/subagents render as compact pi session trees without spawning more pi processes.
- **Project-local skills/plugins** — trusted local Elixir can add project workflows, guardrails, slash commands, tool hooks, and UI widgets.
- **Strict verification** — this repo gates releases with JS lint/typecheck/tests, BEAM compile/test/Credo/Dialyzer, ExDNA clone detection, Reach architecture/smell checks, Hex build validation, and npm pack validation.
`pi-elixir` follows the broader [Elixir Vibe](https://github.com/elixir-vibe) direction: compact agent APIs outside, rich composable Elixir APIs inside, structured BEAM payloads rendered by pi, and verification through runtime state plus structural analysis.
## Install
```sh
pi install npm:pi-elixir
```
Check the bridge from inside pi:
```text
/elixir:status
```
Use full diagnostics when setup looks wrong:
```text
/elixir:doctor
```
No project dependency or `mix.exs` edit is required. The extension starts its bundled `pi_bridge` in an isolated control VM and starts a separate dependencyless worker for the target Mix project. Startup validates a strict build/protocol/capability handshake.
## Daily workflow
### Inspect project code or a running app
Default eval uses the persistent project VM without starting the application:
```text
iex alias MyApp.Repo; alias MyApp.Billing.Invoice; stale = Repo.all(...); length(stale)
14
Took 0.1s
```
The next eval continues from the same IEx-like state:
```text
iex stale |> Enum.group_by(& &1.customer_id) |> Enum.map(fn {id, xs} -> {id, length(xs)} end)
[{"cust_123", 5}, {"cust_456", 9}]
Took 0.1s
```
Use `target: "application"` when application startup is intentional. Use `target: "runtime"` with `PI_ELIXIR_NODE` (and the matching distributed-node cookie) to inspect an already-running node without starting a second copy. Bridge helper APIs such as `AST`, `CodeMap`, `Self`, `Q`, and `Docs` use `target: "bridge"`.
For Phoenix/Ecto/OTP bugs, prefer asking the intended runtime over guessing from files:
```elixir
Supervisor.which_children(MyApp.Supervisor)
Application.get_env(:my_app, MyApp.Repo)
Process.info(pid, [:status, :message_queue_len, :current_stacktrace])
```
### Search and edit by syntax
Use ExAST-backed tools for Elixir code shape:
```text
ast grep defmodule _ do _ end lib/my_app
ast edit Logger.debug(_) → Logger.info(_) lib/my_app --dry-run
```
These tools use valid-Elixir ExAST syntax, not ast-grep metavariables: lowercase variables capture nodes, `_` matches one node without capturing, and `...` matches zero or more nodes. Never use `$NAME` or `$$$ARGS` with the Elixir AST tools. They are for structural Elixir search/refactors; use LSP for editor semantics and `mix format`/tests for verification.
### Review changed Elixir safely
Before reading a large or truncated textual diff, orient on changed modules/functions:
```elixir
AST.diff(changed: true)
CodeMap.reflect(changed: true)
```
Then inspect only the relevant source slices or `git diff` sections. This keeps review focused on semantic changes instead of raw patch volume.
## Model-facing tools
`pi-elixir` deliberately exposes only three model tools:
| Tool | Label | Purpose |
|---|---:|---|
| `elixir_eval` | `iex` | Trusted eval in `project` (default), `application`, attached `runtime`, or isolated `bridge` mode. Stateful by default for pi session branches; sandbox mode is available for untrusted snippets. |
| `elixir_ast_search` | `ast grep` | ExAST structural search over Elixir code. |
| `elixir_ast_replace` | `ast edit` | ExAST structural rewrite with dry-run diffs. |
Everything else is ordinary Elixir API reachable through eval:
```elixir
Pi.project()
Pi.logs(tail: 50)
Pi.Bridge.Info.runtime_apis()
Pi.Eval.bindings()
Pi.Eval.forget(:huge_result)
Pi.Eval.reset()
Pi.Docs.entries(Pi.Output)
Pi.Docs.get(Pi.Output, :table, 2)
Pi.Web.fetch!("https://example.com", format: :text)
Pi.Session.start(name: :reviewer)
Pi.Agent.parallel(["Review API", "Review tests"], timeout: 60_000)
```
For model calls from the BEAM, pi still owns provider/model selection, credentials, streaming, cancellation, usage, and transcript UI:
```elixir
Pi.LLM.complete("Summarize this module")
Pi.LLM.stream("Draft a migration plan")
Pi.ReqLLM.install()
ReqLLM.generate_text(Pi.ReqLLM.current_model(), "Summarize this module")
```
## Stateful eval and sidecars
`elixir_eval` behaves like an IEx/Livebook cell runtime scoped to the current pi execution path:
- variables persist across calls;
- `alias`, `import`, and `require` persist through `Macro.Env`;
- errors do not replace the previous good state;
- `Pi.Eval.bindings/0`, `forget/1`, and `reset/0` manage state from inside eval;
- snapshots are stored as sidecar blobs, **not** in the JSONL transcript.
Physical storage:
```text
<session.jsonl>.pi-elixir/
eval-state/
<toolCallId>.term
<toolCallId>.term.meta.json
```
Unsafe or oversized bindings are handled defensively: PIDs/ports/refs/functions are not persisted, containers containing them are skipped, and sidecar snapshots have a size budget.
## Connection and runtime model
The normal path is an embedded stdio control bridge started from the extension's bundled `packages/bridge` project. It does not load `pi_bridge` into the target project. HTTP MCP endpoints remain advanced/debug escape hatches.
Resolution order:
1. `PI_MCP_URL`, only when explicitly configured for a manually exposed HTTP MCP endpoint.
2. Discovered local HTTP MCP endpoint matching the Mix app name.
3. Bundled embedded stdio control bridge, with `PI_ELIXIR_PROJECT_CWD` identifying the target project.
The control bridge then routes eval to one of four strict targets: dependencyless persistent `project`, managed `application`, attached distributed `runtime`, or `bridge`. Ready state is accepted only when build, protocol, and required capabilities match; one stale child is replaced atomically before an incompatibility is reported. The supervision and dependency boundaries are documented in [`packages/bridge/docs/architecture.md`](packages/bridge/docs/architecture.md).
```sh
# Advanced/debug only: bypass embedded stdio and use your own HTTP MCP endpoint.
export PI_MCP_URL=http://localhost:4001/mcp
export PI_DISABLE_EMBEDDED=1
```
Status distinguishes the control bridge from the target project and reports external/embedded/starting/incompatible/unavailable state plus the negotiated runtime contract. Project-specific checks belong in explicit eval snippets, prompts, and skills.
Feature flags are escape hatches for noisy, sensitive, or experimental environments:
| Capability | Default | Escape hatch |
|---|---:|---|
| Stateful `elixir_eval` | on | `PI_ELIXIR_STATEFUL_EVAL=0` |
| Eval sidecar snapshots | on | `PI_ELIXIR_EVAL_SIDECAR=0` |
| BEAM LLM / ReqLLM | on | `PI_ELIXIR_LLM=0` |
| BEAM sessions/widgets/control | on | `PI_ELIXIR_SESSIONS=0` |
| Project plugins/hooks/UI/commands | on | `PI_ELIXIR_PLUGINS=0` |
| Executable Elixir skills | on | `PI_ELIXIR_SKILLS=0` |
| Extra-short eval previews | off | `PI_ELIXIR_COMPACT_EVAL_PREVIEW=1` |
## Recommended project stack
For new projects, install Elixir 1.20+ with OTP 27+ when possible. Elixir 1.20 introduced compiler type-system improvements, including gradual set-theoretic types, whole-body type inference, occurrence typing, and richer map typing; pi-elixir still supports older Elixir releases for existing legacy projects.
For new web applications, use Phoenix with Igniter and VibeKit, then add pi-elixir in the project:
```sh
mix archive.install hex phx_new
mix archive.install hex igniter_new
mix phx.new my_app
cd my_app
mix igniter.install vibe_kit --agents-md
pi install npm:pi-elixir
```
For non-web Elixir projects and packages:
```sh
mix archive.install hex igniter_new
mix igniter.new my_lib --install vibe_kit --agents-md
cd my_lib
pi install npm:pi-elixir
```
VibeKit provides the project quality baseline (`mix ci`, Credo strict with ExSlop, Dialyzer, ExDNA, and Reach). pi-elixir provides the BEAM tools used by agents while they work inside that project, without adding `pi_bridge` to project dependencies.
## Troubleshooting setup
| Symptom | What to do |
|---|---|
| `target Mix cwd: not found` | Start pi from a Mix project directory, or from a supported repo root with a known nested Mix project. |
| `Elixir is not installed or not available on PATH` | Start pi from a shell where Elixir/Mix are available. If you just changed `mise`/`asdf` versions, restart pi. |
| Stale `mise` PATH warning | Restart the shell/pi process so removed tool install paths disappear from `PATH`. |
| Embedded BEAM exited before ready | Fix the bundled bridge Mix/Elixir error shown in doctor, then run `/elixir:restart`. |
| Bridge build/protocol/capability mismatch | Run `/elixir:restart`; if it remains, update or reinstall `pi-elixir`. Do not edit the target project's dependencies. |
| Attached runtime cannot connect | Set `PI_ELIXIR_NODE` to the existing distributed node and start pi with a compatible node name/cookie. |
| Tool registration conflicts with another `pi-elixir` path | Remove the duplicate install, usually `pi remove npm:pi-elixir`, then install only the checkout or only the npm package. |
## Local development
```sh
git clone https://github.com/elixir-vibe/pi-elixir
cd pi-elixir
pnpm install
cd packages/bridge && mix deps.get && cd ../..
pi install "$PWD"
```
If you also have `npm:pi-elixir` installed globally, remove it before dogfooding a checkout to avoid duplicate tool registration:
```sh
pi remove npm:pi-elixir
pi install "$PWD"
```
From an already-running local checkout, `/elixir:dogfood` performs that switch for you.
Common commands:
```sh
pnpm run fmt
pnpm run check
pnpm run check:js
pnpm run check:beam
pnpm run test:integration
pnpm run pack:check
```
`pnpm run check` is the release-readiness gate.
## More docs
- [`packages/extension/README.md`](packages/extension/README.md) — pi extension behavior, connection resolution, slash commands, debugging, rendering, and tool discipline.
- [`packages/bridge/README.md`](packages/bridge/README.md) — BEAM APIs for eval, docs, LLM, sessions/agents, plugins, host bridge calls, and protocol concepts.
- [`packages/bridge/docs/protocol.md`](packages/bridge/docs/protocol.md) — stdio/protocol payload examples.
## Part of Elixir Vibe
pi-elixir gives the pi coding agent a live door into the BEAM: stateful eval, AST tools, and composable runtime APIs.
It is one building block of a larger stack — tools that make AI-generated software checkable: structural search, dependency analysis, duplication/slop detection, session replay, and ecosystem-wide code search. See the [Elixir Vibe](https://github.com/elixir-vibe) organization and [Building Blocks for the Future Web](https://github.com/elixir-vibe/building-blocks) for the broader thesis and roadmap.
