Beezi Plugin for Codex

Beezi ships a plugin for Codex that reports session usage to your Beezi workspace and provides personal analytics for your coding activity.

Analytics include tokens, models, tool calls, active time, code-change counts, subagent activity, and the repository or branch the work belongs to. The plugin reads the session records Codex saves locally and sends analytics derived from them. See Privacy & Credential Storage below for the data included in reports, including session names and error messages.

The plugin signs in with your own Beezi account. You must already be a Beezi user; access to analytics follows your account's permissions. You can link more than one Beezi account on the same machine; see Several Beezi Accounts on One Machine below.

1. Requirements

• Codex with plugin support and the /hooks interface.
• Node.js 13.2 or newer, available as node in the environment Codex runs in.
• A Beezi account and access to your Beezi workspace.

Check Node from your terminal:

node --version

The plugin has zero runtime dependencies. Its scripts use Node built-ins, so there is no separate dependency installation or build step for the plugin.

2. Installation

Step 1. Install the plugin.

Add the Beezi marketplace and install the plugin from your terminal:

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

If the Beezi marketplace is already configured, you only need the install command.

Start a new Codex thread after installation so its skills and MCP server load.

Step 2. Link this machine and complete setup.

Ask Codex:

Sign in to Beezi and complete the setup.

Or invoke the $beezi:login skill directly:

$beezi:login

You can also select the Beezi login skill from /skills. The login skill walks through:

1. Browser sign-in. Approve the connection using your Beezi account. If the browser does not open, use the sign-in URL shown in the output. The sign-in waits until you finish in the browser; a slow sign-in is not a failure.
2. Billing and plan capture. The plugin asks Codex for the signed-in account and ChatGPT plan, with local account metadata as a fallback. If it cannot resolve the plan, Codex asks how this machine pays for usage: ChatGPT Free, Plus, Pro ($100/mo or $200/mo), Go, Team, Business, Enterprise, Edu, or an OpenAI API key with no ChatGPT subscription. Pick the Pro option by price; the two Pro plans bill differently.
3. Past sessions. Once the plan question is resolved or dismissed, the plugin uploads eligible past Codex sessions from this machine. It covers the last 30 days only. This can take several minutes and prints progress.
4. Analytics default. If another Beezi account is already linked on this machine and is the one analytics read from, Codex offers to make the new account the default instead. Signing in never switches it on its own.

The plugin installs its analytics hooks automatically. Linking through the beezi_login MCP tool alone connects the account; the login skill also handles plan capture and the history upload.

IMPORTANT

The initial history import is one-time per Beezi account and coding tool, and reaches back 30 days. Sessions older than that are never uploaded, by the import or by a later sync. If you want to include history from other machines, sign in there before the import finalizes. A finalized import cannot be reopened. The separate sync skill repairs missing reporting; it does not reset this import.

Step 3. Trust every Beezi hook.

Inside Codex, run:

/hooks

Review and trust all Beezi entries. Installation alone does not grant trust, and untrusted hooks silently do not run. The plugin cannot grant this trust for you.

Once the machine is linked and all hooks are trusted, eligible sessions report automatically. Start a new thread to check the session-start status.

NOTE

Running the login skill again is safe. It can refresh your captured plan or resume an unfinished history import. Normal plugin upgrades preserve hook trust. Older installations that still use version-specific hook paths need one re-trust when migrated to the stable launcher; changing BEEZI_CODEX_HOME also requires re-trusting the entries.

Keeping the plugin up to date.

To update the marketplace installed above, run:

codex plugin marketplace upgrade

Start a new Codex thread afterwards to load the updated plugin.

The plugin can notify you when a newer version is published, but it does not update itself. It checks at most once an hour, at session start, so update notices depend on the SessionStart hook being installed and trusted.

Several Beezi Accounts on One Machine

You can link any number of Beezi accounts on one machine, for example a work account and a second workspace.

