[Resource]: claude-code-pulse (ccp) #962
Description
Display Name
claude-code-pulse (ccp)
Category
Status Lines
Sub-Category
General
Primary Link
https://github.com/brianruggieri/claude-code-pulse
Author Name
brianruggieri
Author Link
https://github.com/brianruggieri
License
MIT
Other License
No response
Description
Bash wrapper for the Claude Code CLI that updates each terminal pane's title bar in real time using hook events (PreToolUse, PostToolUse, UserPromptSubmit, Stop). Shows the project name, git branch, task summary, and current operation status independently per pane. Built for multi-agent workflows where several Claude Code sessions run in parallel in a split-pane terminal layout.
Validate Claims
Clone and run the test suite (no install required):
git clone https://github.com/brianruggieri/claude-code-pulse.git
cd claude-code-pulse
bash tests/test-suite.shExpected: 149 tests pass, 0 failures.
Verify no ShellCheck warnings:
shellcheck bin/ccp bin/ccp-watch lib/*.sh install.sh uninstall.sh
Expected: exits 0, no output.
Install and watch it live:
./install.sh
ccp "Fix the login bug"
The pane title immediately shows something like:
my-project (main) | Fix the login bug | Idle
As Claude reads files, edits code, and runs tests, the status updates to Reading, Editing, Testing, etc.
The README hero GIF shows four independent panes updating in real time:
https://github.com/brianruggieri/claude-code-pulse/blob/main/docs/screenshots/demo-4pane.gif
install.sh is 132 lines and fully annotated -- you can read it before running anything:
https://github.com/brianruggieri/claude-code-pulse/blob/main/install.sh
Specific Task(s)
Open three or four iTerm2 split panes. In each one, cd into a different project directory and run ccp with a different task. Start giving Claude work in each pane and watch the title bars update independently as each agent reads, edits, and tests.
Specific Prompt(s)
In each split pane, run:
ccp "Refactor the auth module"
Then ask Claude to read a few files, make some edits, and run the test suite. Watch the title bar in that pane update to show Thinking, Reading, Editing, Testing, etc. You shouldn't have to switch focus to panes to know what is happening in the others.
Additional Comments
I built this because I run 3-5 Claude Code sessions in parallel and kept losing track of which pane was doing what. Every other approach I found required switching windows or only worked in the active pane. The title bar is visible across all split panes at once, which is what I actually needed.
Security and side-effects
Hooks: ccp injects hook entries into .claude/settings.local.json when it starts. These entries point to hook_runner.sh, a plain bash script that reads event JSON from stdin and writes short status strings to disk. This is the core mechanism. It's how ccp knows what Claude is doing. Entries are tagged with the session PID and removed automatically when ccp exits (via trap EXIT). You can inspect them while a session is running:
cat .claude/settings.local.json | jq '.hooks'State files: hook_runner.sh writes to ~/.config/claude-code-pulse/status.<pid>.txt and context.<pid>.txt. A background monitor reads these to drive title bar updates. No other files are written or read. State files are cleaned up on exit.
PATH extension: hook_runner.sh adds /opt/homebrew/bin and /usr/local/bin to PATH. Claude Code invokes hooks with a minimal PATH (/usr/bin:/bin only), so jq is not reachable without it. Line 18 of hook_runner.sh has an inline comment explaining this.
Network calls: none by default. The optional --ai-context flag calls claude --print --model claude-haiku-4-5-20251001 to distill the user's prompt into a 3-5 word title label. This only calls the Anthropic API, is opt-in, uses the user's Claude subscription (no third-party service), and prints a disclosure at startup when enabled.
A zero-API-call alternative is available via --ai-context-strategy inline, which injects a short system prompt into the outgoing Claude request instead of spawning a separate haiku call. Same result, no extra subscription usage.
No auto-update mechanism of any kind.
Does not require --dangerously-skip-permissions.
ccp sets CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1 before launching Claude. Claude Code writes its own OSC title escapes and without this flag the two would fight over the title bar. This is the intended use of that env var.
Install and uninstall
Install (user-local, no sudo):
./install.shFiles go to ~/.local/share/ccp/
Symlinks created at ~/bin/ccp and ~/bin/ccp-watch
Uninstall:
~/.local/share/ccp/uninstall.shQuality
149 passing tests, ShellCheck clean on all files, GitHub Actions CI on every push, MIT license.
Recommendation Checklist
- I have checked that this resource hasn't already been submitted
- It has been over one week since the first public commit to the repo I am recommending
- All provided links are working and publicly accessible
- I do NOT have any other open issues in this repository
- I am primarily composed of human-y stuff and not electrical circuits