Skip to main content

Beezi Plugin for Codex

NOTE

This page covers the full plugin, beezi. For the read-only beezi-analytics plugin, which shows your usage summary and records nothing, see Beezi Analytics Plugin.

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. If your account belongs to several workspaces, you choose which workspaces receive the analytics for each repository or folder; see Choosing Where Analytics Go below.

1. Requirements​

  • Codex with plugin support and the /hooks interface. The Codex CLI, the ChatGPT desktop app, and the Codex extension for VS Code and similar editors all read the same ~/.codex folder, so one installation covers each of them on the machine. JetBrains AI keeps its own Codex settings and is not covered.
  • 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.

You can install the plugin with the Beezi installer or with Codex's own plugin commands. Both install the same plugin from the Beezi marketplace.

Option A: the Beezi installer. On macOS or Linux, run this in a terminal:

curl -fsSL https://beezi.ai/codex/install.sh | bash

On Windows, run this in Windows PowerShell 5.1 or PowerShell 7:

irm https://beezi.ai/codex/install.ps1 | iex

The installer finds Codex on the machine and starts right away, without asking anything. It adds the Beezi marketplace, installs or updates the plugin, and, when Node is available and no Beezi account is signed in yet, continues straight into the sign-in and the one setup question in the terminal (Step 2 below). Without an interactive terminal it skips the setup, as with --yes. The macOS and Linux installer needs bash (not sh) and git. The installer only runs Codex's own plugin commands and the plugin's setup; it never edits Codex's config.toml itself.

To install or update without the setup in scripted setups, use:

curl -fsSL https://beezi.ai/codex/install.sh | bash -s -- --yes
$env:BEEZI_YES = '1'; irm https://beezi.ai/codex/install.ps1 | iex

With --yes, the installer does not run the terminal setup. Sign in from Codex afterwards, as described in Step 2.

Option B: Codex plugin commands. 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.

If the installer already took you through sign-in in the terminal, continue with Step 3. Otherwise, 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, like the terminal setup, 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. It does not ask you; if it cannot resolve the plan, set it later with the settings skill.
  3. What to track. Codex shows how many past sessions it found and what is sent from them, then asks one question: Everything, or Let me choose the repositories and folders to track. For an account in several workspaces, the options name the workspaces. Once you have answered on this machine, the question is not asked again.
  4. Past sessions. The eligible past Codex sessions from what you track upload in the background. The upload covers the last 30 days only.
  5. Crash reports are turned on, unless you already chose.

The plugin installs its analytics hooks automatically. Linking through the beezi_login MCP tool alone connects the account; the login skill also handles what to track, 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. For an account in several workspaces, each workspace has its own import, and an import stays open while some repositories or folders still wait for you to choose where they go. 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.

While the Beezi hooks are installed but not trusted, the plugin adds a short reminder to your global Codex instructions file, so the next session starts by asking you to fix it:

Beezi analytics hooks are not trusted in Codex, so this session isn't being tracked. Run /hooks, trust the Beezi entries, then reply "done" — or "skip" to continue without analytics.

Reply “done” after trusting the entries. Codex checks the trust state again and, once the hooks are trusted, removes the reminder and continues with your request. Reply “skip” to continue without analytics for that session; the reminder returns in the next session until the hooks are trusted.

Once the machine is linked and all hooks are trusted, eligible sessions report automatically. Start a new thread to see the session banner, which confirms who you are signed in as and where the current folder's analytics go.

NOTE

Running the login skill again is safe. It can refresh your captured plan, or ask what to track if you dismissed the question. 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

Running the Beezi installer again also updates an older installation. 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. You can also ask for your Beezi status to see the installed version and the update steps, or use the release-notes skill to see what changed.

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, following that account's own workspace rules. 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 settings skill and choose Account, then Default account. Settings lists every linked account and its sign-in health. 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 people from the same Beezi workspace can both link their accounts on one machine. If both accounts send analytics to that workspace, the workspace counts the same sessions twice. Use a workspace rule or the logout skill if that is not what you want.

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.

SkillExample requestPurpose
login“Sign in to Beezi.”Link an account, choose where its analytics go, capture the plan, and import eligible history; run again to add another account
settings“Show my Beezi settings.”See linked accounts and where this folder's analytics go; change workspace rules, New folders, the default account, the captured ChatGPT plan, and crash reports
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
release-notes“What's new in Beezi?”Show the installed version's release notes, every release, or one named version

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

Two actions are provided as Beezi MCP tools rather than skills: beezi_login signs in, and beezi_status reports your link status. Ask “Show my Beezi link status” to use beezi_status. It reports whether this machine is linked and as which account (the default account when several are linked), the Beezi API the plugin talks to, whether analytics are being reported and the analytics hooks are installed and trusted, where this folder's analytics go for each linked account, and the installed plugin version with update steps when a newer one is published. It repairs missing or outdated hooks before it reports.