• Every linked account receives this machine's analytics. Each one gets its own copy of the reports.
• The default account only decides which account the analytics summary and Beezi tools read from. Changing it does not change where reports go, and it does not move analytics already reported.
• To add an account, run the login skill again. The browser signs in as whichever Beezi account it is already signed in to, so sign out of Beezi in the browser first or use a private window. Logging in never switches the default.
• To switch the default, use the accounts skill. It lists every linked account, marks the default and any revoked account, and lets you pick another one. If the two workspaces are on different plans, start a new Codex thread so the available tools match.
• To remove an account, use the logout skill. It can log out one account or all of them.
• Each account has its own one-time history import. An import already used by one account does not affect another account.

NOTE

Two different people's accounts from the same Beezi workspace cannot both be linked on one machine. If the workspace is already linked under another email, sign-in is refused with a message such as Workspace <name> is already linked as <email>. Log that account out first to link <your email>. Nothing is stored in that case. This prevents the same sessions from being counted twice in one workspace.

An account linked with an older plugin version may show as linked account (no name or email recorded). This is not an error; its name and email are filled in the next time it reaches Beezi.

3. Commands

In Codex, Beezi commands are provided through skills. Select one from /skills, or describe what you want in conversation. Beezi does not register separate /beezi:* slash commands.

Skill	Example request	Purpose
login	“Sign in to Beezi.”	Link an account, capture the plan, and import eligible history; run again to add another account
accounts	“Which Beezi accounts are linked?”	List linked accounts and choose the default that analytics read from
me	“Show my Beezi link status.”	Check every linked account, the default, the API, and analytics-hook installation
logout	“Sign out of Beezi.”	Log out one account or all of them and remove their stored credentials
analytics-hooks	“Set up Beezi analytics hooks.”	Install, repair, check, or remove the hooks
track	“Save this session's Beezi analytics now.”	Checkpoint the current session without waiting for a hook
analytics	“Show my Beezi analytics for the last 7 days.”	Show your personal usage summary
sync	“Sync my missing Codex sessions to Beezi.”	Upload session and subagent data Beezi has not received
telemetry	“Show my Beezi crash-reporting setting.”	Check, enable, or disable plugin crash reporting

You can also call a skill by name with the $ prefix, for example $beezi:accounts.

Notes on Individual Commands

me shows one block per linked account, with its plan, tracking mode and history-import state, plus one line for the whole machine that says whether analytics are actually being reported. It repairs missing or outdated hooks before it reports. An account marked revoked or expired needs the login skill again, signed in as that account; you do not need to log out first.

track runs the same reporting engine as the hooks and works even when hooks are not installed or trusted. It saves the current session for every linked account and prints one result line per account; use sync for missing history. Asking Codex to run this skill requires a working model interaction.

logout removes the local Beezi credentials even if server-side revocation cannot be completed. If Beezi cannot reach the server, the machine may still appear in the portal's Connections tab, where you can remove it. With several accounts linked, Codex asks whether to log out one account or all of them, and, if you remove the default, which remaining account should become the default. Logging out leaves the analytics hooks installed, but they do nothing while no account is linked: sessions you run while signed out are not captured. Logging out does not change your captured plan or crash-reporting choice, and does not delete anything already reported to Beezi.

telemetry controls optional plugin crash reporting, which is off by default. Ask to check, enable, or disable it. It works on a machine that is not linked. This setting is separate from session analytics and session-error reporting. Turning it on reports only failures that happen afterwards. Disabling it also discards pending crash reports on this machine.

4. Analytics Summary

Ask for your Beezi analytics to get a personal summary of usage, spend, sessions, status, and recommendations. The default window is 30 days; ask for 7 days for a shorter view.

The summary covers your own usage across all coding agents linked to your Beezi account, not only Codex and not your whole team. Figures come from Beezi, and Codex follows the summary instructions provided by the Beezi server.

When several Beezi accounts are linked, the summary is read from the default account only. Use the accounts skill to see or change it.

If authentication fails, sign in to Beezi again. If personal analytics tools remain unavailable on a linked machine, your Beezi administrator may need to enable them for the deployment.

5. How Reporting Works

The plugin installs hooks in the user-level Codex hook registry, normally ~/.codex/hooks.json. It repairs missing or outdated Beezi entries during setup and MCP startup, while leaving a healthy installation unchanged.

