@kevinhao/pi-spark

Pi package that polishes your daily experience.

Install

# Install this package from npm (recommended)
pi install npm:@kevinhao/pi-spark
# Or install all extensions from this monorepo
pi install git:github.com/haoyiqiang/pi-extensions

Reload or restart Pi after installation.

Features

Compact TUI: editor and footer

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

• The editor shows a working indicator inspired by Amp, the elapsed time since you sent the message, 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. Set style to p10k for a lean powerlevel10k left prompt (OS icon, fish-shortened path, on, and branch). That style needs a Nerd Font.

Earlier pi-spark releases included a custom fullscreen renderer. Pi 0.84.0 now provides fullscreen mode natively, with a sticky editor and footer and an independently scrollable transcript, so pi-spark has retired its workaround. Enable Pi's fullscreen mode in /settings, with pi --tui-mode fullscreen, or in Pi's settings.json:

{
  "tuiMode": "fullscreen"
}

When upgrading, remove the retired fullscreen field from spark.json.

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, Kimi Code, 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 Reverse-Engineering Fireworks Credits).

OpenAI Codex banked resets

Banked rate-limit resets are saved benefits that can reset eligible Codex usage windows when redeemed. When available, their count appears after the usage windows. Run /codex-resets to inspect each reset and its expiration date, then select one to redeem. See OpenAI Codex Banked Rate-Limit Resets for the underlying behavior and internal APIs.

Peak/off-peak pricing

Pi does not currently support time-based pricing, so its cost estimates can be inaccurate for providers with peak/off-peak rates, such as DeepSeek. pi-spark updates model cost metadata so subsequent usage calculations reflect the current rate.

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.

Clean mode

Clean mode collapses an entire agent run into one duration header, leaving the final answer visible. Press F2 or run /clean to expand the hidden narration, tool calls, and extension work entries. Shift+F2 expands or collapses all action groups.

• The run stays expanded while the agent is working and collapses after agent_settled, unless you manually changed it during that run.
• Fullscreen TUI supports clicking the run header, action groups, and individual tool summaries.
• Run /config:spark → Clean mode → Detailed settings to configure folding and activity rows.
• Set cleanMode to false to disable all folding. An existing extensions/pi-clean-mode/config.json is read only when spark.json does not set cleanMode.
• Remove npm:pi-clean-mode if it is still installed, or its commands and shortcuts will conflict.

Metrics

pi-spark shows session elapsed time and token-generation telemetry through Pi's native notifications. The editor border shows the total wait, for example ⏱ 47s, and it keeps counting across turns.

• on-stop (default): the transcript stays quiet during the run. When the agent settles, one native notification reports elapsed time, blended TPS, TTFT, tokens, stalls, and cost. If no TPS sample is available, it still reports elapsed time.
• live: one native notification is emitted at the end of every turn. A multi-turn run also gets a final ⏱ <duration> notification.
• Metrics do not register a custom entry renderer or write display entries into the session.
• Run /config:spark → Metrics to toggle telemetry or select live / on-stop. An existing extensions/pi-metrics/config.json is used only when spark.json does not set metrics.

Session resources

Typing # at a token boundary opens a tabbed picker above the spark editor. It lists files, web URLs, and PR/MR links collected from successful tool results in the current session. Enter inserts a normal reference such as #src/index.ts; it does not read the file again or add hidden context.

• The picker stays outside the spark editor, so the two no longer replace each other.
• Run /config:spark → Session resources to enable or disable the picker.
• Set resources to false to disable it. An old extensions/pi-session-resources/config.json with "enabled": false is used only when spark.json does not set resources.
• Remove npm:pi-session-resources if it is still installed, or the command names conflict.

Session naming

Naming is now a Spark feature, migrated from pi-naming.