Notes on Individual Commands​

settings starts with a short screen: the linked accounts and the default, a sign-in line when a sign-in needs attention, where this folder's analytics go, how many rules there are, and the crash-reporting setting. It then asks what you want to change: Rules, New folders (only for an account in several workspaces), Account, or Crash reports. Each choice shows its current state. Under Account you can refresh the captured ChatGPT plan and, with several accounts linked, pick the default account. A rule or New folders change ends with “Undo: ask the settings skill to undo.” Asking to undo puts your last change back. 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. If the folder has no rule yet and the account is set to ask, the line says the analytics are held and not sent, and Codex asks where they should go. 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.

release-notes shows the notes shipped with the installed plugin, with a short table of the releases before it, and the update steps when a newer version is published. Ask for all releases or name a version, such as 0.23.1. It does not contact the server and does not run the update for you.

Crash reports are part of the settings skill and control optional plugin crash reporting. The setup (the terminal installer or the login skill) turns them on in Correlate mode unless you already chose. Until then they are off: Beezi mentions it once at a session start and points you to the settings skill, and nothing is sent. The modes are:

ModeWhat it does
CorrelateSends crash reports with a random installation ID, so support can match a report to your account. This is the recommended way to turn reports on
OnSends crash reports without an installation ID; Beezi may offer Correlate once
AnonymousSends crash reports without an installation ID, deletes any existing installation ID, and never offers one again
OffSends nothing and deletes pending reports and the installation ID

Ask to check or change the mode, for example “Turn Beezi crash reports off.” 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.

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 settings skill (Account, then Default account) to see or change it.

For an account in several workspaces, you can name the workspace in your request, for example “Show my Beezi analytics for 7 days in Acme.” The answer then ends with a line such as Beezi: reading from Acme. Choosing a workspace to read from does not change where analytics are reported.

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 sign-in, MCP startup, status checks, and the settings screen, while leaving a healthy installation unchanged. The entries run a small launcher at a fixed path under BEEZI_CODEX_HOME, which always runs the newest installed plugin version, so an upgrade does not change the entries or their trust.

HookWhat it does
SessionStartFor every linked account: checks the link and tracking availability, refreshes account information when possible, and retries queued reports. Shows the session banner, asks where analytics go when the folder has no rule yet, and says whether the repository is connected to a Beezi project. Also captures the plan when needed and checks for plugin updates
PostToolUseCheckpoints around git commits and branch changes; also checkpoints after tool activity when the 15-minute heartbeat interval has elapsed
SubagentStartRecords a spawned agent's identity and start time
SubagentStopRecords a spawned agent's completion
StopCheckpoints 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, and for each workspace an account sends analytics to. 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.

The Session Banner​

Once you are signed in, every new Codex thread starts with a short Beezi banner. It names the account you are signed in as and its workspaces, and says where the current folder's analytics go, or that the folder has no rule yet and nothing is sent until you choose. With several accounts linked, it shows one line per account. If a workspace does not track new sessions, the banner says so, for example new sessions are not tracked (audit mode). The banner needs the SessionStart hook to be installed and trusted.

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.

Choosing Where Analytics Go​

Each linked account decides where this machine's analytics go, per repository or folder. You manage this with the settings skill.

  • Rules send a repository's or folder's analytics to one or more workspaces, or mark it Don't track so nothing from it is sent. A repository rule matches the repository's remote; otherwise the longest matching folder wins, and a folder rule covers everything inside it. Sessions in your home folder, the root folder, or a temporary folder share one rule for sessions outside a project. A rule follows each part of a session, so changing folders during a session respects the destination's rule.
  • New folders applies only to an account in several workspaces. It decides what happens in a repository or folder with no rule: Ask me (Beezi asks once, when a session starts there), Send to… (the workspaces you pick), or Don't send.
  • An account in one workspace sends everything to that workspace by default. Its rules let you stop tracking a repository or folder, and track it again later.

The rules table shows a Default row for everything without a rule, marks the rule that covers the folder you are in with ← you're here, and lists each rule's path or remote and its sessions over the last 30 days. To add a rule for another folder, pick it from your most-used repositories and folders, or type a folder path or repository URL.

With Ask me, analytics for a folder with no rule are held on this machine, not sent, until you answer. They wait for up to 3 days. Answering with one or more workspaces sends them on the next checkpoint; answering Don't track drops them. If you dismiss the question, the next session start, track run, login, or sync asks again.

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.

Configuration​

The plugin works without configuration. These environment variables are available for special setups; the MCP server only receives the ones Codex passes to it.