Hook	What it does
SessionStart	For every linked account: checks the link and tracking availability, refreshes account information when possible, and retries queued reports. Also captures the plan when needed and checks for plugin updates
PostToolUse	Checkpoints around git commits and branch changes; also checkpoints after tool activity when the 15-minute heartbeat interval has elapsed
SubagentStart	Records a spawned agent's identity and start time
SubagentStop	Records a spawned agent's completion
Stop	Checkpoints usage and the activity timeline at turn end, including subagent usage and available usage-limit observations

Reporting is incremental. Stable report identifiers and saved progress prevent normal retries from counting the same segments twice. Subagent usage is associated with the parent session, and overlapping activity intervals are combined when calculating duration.

While Codex is running, the plugin's MCP server also reads the session records Codex has already written and checkpoints new activity in the background, at most once a minute per session. This covers cases where no hook fires, such as a turn that ends on a usage-limit error. Every 6 hours it also runs a sync for each linked account. Set BEEZI_CODEX_WATCHER=0 to turn this background reading off.

If Codex closes abruptly, already-queued reports remain on disk for retry. Activity after the last checkpoint may need a later checkpoint or history sync before it appears.

Token totals come from Codex's recorded usage, with cached input counted separately from uncached input. Code-change counts are derived from recorded patch operations, so they are not a complete count of every possible file edit.

Where Codex records them, Beezi captures five-hour, seven-day and, on plans that have one, 30-day usage-limit observations.

Plan capture distinguishes ChatGPT subscriptions from API-key billing. Ask to refresh your Beezi plan if it changes or cannot be resolved. Custom third-party providers may require you to identify the billing source because the plugin does not parse provider settings from Codex's config.toml.

Historical imports use the account active during the import; they do not reconstruct which account or plan was active when each old session ran.

What Gets Attributed Where

The plugin uses the working directory recorded during the session and git history to attribute work to the relevant repository and branch. A sanitized origin remote identifies the repository.

NOTE

Work outside a git repository, or in a repository without a resolvable origin, can still be reported under a folder label. That label contains the folder's name, not its full path.

MCP Bridge

The plugin connects Codex to Beezi's MCP server using the credentials stored during Beezi sign-in. This connection provides the personal analytics tools available to your account; there is no second sign-in for MCP.

Available tools depend on your Beezi deployment and account permissions. Before sign-in, the plugin provides tools to link the machine and check its status. After sign-in, the server makes the enabled Beezi tools available in the same thread. With several accounts linked, the tools are served for the default account.

6. Availability

The plugin is free to install. Reporting availability depends on your Beezi workspace:

• Live tracking: eligible new sessions are reported automatically once hooks are trusted.
• Past sessions only: the initial history import is available, but new sessions are not tracked live.
• Tracking disabled: analytics reporting is unavailable for the workspace.

The me skill shows each linked account's mode as tracking live, backfill_only or disabled. The mode is a Beezi workspace setting, not something to fix on the machine. In a workspace that is not on live tracking, reports already queued on the machine are kept for 3 days and then removed.

At session start, the plugin says whether the current repository is connected to a Beezi project. Some workspaces accept reports only from repositories connected to Beezi; the history import and sync then report how many were skipped for that reason. Connect the repository to the appropriate Beezi project if its work should be included.

Use the sync skill when sessions are missing because hooks were untrusted, removed, or reporting was interrupted. It checks Beezi's existing coverage before uploading missing data, so running it again never uploads the same data twice. It reaches back 30 days, the same window as the initial import. It does not reset the one-time initial import, and on-demand sync is unavailable on audit-only plans and in any workspace that is not on live tracking.

With several accounts linked, sync runs for each account in turn and prints a heading before each one; ask for a single account if you only want that one. Every sync also uploads subagent activity Beezi is missing.

If sync leaves sessions for a later run, read the explanation: a delivery backlog, unavailable coverage information, or saved progress that does not match Beezi's records can prevent a safe upload. Some subagents may be left alone on purpose: either live tracking is still delivering them, or they ran before 11 September 2026, when subagent identifiers changed, and sending them again could double-count. If the output says the server does not support history sync yet, your Beezi server needs an update; no history is lost.

