Claude Companion

Live sidebar panel for Claude Code — an animated mascot, tool activity feed, session stats, and contextual suggestions. Available as a VS Code extension, a macOS menu-bar corner anchor, and a CLI.

Status: pre-1.0. Core features stable; some features (e.g. Apple notarization, VS Code Marketplace publish, public relay) are still being prepared for public release.

What it does

• Live mascot that reacts to what Claude is doing (idle, thinking, running tools, writing files, hitting errors).
• Per-session stats: tool calls, files touched, errors, duration, tokens spent, cache savings.
• Streak tracking: consistency, depth, flow, width, endurance, recovery — computed locally from your hook history.
• Friend feed (optional, requires sign-in): see your friends' streak scores. No content, no prompts, no file names ever shared.

Install

CLI + macOS anchor

npm install -g claude-companion-app
claude-companion install

claude-companion install will:

• Write the hook commands into ~/.claude/settings.json (safe-merged with anything already there).
• Drop a tiny launcher in ~/Library/LaunchAgents/ so the macOS anchor starts at login.
• Add a streak badge to your shell prompt (zsh / bash / fish).

To remove everything later: claude-companion uninstall (or uninstall --purge to also wipe local stat history).

VS Code extension

Marketplace publish is in progress. For now you can sideload from a locally-built .vsix:

cd claude-companion
npm install && npm run compile
npx vsce package
code --install-extension claude-companion-*.vsix

Privacy

Runs locally by default. Nothing leaves your machine unless you explicitly run claude-companion login.

When you do sign in (optional, for cross-device streaks and friend features), we sync only:

• Computed numbers (streak score, consistency %, etc.)
• Calendar dates you were active (no content)
• A hashed device label (real hostname is never sent)
• Your GitHub username (already public)

We never send: code, prompts, file names, file contents, command strings, tool outputs. See PRIVACY.md and TERMS.md.

Your GitHub OAuth token is stored in your operating system's keychain (macOS Keychain Access / Linux libsecret / Windows Credential Vault), not in a plaintext file. Run claude-companion doctor to confirm.

Run claude-companion forget-me at any time to wipe everything from our servers.

Common commands

claude-companion install        # set up hooks, anchor, shell badge
claude-companion uninstall      # remove hooks (keeps local stats)
claude-companion login          # optional cloud sync (GitHub OAuth)
claude-companion logout         # sign out (keeps local stats)
claude-companion forget-me      # delete all server-side data
claude-companion status         # show daemon + sync state
claude-companion doctor         # self-check; pass --verbose for detail
claude-companion backup         # export everything to a JSON file

Architecture (brief)

┌──────────────┐  hooks  ┌──────────┐  unix-socket  ┌──────────────┐
│ Claude Code  │ ──────► │  daemon  │ ────────────► │  VS Code ext │
└──────────────┘ + NDJSON└──────────┘  + NDJSON     │  + Mac anchor│
                              │                     └──────────────┘
                              │ syncProfile() every 10 min (optional)
                              ▼
                         relay server ──► Supabase (RLS)

• Hooks fire on every tool call, error, session end — written into ~/.claude/settings.json at install time.
• Daemon (Node) consumes events, computes stats, owns the truth for the on-disk state at ~/.companion/.
• VS Code extension + macOS anchor both render the same panel HTML (media/companion-panel.html).
• Relay is optional; only runs server-side aggregation. All secrets (Supabase keys) stay on the relay, never on clients.

For deeper architecture notes see /Users/bukyadinesh/Desktop/work/rough/impl/Impl_architecture/ (internal; not shipped).

Troubleshooting

| Symptom | First thing to try | |---|---| | Anchor not showing | claude-companion doctor --verbose | | Streak not updating | claude-companion status — daemon alive? | | Sign-in fails | check ~/.companion/auth.json perms; re-run login | | Anchor stuck after Claude crashed | will self-heal at next session |

If doctor reports stale hook commands in ~/.claude/settings.json (e.g. older || pattern), run claude-companion install again to refresh them.

Full troubleshooting guide: TROUBLESHOOTING.md.

Feedback

We'd love to hear from you — bugs, feature ideas, or just how it's going:

Give Feedback or run claude-companion feedback in your terminal.

Contributing

Internal repo for now. PRs welcome once we open up.

License

See LICENSE.