p-spore

A Linux-first, local-first AI agent you run from your own terminal. p-spore keeps a long-running local daemon that holds your sessions, memory, scheduled jobs and child agents, and gives you a reconnecting TUI on top of it. Everything lives on your machine under ~/.pspore — there is no hosted backend and no account.

Built on Pi (pinned to v0.84.1).

Requirements

• Linux
• Node.js 24 (>=24.0.0 <25)

Install

npm install --global p-spore
p-spore tui

This installs two equivalent commands, p-spore and the shorter pspore — both start the same CLI, so use whichever you prefer. To run it once without installing:

npx p-spore --help

p-spore tui initializes a missing home directory, starts a local daemon if none is running, and shuts down only the daemon it started itself. If one is already running, it reconnects to it instead.

Configure a model

No model is configured out of the box. The daemon still starts so you can check its health, and the first prompt returns model_not_configured until you set one up.

p-spore config show
p-spore config set deepseek deepseek-v4-flash off
p-spore config set openai gpt-5.6-terra low
p-spore config set custom-openai my-model https://gateway.example.com/v1 responses off
p-spore config key                 # hidden TTY input, or piped from stdin
p-spore config clear-key

Three provider kinds are supported: deepseek, openai, and custom-openai for any OpenAI-compatible endpoint (choose chat or responses compatibility). API keys are written to ~/.pspore/credentials/<provider>.api-key with mode 0600 and are never stored in config.json, sessions, or logs. You can also supply credentials through the daemon's environment instead.

Everyday commands

p-spore init                       # create config/workspace/state directories
p-spore doctor                     # check Node, config, model, shell, ripgrep, MCP, daemon
p-spore status                     # daemon and session status
p-spore tui                        # reconnecting terminal client
p-spore prompt "summarize today's notes"
p-spore daemon                     # run the daemon in the foreground

Add --home PATH to any command, or set PSPORE_HOME, to work against a home other than the default ~/.pspore. Run p-spore help for the full command list.

Scheduled jobs

Define a five-field cron job in workspace/jobs/<job-id>.json, or create and update one atomically from a file. Runs are recorded in a durable ledger and can be triggered or cancelled by hand.

p-spore schedule put job.json
p-spore jobs
p-spore run <job-id>
p-spore runs
p-spore cancel <run-id>
p-spore notifications

Child agents

Spawn bounded child agents that share read access, exchange messages with them while they work, and wait on or cancel them.

p-spore agent spawn "inspect the workspace API"
p-spore agent send <agent-id> "focus on error handling"
p-spore agents
p-spore agent join <agent-id>
p-spore agent cancel <agent-id>

MCP servers

MCP servers are declared in config.json and reference secrets indirectly through envRefs/headerRefs. Only trusted-local servers are started, and only on demand.

p-spore mcp list                   # configured servers and health, without connecting
p-spore mcp discover <server-id>   # connect and activate one trusted server
p-spore mcp tools                  # schemas active in this daemon process
p-spore mcp ping <server-id>

Skills and plugins

Skills and host plugins can execute arbitrary code, so they are only loaded after you explicitly trust them. Staged content is inspected first — schema, paths, dependencies and syntax only, never imported — and installing requires echoing back the exact SHA-256 you were just shown.

p-spore resource inspect <staging-path>
p-spore resource install <staging-path> <sha256>
p-spore resources
p-spore resource disable <skill|host-plugin> <name> <sha256>

Security model

• Single user, local-first. Nothing is exposed to the network; clients talk to the daemon over a Unix domain socket.
• Tools run as the user who started p-spore. This is not a sandbox.
• allow_all lets the model run any tool action as that user, which can reach root if you have passwordless or cached sudo.
• Skills, Pi extensions, plugins and local MCP servers are loaded only after explicit trust.

Desktop client

This npm package is the CLI and does not bundle Electron. p-spore desktop works when Electron is available in a source checkout; otherwise use the AppImage from the project's releases.

Links

• Repository
• Issues
• Project overview and development notes (Chinese): docs/project-overview.md