7. Privacy & Credential Storage

What Beezi Receives

• Token counts, model and billing information, tool-operation counts (including the names of MCP servers called), and durations.
• Repository and branch attribution, task identifiers when available, and sanitized repository remotes or folder-name labels.
• Session names, activity timelines, and subagent identity and timing metadata.
• Code-change counts derived from patch operations, including files and lines changed.
• Names of skills used in the session, and planning activity (Codex plan mode or planning skills).
• Whether the repository has a project instruction file (AGENTS.override.md or AGENTS.md) and its line count. The file's contents and path are not sent.
• Available usage-limit observations and account identity fields, including the ChatGPT account ID and email when resolved.
• Reportable session-error categories, details, and error-message text, limited to 1,000 characters for the message.
• This machine's hostname and the plugin version, used to name the machine in the portal's Connections tab.

When several Beezi accounts are linked on the machine, each linked account receives these reports.

IMPORTANT

Session names can contain user text. The plugin prefers the Codex thread name and can fall back to the first genuine user prompt, limited to 200 characters. It replaces Windows drive paths and home-folder paths (/Users/…, /home/…) with …; other paths and arbitrary sensitive text are not guaranteed to be removed. Session-error reports can also contain text from recorded API errors.

If you enable optional plugin crash reporting, a crash report contains only structured fields: failure identifiers, a plugin-relative failure location, error class and code, HTTP status where available, plugin and Node versions, OS information, counts, and timestamps. A report has no field that could hold code, prompts, file contents, paths outside the plugin, repository or branch names, error messages, stack text, or credentials.

What Never Leaves the Machine

The analytics pipeline reads local session records, including tool inputs, to derive reports. It does not upload:

• Full conversation transcripts or source files as analytics.
• OpenAI authentication tokens or API keys.
• The contents of your Codex configuration and credentials files.
• Full local file paths as repository or folder identifiers.

Session names and recorded API-error text are included as described above. Your Beezi token is used to authenticate Beezi requests; it is not an analytics field.

Credential Storage

Platform	Where the Beezi token is stored
macOS	Login Keychain
Linux	Secret Service / libsecret, when available
Windows	Windows Credential Manager; DPAPI-encrypted file if Credential Manager is unavailable
Fallback	A permission-restricted file under BEEZI_CODEX_HOME when the OS store is unavailable; this fallback can contain plaintext credentials

Each linked Beezi account has its own credential entry. Codex credentials use a separate Beezi credential namespace (beezi-codex) from the Claude Code plugin. Logging out removes the local Beezi credentials even if server-side revocation cannot be completed.

8. Troubleshooting

Nothing Is Being Tracked

Problem: Sessions run but no analytics appear in Beezi.

Solution:

1. Ask “Show my Beezi link status” to confirm the account and API.
2. Ask Codex to check or repair the Beezi analytics hooks.
3. Run /hooks and trust every Beezi entry. An installed hook can still be untrusted.
4. Start a new thread and read the Beezi messages shown at session start. Check that each account shows tracking live in the me output.
5. Ask to save the current session's analytics and read the result. Use sync for earlier missing sessions.

Commands Are Blocked or Never Run

Problem: Codex describes a Beezi action without running it, or a /beezi:* command is not recognized.

Solution: Select the Beezi skill from /skills or ask for it in conversation. If Codex is in Plan mode, switch to a mode that allows execution. If an approval request appears, review it so the requested script can run. If the skills are missing, confirm the installation with codex plugin list and start a new thread.

Commands Fail With a Node Error

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

Solution: Run node --version and confirm Node 13.2 or newer is available on the PATH used by Codex. Restart Codex after installing Node or changing PATH.

Login Says the Machine Is Already Linked

This is not an error. Continue the login skill to refresh the captured plan and resume any eligible unfinished history import. A completed initial import is not repeated.

If you meant to add a different account, the browser signed in as the account it was already signed in to. Sign out of Beezi in the browser, or use a private window, and run the login skill again.

The Subscription Plan Could Not Be Resolved