VariableDefaultPurpose
BEEZI_API_URLhttps://api.beezi.ai/apiThe Beezi API the plugin reports to
BEEZI_CODEX_HOME~/.beezi-codexThe plugin's queue, state, fallback credentials, and hook launcher
CODEX_HOME~/.codexWhere the plugin reads Codex's session records and hook registry
BEEZI_CODEX_WATCHERonSet to 0 to turn off background reading of session records
BEEZI_CODEX_APP_SERVERonSet to 0 to stop the plugin from asking Codex for the plan and the hook trust state
BEEZI_CODEX_CLIcodexThe path to the Codex CLI, when it is not on the PATH

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 and on-demand sync are available, but new sessions are not tracked live.
  • Tracking disabled: analytics reporting is unavailable for the workspace.

The mode is a Beezi workspace setting, not something to fix on the machine. The session banner and the beezi_status tool say when a workspace does not track new sessions or has analytics turned off. 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. Sessions in a repository that is not connected are still tracked, against the repository itself. 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. On-demand sync also works for workspaces on audit-only plans; the automatic 6-hour background sync runs only for workspaces on live tracking.

Before uploading, sync asks the same questions as the login skill when they are open: which repositories and folders should go to a workspace you joined recently, and where repositories and folders with no rule should send their past sessions. Each past session then goes where its own repository's or folder's rule sends it. Sessions in folders you do not track are skipped.

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. For an account in several workspaces, it also prints a heading for each workspace. 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 sessions are left alone on purpose and a later run does not change that: for an account in several workspaces, a session whose history was split between workspaces cannot be resumed safely. Some subagents may also 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 for the repositories and folders its rules send to it. Nothing is sent for a repository or folder marked Don't track, or for one that is still waiting for you to choose a workspace.

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, sign-in state, plugin and Node versions, OS information, counts, and timestamps. In Correlate mode it also carries a random installation ID. 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.

Files the Plugin Changes on This Machine​

  • ~/.codex/hooks.json: the plugin adds its own entries and leaves hooks you configured yourself untouched. Removing the hooks with the analytics-hooks skill removes only Beezi's entries.
  • ~/.codex/AGENTS.md: while the Beezi hooks are installed but not trusted, the plugin keeps a marked Beezi section in this file for the trust reminder. If you use ~/.codex/AGENTS.override.md, the section goes there instead. Everything else in the file is left as it was, and the section is removed once the hooks are trusted. Set BEEZI_CODEX_APP_SERVER=0 to turn this check off.
  • BEEZI_CODEX_HOME (normally ~/.beezi-codex): queued reports, session state, settings, and the hook launcher.

Credential Storage​

PlatformWhere the Beezi token is stored
macOSLogin Keychain
LinuxSecret Service / libsecret, when available
WindowsWindows Credential Manager; DPAPI-encrypted file if Credential Manager is unavailable
FallbackA 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, the API, and the hook trust state.
  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 banner shown at session start. Check that the folder's analytics go to a workspace and are not held for a choice or marked as not tracked. Use the settings skill (Rules) to change it.
  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. Beezi scripts read the system credential store and files in your home folder, so Codex asks you to approve each one outside the sandbox; review and approve the request. If the session cannot ask for approvals (an approval policy of never), Beezi says so and asks you to restart Codex with codex --sandbox workspace-write --ask-for-approval on-request, or to change permissions with /permissions. 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, answer any open workspace questions, 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, or use the settings skill (Account, then Refresh my ChatGPT 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 settings skill (Account, then Default account).
  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. Ask “Show my Beezi link status” afterwards; its hook trust line confirms whether Codex now trusts the entries.

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 settings skill (Account, then Default account) 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. For an account in several workspaces, name the workspace in your analytics request and check the Beezi: reading from line in the answer.

Analytics Go to the Wrong Workspace​

Problem: A repository's or folder's analytics arrive in a workspace you did not intend, or in none.

Solution: Use the settings skill and choose Rules. The table marks the rule that covers the folder you are in with ← you're here. Change where that rule sends analytics, add a rule just for this folder, or remove the rule. If you changed something by mistake, ask the settings skill to undo it. Rules change where new analytics go; they do not move analytics already reported.

An Account Shows as Revoked or Expired​

Problem: The settings skill or the status check 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: Ask “Show my Beezi link status” so the status is checked by the beezi_status tool in the MCP server's environment, and compare the API reported in the result. That quick check describes the default account's link; use the settings skill to see every linked account's sign-in state. A Beezi script that ran inside the Codex sandbox cannot read the credential store and can wrongly report that no account is linked; approve it to run outside the sandbox. Different BEEZI_API_URL or BEEZI_CODEX_HOME settings can also 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, some repositories or folders may still need a rule or be marked as not tracked, 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.