Beezi Plugin for Claude Code

Beezi ships an official plugin for Claude Code. Once installed and linked, it reports what each session used — tokens, tool calls, which model led, which skills and MCP servers were invoked, active time, code-change counts, and the branch or repository the work belongs to.

Everything reported comes from what Claude Code records about a session. The plugin does not read your prompts, your model's responses, or your file contents.

The plugin signs in with your own Beezi account. You must already be a Beezi user — everything it does happens as you, on your tenant.

1. Requirements

• Claude Code with plugin support.
• Node.js 13.2 or newer, available on your PATH as node.
• Zero dependencies — the plugin runs on Node built-ins alone, so /plugin install works immediately with nothing to install or build, on every platform.

Every command and hook the plugin ships is a Node script, so the node binary must be resolvable in the environment Claude Code runs in. Check yours with:

node --version

NOTE

Node 13.2 is the floor because the plugin is ESM-only — that is the first release to load ES modules without a flag. On an older runtime, the scripts cannot start, so no analytics are reported. Any current Node LTS release is comfortably above the floor.

2. Installation

IMPORTANT

Plan mode and auto mode can stop some scripts from running — switch to another mode before running these steps. Shift+Tab cycles modes.

Step 1. Add the marketplace and install the plugin.

/plugin marketplace add https://github.com/Beezi-AI/beezi-claude-plugin
/plugin install beezi@beezi

Step 2. Link this machine.

/beezi:login

/beezi:login opens Beezi's sign-in page in your browser and finishes once you approve there. It then walks a short setup:

1. Subscription plan. Records which Claude plan this machine bills against, so it reports spend accurately. If it cannot be determined, Claude asks you — including an option for machines that pay per token with an API key rather than a subscription.
2. Live usage status line (optional). Claude offers to wrap your Claude Code status line so Beezi can record the plan-usage numbers Claude Code already computes. No extra requests are made, and any status line you already have keeps rendering unchanged. Declining is fine — usage is still captured, just less often.
3. Past sessions. Uploads the Claude Code history already on this machine, so your analytics are populated from the start rather than beginning at zero. This can take several minutes and prints progress as it goes.

After that, it tracks work automatically. There is nothing else to run.

NOTE

Re-running /beezi:login on an already-linked machine is safe. It is the supported way to refresh a changed subscription plan, install the status line later, or resume an interrupted upload of past sessions.

Optional Configuration

Variable	Default	Purpose
BEEZI_API_URL	https://beezi-api-prod.azurewebsites.net/api	Beezi API base URL
BEEZI_MCP_URL	<API URL>/mcp	Beezi MCP server used for the analytics summary
BEEZI_HOME	~/.beezi	Local state root (queue, cursors, credentials fallback)

3. Commands

Commands are slash commands shipped by the plugin. Each one runs a fixed local script — Claude is instructed not to read or inspect files on your behalf, and never to echo a token.

Command	Purpose
/beezi:login	Link this machine and run the setup above
/beezi:me	Show whether this machine is linked, and as whom
/beezi:logout	Unlink this machine and delete the stored credentials
/beezi:track	Save the current session's analytics without waiting for it to end
/beezi:refresh	Re-capture this machine's Claude subscription plan

Notes on Individual Commands

/beezi:track saves the session the moment the command is submitted, with no model round trip, and shows its result as a system message. It therefore works even when the model is unavailable — an outage, or no credits. It fails only if the machine is not linked, the transcript cannot be found, or the server rejects the report.

/beezi:logout always signs out locally, even when it cannot reach the server, so a machine can never be left holding credentials it cannot revoke.

4. Analytics Summary

The plugin ships one skill, analytics. Ask for your Beezi analytics summary and you get a short personal read — spend, sessions, top model, an alert status, and up to three recommendations.

The default window is the last 7 days; ask for 30 days to widen it. The summary always covers only the person asking, whatever their role — it is a personal read, not a team report. The figures come from Beezi; the wording is generated by your own model.

If the machine isn't linked or authentication fails, Claude replies, "Sign in to Beezi first."

NOTE

analytics is a skill, not a slash command. Ask for it in conversation rather than typing a command.

5. How Reporting Works

The plugin registers hooks on Claude Code's session lifecycle. Each hook is a small Node script that runs locally, reads the session transcript, and reports a summary to Beezi.

Hook	What it does
SessionStart	Verifies the machine link and prepares repository attribution
UserPromptSubmit	Runs the manual save for /beezi:track, and pings live usage
PostToolUse	Saves an incremental checkpoint and a lightweight activity pulse
PreCompact	Captures usage before the conversation is compacted
SubagentStop	Captures usage when a subagent finishes
Stop / StopFailure	Records turn completion and turn-level failures
SessionEnd	Ships the final session report

Reporting is incremental, and overlapping hook runs never double-count the same work.

What Gets Attributed Where

Work is attributed to a repository when the session resolves to a git repository root with an origin remote. Each part of the session is attributed to the repository it actually ran in — so research turns, thinking, and whole subagents land where the work happened, not wherever the session was launched.

