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

Install from npm:

pi install npm:pi-spark

Install from git:

pi install git:github.com/zlliang/pi-spark

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.

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).

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.

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.

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.

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"
  }
}

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

The spinner field is optional and defaults to tildes.

Each preset must set all three fields.

All fields are optional, including thinkingLevel. If the recap model configuration is incomplete, pi-spark falls back to the session's main model.

Valid values: off, minimal, low, medium, high, xhigh.

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
}