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/](./ ../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.