NOTE

Work outside any git repository, or in a repository with no reachable origin, is not discarded. It is reported under a folder label — only the folder's own name travels, never the path around it.

MCP Bridge

The plugin ships a stdio bridge that forwards MCP traffic to the Beezi server, authenticated with the credentials stored by /beezi:login — there is no second sign-in prompt for MCP. The bridge is generic: it exposes whatever tools the server offers for your account, which is how the analytics summary stays current without shipping its workflow in the plugin.

6. Availability

The plugin is free to install. What it reports depends on your Beezi tenant.

• Live tracking — the normal mode. Past sessions are uploaded when you link the machine, and new sessions are reported as they happen.
• Past sessions only — the upload of existing history runs, but new sessions are not tracked.

Claude Code tells you which one applies at session start, and points at the next step when there is one. A tenant's mode is determined by its Beezi plan — if tracking isn't what you expect, check your plan in the Beezi portal or ask your tenant owner.

You can upload past sessions once per account.

Which repositories can be reported also depends on the tenant: some accept only sessions from repositories connected to Beezi, and reject the rest.

7. Privacy & Credential Storage

What Beezi Receives

• Token counts, tool-call counts, and durations.
• Branch name, task id, and the sanitized origin remote of the repository — or a folder-name-only label when the work was outside any repository.
• The session name and its activity timeline.
• A per-category breakdown of operations (file, search, internet, MCP, shell, skill, other), a per-server tally for MCP calls and a per-skill tally for skill calls, and, for subagents, the agent type and spawn depth.
• Code-change counts for the session: files changed, lines added, lines removed, and a count of files per file extension.

What Never Leaves the Machine

• Your prompts, the model's responses, and the contents of your files.
• Your Beezi authentication token.
• The contents of your local Claude configuration file. The plan capture reads only the non-secret account fields from it — never a token, never the credentials file.
• File paths, and the path around a folder. Only a folder's own name is ever sent for work outside a repository.

Credential Storage

The /beezi:login token is stored in your operating system's own secret store via its built-in CLI — no native module and no extra install:

Platform	Where the token is stored
macOS	The login keychain
Linux	Secret Service / libsecret, when available
Windows	DPAPI (user-bound encryption); the ciphertext is kept in a file
Fallback	A permission-restricted (0600) file under BEEZI_HOME (default ~/.beezi/) when no store is available

8. Troubleshooting

Nothing Is Being Tracked

Problem: Sessions run but no analytics appear in Beezi.

Solution:

1. Run /beezi:me to confirm this machine is linked and that it's the account you expect.
2. Read the message Claude Code shows at session start — it says when a tenant isn't tracking live or when a repository isn't connected.
3. Run /beezi:track to force a save and read the error it reports.

Commands Are Blocked or Never Run

Problem: A /beezi:* command produces no output, or Claude describes what it would do instead of running it.

Solution: Check which mode Claude Code is in. Plan mode and auto mode can stop the plugin's scripts from running. Press Shift+Tab to cycle modes, switch out of plan or auto mode, and run the command again.

Commands Fail With a Node Error

Problem: A Beezi command exits immediately, or reports that node was not found or that it cannot load a module.

Solution:

1. Run node --version. It must report 13.2 or newer.
2. If nothing is reported, Node is not on the PATH that Claude Code uses. Install Node (any current LTS) and restart Claude Code so it picks up the updated PATH.
3. If the version is older than 13.2, upgrade — the plugin is ESM-only and cannot start on earlier runtimes.

/beezi:login Says the Machine Is Already Linked

Not an error. Continue the flow — the plan capture, status line offer, and history upload still run, which is exactly how you refresh a changed subscription plan or finish an interrupted upload.

The Subscription Plan Could Not Be Resolved

Problem: Login reports that no Claude subscription info was found, or that it kept the self-reported plan.

Solution: Answer the question when Claude asks it, and run /beezi:refresh later if your plan changes. If this machine pays per token, choose the API-key option — otherwise its spend is reported under a subscription tier it does not have.

No beezi Tools Available

Problem: Claude reports it cannot find the Beezi MCP tools, so the analytics summary is unavailable.

Solution:

1. Run /mcp and confirm the beezi server is connected.
2. If it is connected but no tools are listed, MCP tools are switched off for your Beezi deployment — a Beezi admin can enable them.

Authentication Errors During MCP Calls

Problem: MCP calls fail with an authentication error.

Solution: Run /beezi:login again to re-link the machine.

Some Past Sessions Were Not Uploaded

Problem: The upload reports that a repository is not connected to Beezi.

Solution: Expected on a tenant that only accepts connected repositories. Connect the repository to a Beezi project if that work should be tracked; otherwise, the rejection is correct.

9. Getting Help

If you encounter issues not covered here:

• Support Email: hello@beezi.ai
• Check Beezi Status: Verify no ongoing service issues

When contacting support, include:

• Your Beezi tenant ID
• The command or skill you ran, and its exact output
• Your operating system and Claude Code version
• Error messages or screenshots