OpenPeach

OpenPeach is a Node.js and TypeScript CLI/TUI for reducing verbose Claude Code tool output and inspecting local hook activity.

It has two entry points:

• openpeach launches the interactive terminal UI.
• peach provides scriptable hook, stats, diagnostics, export, and local credential commands.

Requirements

• Node.js 18 or newer
• Claude Code 2.1.121 or newer for updatedToolOutput support

Installation

Install the published package globally:

npm install -g openpeach

Or use another supported package manager:

pnpm install -g openpeach
yarn global add openpeach

The repository also includes shell and PowerShell installers:

curl -fsSL https://raw.githubusercontent.com/svanikhansh/OpenPeach/main/install.sh | sh

irm https://raw.githubusercontent.com/svanikhansh/OpenPeach/main/install.ps1 | iex

The npm postinstall, install.sh, and install.ps1 also fetch gum (the charmbracelet CLI styling tool) next to the peach binaries so command output can render with gum's styles and tables. Gum is optional — set OPENPEACH_NO_GUM=1 to skip it, and the CLI falls back to plain text whenever gum is absent or output is piped.

Commands

openpeach

Launches the interactive TUI. See TUI below for tabs, the command palette, and keyboard navigation.

peach connect

Run this inside a Claude Code project to add OpenPeach's project-level PostToolUse hook to .claude/settings.json.

The hook matches Bash, Read, and Grep output.

On genuinely first use (when ~/.openpeach/ does not exist yet), a one-time welcome block explains what the hook does and what to try next. It is not shown again on later connects in other projects.

peach disconnect

Removes only OpenPeach's PostToolUse hook entry from the current project's .claude/settings.json; unrelated settings and hooks remain unchanged. If it is already absent, the command reports that without failing.

peach status

Prints one scriptable line with connection state, today's intervention count, and today's estimated tokens saved.

peach sessions

Lists recent session logs, newest first, with a shortened session ID, date, intervention count, and tokens saved. Limit the output with peach sessions --limit 5.

peach clean

Preview old session logs without deleting them:

peach clean --older-than 30

The default is a dry run. Add --yes to delete the listed files.

peach stats

Aggregates existing intervention logs from ~/.openpeach/sessions/*.jsonl and prints a plain-text table with all-time and last-seven-days totals, averages, and per-tool breakdowns.

peach export

Generates a shareable savings report (the "show your team what OpenPeach saved" artifact) as a standalone Markdown or JSON file, reusing the same session statistics engine as peach stats.

# Markdown to stdout (default)
peach export

# JSON to stdout
peach export --format json

# Write to a file
peach export --format md --out savings-report.md
peach export --format json --out savings-report.json

If no session logs exist, the command prints a notice and exits non-zero.

peach doctor

Checks the local environment without requiring a live Claude Code session. It verifies Node.js, Claude Code availability and version, project .claude configuration, the OpenPeach hook, both installed binaries, and writable OpenPeach storage.

peach login, peach logout, peach whoami

These commands are local-only authentication placeholders. They do not contact a backend and the generated token is not a security boundary.

peach login
peach whoami
peach logout

peach login writes { token, tier: "free", createdAt } to ~/.openpeach/credentials.json. The hook records the current tier in each intervention log, but tier does not change truncation behavior yet.

peach hook posttooluse

Internal hook handler invoked by Claude Code after matching tool calls. Users normally configure it with peach connect and do not run it manually.

Global flags

Every command with human-readable output accepts --json for machine-parseable output — status, doctor, sessions, connect, disconnect, and stats all emit valid JSON when requested.

peach status --json
peach doctor --json
peach sessions --json

peach --version doubles as a fast one-line environment check. It reports the OpenPeach version, the detected Claude Code version, and whether it meets the minimum required for updatedToolOutput support:

peach --version
# OpenPeach 0.2.0 ・ Claude Code 2.1.240 ・ minimum ok (needs >= 2.1.121)

peach --help (or peach help) prints the grouped, branded command reference with Setup, Usage, and Account sections. The same content is browsable inside the TUI's Help tab.

Color

OpenPeach's identity is a four-tone peach ramp — #FF9A86 (emphasis), #FFB399 (secondary), #FFD6A6 (subdued text), and #FFF0BE (highlights) — applied across the CLI output and both TUIs.

OpenPeach respects the NO_COLOR environment variable and a --no-color flag. When either is set, all brand colors and gradients fall back to plain text; icons (✓ ✗ ⚠ ● ○ → ・) still render uncolored. This matters for CI logs, piped output, and non-interactive shells.

NO_COLOR=1 peach doctor
peach --no-color doctor

When gum is installed and stdout is a real terminal, the CLI commands render through gum: stats and sessions get proper bordered tables, doctor gets status-colored checks, and confirmations render as bold peach lines. Everywhere else (pipes, CI, --json, export) the output is the exact same plain text — gum never changes what scripts parse.

TUI

The TUI is built with Bubble Tea (Go) and styled with Lip Gloss and pterm — the openpeach command runs the compiled binary at tui/openpeach (built with npm run build:tui), falling back to the Ink/React TUI when the binary isn't present.

When the current project isn't hooked up yet, the TUI opens a setup wizard (a huh form): confirm connecting the token-saving hook, pick which tools to intercept (Bash / Read / Grep), and the dashboard takes over — either with the hook live or with a skip note. Reopen it any time with /setup.

The dashboard is organized into three tabs, with the active tab highlighted in the header bar:

• Overview (default): a gradient OpenPeach wordmark with a 400ms left-to-right startup reveal (no ASCII art), connection status, a hero tokens-saved figure that sweeps the peach ramp (pterm RGB gradient), an all-time vs last-7-days stats table, and the seven-day savings trend rendered with progress bars
• History: the five most recent session summaries in a table
• Help: the same grouped command reference as peach --help, inside a scrollable viewport (↑/↓, PgUp/PgDn, Home/End)

Ephemeral toasts confirm quick-command actions (e.g. /connect, /status, setup completion) for ~2 seconds.

Keyboard navigation:

• Tab / Shift+Tab — cycle forward/backward through tabs
• Ctrl+C / Ctrl+D — exit (both restore the terminal cleanly)
• Ctrl+R — refresh workspace status (a spinner runs while it reloads)

Command palette

Typing / in the prompt opens a filterable command palette: typed characters filter the command list live (prefix match on command name), arrow keys navigate, and Enter executes the selection. The numbered fast paths (1–8) still run commands directly, and pressing a digit inside an open palette runs that entry immediately.

Hook behavior

For matching tool output over 2,000 characters, the hook:

1. Applies character-budget truncation with head and tail sections.
2. Preserves important error, failure, assertion, traceback, and diff lines with context.
3. Caps preserved anchor blocks to keep output bounded.
4. Returns the result through hookSpecificOutput.updatedToolOutput.
5. Logs intervention metadata to ~/.openpeach/sessions/<session_id>.jsonl.

Development

npm install
npm run typecheck
npm test
npm run verify
npm run build
npm run dev
npm run dev:cli
npm run build:tui   # compile the Bubble Tea TUI (requires Go)
npm run tui         # run the Bubble Tea TUI from source
npm run test:tui    # run the Go test suite (tui/)

The truncation harness uses realistic PostToolUse JSON fixtures in test/fixtures/ and imports the production truncation function directly. The command suite spawns the built binary end-to-end, and the render suite asserts TUI tabs, palette filtering, the startup reveal, and NO_COLOR behavior.

License

Apache License 2.0. See LICENSE.