aloita-extensions

A Pi extension. One long-running Pi session connects to your Aloita server and works on tickets natively — no separate MCP server or subprocesses.

Install

Requires Pi (@earendil-works/pi-coding-agent) on your PATH and Node 18+.

pi install npm:aloita-extensions

Pi auto-loads the extension on every startup. Manage it with:

pi list                            # confirm it's registered
pi remove npm:aloita-extensions    # unregister
pi update --extensions             # update installed packages

Configure

Set your server URL and API key via environment variables:

export ALOITA_URL="https://your-aloita-server"
export ALOITA_API_KEY="kai_your_key_here"

Or run /aloita-configure inside Pi to set them (and other options) in an interactive settings screen — values persist to ~/.pi/aloita.json and apply to every Pi session on the machine.

A config.example.json ships with the package; copy it to ~/.pi/aloita.json (global) or <cwd>/.pi/aloita.json (project-local) and edit.

Launch pi. The footer shows the connection status when the socket is up.

Commands

Command	Action
/aloita-status	Show connection state, active ticket, queue.
/aloita-connect	Force reconnect.
/aloita-disconnect	Disconnect.
/aloita-next	Drain the next queued ticket.
/aloita-configure	Interactive settings UI.

Auto-start: how the settings interact

Two independent things exist — ticket pickup and the auto-start supervisor. They do not affect each other:

• Ticket pickup happens whenever a Pi instance with this extension is running in (or resolves to) a project's folder. It works regardless of any auto-start setting. If you cd into a project folder and start pi yourself, it picks up that project's tickets even with every auto-start option off.
• The auto-start supervisor (autoStartProjects, the "Auto-start supervisor" master switch) only controls whether this Pi session additionally launches child pi instances for other projects. Turning it off never stops ticket pickup — it only stops the launching of new instances.

Per setting:

Setting	What it actually does
autoStartProjects (master switch)	ON: this session polls /api/projects and spawns a child pi per allow-listed project. OFF: this session launches nothing. Ticket pickup is unaffected either way.
Project allow-list (autoStartProjectIds, the per-project auto-start on/off in /aloita-configure)	Only projects in this list are ever launched. A project that is OFF is simply never launched automatically — but a manually started pi in its folder still picks up its tickets.
autoStartSeedExisting ("Launch for all existing projects")	ON (default): when the supervisor starts, it launches every allow-listed project immediately — start one Pi and the rest of the fleet comes online. OFF: only projects created after the supervisor started are launched.
autoStartLinuxTerminal	Linux only: auto (default) opens each child in a visible terminal window (parity with the console windows on Windows); none = invisible background process; any other value = explicit terminal command. Headless sessions (no DISPLAY/WAYLAND_DISPLAY) always fall back to invisible.

Every spawned child also runs the supervisor loop; duplicate launches are prevented by per-project pidfiles (<folder>/.pi/aloita.autostart.pid) — a project whose pidfile holds a live pid is never launched again.

Assigned model (complexity tiers)

When Aloita's complexity scan stamps a model on a ticket (custom fields assigned_tool / assigned_provider / assigned_model), the extension switches Pi to that model right before the ticket's prompt is delivered — so the run uses the tier's model, not whatever the session started with. If the assignment targets a different tool, or the model isn't in Pi's registry (check the model list and API keys on this machine), the current model is kept and the reason is logged/toasted.

Logging

Diagnostics go to ~/.pi/aloita.log (never stdout/stderr, which would corrupt Pi's TUI). Set the level via ALOITA_LOG_LEVEL (debug/info/warn/error/off, default info) and the path via ALOITA_LOG_FILE.

License

MIT