• The first real user input in a new, unnamed session generates a title in the background. Automatic naming attempts once, never overwrites an existing title, and ignores extension-injected input.
• /rename [name] applies an explicit name or generates one from all user messages on the current branch. Later corrections take precedence; procedural follow-ups such as “continue” do not replace the main topic.
• Run /config:spark → Session naming → Detailed settings to configure naming; the same feature menu provides a reset action.
• Naming renames the Pi session only. Set naming: false to disable automatic and manual naming; legacy naming.targets keys are accepted and ignored.
• Naming uses the current Pi model/authentication and makes a separate background request. OpenAI Codex requests use isolated UUIDv7 sessions and clean them up afterwards. Generated names obey the length limit; explicit names are not truncated.
• Manual requests supersede pending automatic requests. Session changes invalidate pending results and errors.

Spark no longer renames tmux windows, tmux sessions or Orca tabs, and no longer depends on @kevinhao/pi-terminal-mux. A pane proves no exclusive ownership of its window, session or tab, and subagents now launch in detached tmux sessions, so terminal naming had no target it could safely rewrite.

Migrating from pi-naming

Remove the old extension to avoid duplicate commands and automatic requests:

pi remove npm:pi-naming

Also remove any explicit old entrypoint from extension lists, then /reload. If installed in project scope, remove the corresponding local package declaration too. This repository no longer loads or publishes the standalone package; previously published npm versions are not changed.

When neither global nor project spark.json defines naming, Spark reads <agent-dir>/extensions/pi-naming/config.json as a read-only fallback. Any canonical section, including {} or false, takes precedence over the entire legacy config. The config menu writes only spark.json, preserves other features, and writes the project file when that file explicitly owns naming; otherwise it writes the global file. Invalid naming settings or unreadable configuration disable naming rather than unexpectedly starting model requests.

To enable naming in isolated Pi subagents, explicitly load the installed Spark entrypoint in their extension allowlist. This also loads Spark's other features: disable unwanted features in the applicable spark.json. Installing Spark only in the parent does not bypass child isolation.

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 generation can use its own model, configured separately from your working model.

Configuration

Run /config:spark to open the unified configuration panel. Select a feature to toggle it, change common editor/footer/metrics options, or edit its complete settings as validated JSON (including credits providers, naming, presets, and recap). Changes are saved immediately and preserve other features. The panel writes the project file when it explicitly owns the selected feature; otherwise it writes the global file. Run /reload after saving to apply all changes. This is the only configuration entrypoint: the former feature-specific commands and aliases, including /clean config, have been removed. Operational commands such as /clean, /rename, /preset, and /recap remain.

pi-spark reads config from <agent-dir>/extensions/pi-spark/config.json and from the current project's .pi/extensions/pi-spark/config.json. Project config overrides matching global fields. A retired spark.json in the agent directory or .pi/ is read only when the new file is absent. The agent directory respects PI_CODING_AGENT_DIR. See config.example.json for naming defaults.

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.

CleanModeConfig

CreditsConfig

All supported providers are enabled by default. Set a provider to false to disable its credits status and pricing updates, or to true to override a global false in project config.

{
  "credits": {
    "providers": {
      "fireworks": false,
      "openai-codex": true
    }
  }
}

EditorConfig

The spinner field is optional and defaults to tildes. thinkingLevelIndicator is also optional and defaults to border.

FooterConfig

The statusPosition field is optional and defaults to inline.

MetricsConfig

Set metrics to false to disable both the elapsed label and telemetry.

NamingConfig

All fields are optional. automaticNaming and manualNaming default to true.

Length and token limits are independent positive safe integers. For longer English titles, use maxLength: 60, preferredLength: 40, language: "English". Unknown naming fields and invalid values are rejected. Run /reload after configuration changes.

Preset

Each preset must set all three fields.

RecapConfig

All fields are optional. If the recap model configuration is incomplete, pi-spark falls back to the session's main model. thinkingLevel defaults to off (clamped to the model), so recap stays cheap regardless of your working thinking level.

ModelThinkingLevel

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

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
}

Themes

pi-spark ships with two custom themes inspired by GitHub's VS Code themes:

• github-light-default
• github-dark-default

Select either theme in /settings, or configure automatic switching between them:

{
  "theme": "github-light-default/github-dark-default"
}

Development

Run the package checks from the monorepo root:

npm install
npm run typecheck --workspace pi-spark
npm run check --workspace pi-spark

pi-spark is based on zlliang/pi-spark and is maintained and released from this monorepo.

License

MIT