pi-spark

Pi package that polishes your daily experience and keeps you at the frontier of agentic workflows.

Features

Compact TUI: editor, footer, and fullscreen

pi-spark ships with custom editor, footer, and fullscreen rendering, replacing the default ones. The compact TUI gives you a calm, immersive experience without distraction.

• The editor shows a working indicator inspired by Amp and the current model on the top border. If you use presets, the active preset appears there too.
• The footer shows session information, extension statuses, cost, and context usage on one line.
• The fullscreen rendering clears the terminal screen and scrollback on session start and exit, and pins the editor and footer to the bottom.

Credits

pi-spark shows the active provider's credit balance or rate-limit usage in the status line, so you can keep an eye on what's left without leaving the terminal.

• Supported providers: DeepSeek, Fireworks, Moonshot, OpenAI Codex, OpenRouter, and Vercel AI Gateway.
• Most provider fetching follows CodexBar. Fireworks is the exception: its balance sits behind an internal gRPC API, reverse-engineered from the firectl binary (see docs/fireworks.md).

Presets

pi-spark lets you define named model presets in spark.json (see Configuration), so you can switch between models and thinking levels without retyping provider details. The active preset is shown on the editor's top border.

• Switch interactively with /preset, or jump straight to one with /preset <name>.
• Start pi on a given preset with pi --preset <name>.
• Cycle presets with ctrl+super+p (forward) and ctrl+shift+super+p (backward); super is command on macOS and needs a terminal that forwards it.

Recap

pi-spark generates a short recap of the current session after it goes idle, or on demand, inspired by Claude Code's session recap.

• A recap is generated automatically once the session stays idle past recap.idle in spark.json.
• Run /recap to generate one manually at any time.
• The recap can use its own model, configured separately from your working model.

Agent tools: pi and web

pi-spark adds two agent tools:

The pi tool lets the pi coding agent inspect and manipulate itself (~740 tokens).

• models lists and searches the model catalog.
• name sets or updates the current session's name.
• whoami shows the current pi state, including session name, active model, and thinking level.

The web tool gives the agent live web access, backed by the free Exa MCP (~350 tokens). No separate MCP setup or API key is needed.

• search finds current information across the web and returns ready-to-use content.
• fetch reads the full content of known URLs as clean markdown, and can batch several URLs in one call.

Configuration

pi-spark reads config from ~/.pi/agent/spark.json and from the current project's .pi/spark.json. Project config overrides matching global fields.

For example:

{
  "editor": {
    "spinner": "dots"
  },
  "footer": false,
  "presets": {
    "claude-opus": {
      "provider": "anthropic",
      "model": "claude-opus-4-8",
      "thinkingLevel": "high"
    },
    "gpt": {
      "provider": "openai-codex",
      "model": "gpt-5.5",
      "thinkingLevel": "medium"
    }
  },
  "recap": {
    "idle": "5m",
    "provider": "openai-codex",
    "model": "gpt-5.4-mini",
    "thinkingLevel": "off"
  }
}

References

All fields are optional. Each top-level feature runs with the defaults below unless you turn it off.

Field	Value (or false)	Description
credits	{}	Shows the active provider's credit balance or rate-limit usage in the status line.
editor	EditorConfig	Shows a working indicator and the current model on the editor's top border.
footer	{}	Shows session info, extension statuses, cost, and context usage on one line.
fullscreen	{}	Clears the screen and scrollback on start and exit, and pins the editor and footer to the bottom.
pi	{}	Exposes the pi agent tool (models, name, whoami actions).
presets	{ [name]: Preset }	Defines named model presets, keyed by name.
recap	RecapConfig	Generates a session recap when idle or on demand.
web	{}	Exposes the web agent tool (search, fetch actions) via Exa's hosted MCP server.

EditorConfig

The spinner field is optional and defaults to tildes.

Field	Value	Description
spinner	dots	⠋, ⠙, ⠹, ⠸, ⠼, ⠴, ⠦, ⠧, ⠇, ⠏
	lights	○, ●
	tildes (default)	∼, ≈, ≋, ≈, ∼
	pulse	·, •, ●, •, ·

Preset

Each preset must set all three fields.

Field	Value	Description
provider	string	Provider ID, e.g., anthropic.
model	string	Model ID, e.g., claude-opus-4-8.
thinkingLevel	off, minimal, low, medium, high, xhigh	Thinking level for the preset.

RecapConfig

All fields are optional, including thinkingLevel.

Field	Value	Description
idle	number (ms) or duration string	How long the session must stay idle before a recap is generated. Accepts a millisecond number or a vercel/ms string (e.g., "3m"); minimum 5000 ms, defaults to 3 minutes.
provider	string	Provider ID for the recap model.
model	string	Model ID for the recap model.
thinkingLevel	off, minimal, low, medium, high, xhigh	Thinking level for the recap model.

Turn off the features you don't like

All features are enabled by default. Set a specific feature to false in spark.json to disable it.

For example, to disable the customized footer:

{
  "footer": false
}