Problem: Beezi cannot identify the plan, or analytics show an outdated billing source.

Solution: Ask Codex to refresh your captured Beezi plan. If automatic capture cannot resolve it, answer the billing question, including whether this machine uses an API key or a third-party provider.

If Beezi reports that the Codex sign-in expired, run codex login and start a new session. This refreshes your Codex sign-in; it is separate from linking Beezi.

No beezi Tools Available

Problem: Codex cannot find Beezi's MCP tools, so the analytics summary is unavailable.

Solution:

1. Run codex plugin list to confirm Beezi is installed, then start a new Codex thread.
2. If only beezi_login and beezi_status are available, ask Codex which Beezi accounts are linked. If none are, sign in to Beezi. If accounts are linked but none is marked as the default, choose one with the accounts skill.
3. If those remain the only tools after a successful sign-in with a default account set, or the analytics tools are still missing, ask your Beezi administrator whether the deployment enables the requested tools.

Authentication Errors During MCP Calls

Problem: Beezi MCP calls fail with an authentication error.

Solution: Ask Codex to sign in to Beezi again, complete browser sign-in, and retry the requested action.

Hooks Are Installed but Do Not Run

Problem: Beezi reports that hooks are installed, but automatic tracking or subagent activity is missing.

Solution: Run /hooks inside Codex and review every Beezi entry. Trust all of them, including SubagentStart and SubagentStop, then start a new thread. Installing or repairing hooks does not grant trust. If the entries are missing, ask Codex to repair Beezi analytics hooks first.

If you changed BEEZI_CODEX_HOME or upgraded an older installation that used version-specific hook paths, review and trust the updated entries again.

Analytics Show the Wrong Workspace

Problem: The analytics summary shows figures from a different Beezi workspace than you expected.

Solution: The summary reads from the default account. Use the accounts skill to see which account is the default and switch it. Every linked account still receives this machine's analytics; switching only changes what you read. If the two workspaces are on different plans, start a new Codex thread after switching.

Sign-In Says the Workspace Is Already Linked

Problem: Sign-in is refused with Workspace <name> is already linked as <email>.

Solution: Another account from the same Beezi workspace is already linked on this machine. Use the logout skill to log that account out, then sign in again.

An Account Shows as Revoked or Expired

Problem: The me or accounts skill marks an account as revoked or expired.

Solution: Run the login skill and sign in as that account. You do not need to log out first. A revoked or expired account does not report until it is signed in again; other linked accounts are not affected.

Sign-In Succeeds but Another Check Says “Not Linked”

Problem: Browser sign-in succeeds, but a later status check reports that the machine is unlinked.

Solution: Use the Beezi me skill so the status is checked in the MCP server's environment. That quick check covers the default account only; ask for every linked account if you have more than one. Compare the API reported in the result. Different BEEZI_API_URL or BEEZI_CODEX_HOME settings can make the MCP server and shell scripts use different connections or state directories. Start a new thread after correcting the settings, then sign in again if needed.

Some Past Sessions Were Not Uploaded

Problem: The history import or sync reports skipped or deferred sessions.

Solution: Read the summary for the reason. A repository may need connecting to Beezi, the workspace may restrict reporting, or some sessions may be deferred for a later run. Sessions older than 30 days are skipped for age, and no later run picks them up. An initial import marked finalized cannot be reopened. Use sync only to repair missing reporting that your workspace allows.

The Server Cannot Be Reached

Problem: Tracking reports a network error or says analytics will be retried automatically.

Solution: Check the connection and allow a later checkpoint or session start to retry. Already-queued analytics stay on disk; queued items older than 14 days are removed, so a machine that stays offline longer than that loses them. A server rejection is different from a network failure: keep its exact message for support.

“Nothing new to save” means the current session has no new reportable usage; it is not an error.

9. Getting Help

Contact hello@beezi.ai with:

• Your Beezi tenant ID.
• The skill or command you ran and its exact output.
• Your operating system, Codex version, Node version, and Beezi plugin version.
• Any error message or correlation ID returned by Beezi.

Do not include authentication tokens or credential files.