Beakr agent plugins

Install Beakr into your coding agent in one step. Beakr is your team's organizational memory: decisions, processes, ownership and dated events. With this plugin your agent can research it with citations, read and write the knowledge base, and start each session knowing what your team knows.

Client	What you get	Install
Claude Code	skill, MCP server, slash commands, session hooks	plugin
Codex	skill, MCP server	plugin
Cursor	skill, MCP server	plugin or one-click MCP
VS Code (Copilot)	skill, MCP server	plugin or MCP config
Gemini CLI	skill, MCP server, context file	extension
Claude.ai, Cowork, Claude Desktop, ChatGPT	MCP server	hosted connector (not live yet)

Before you install

Every plugin talks to Beakr through the beakr CLI's local MCP server (beakr mcp). Install the CLI and sign in once. The flags keep the installer from wiring Beakr into your agents itself; the plugin does that:

curl -fsSL https://raw.githubusercontent.com/BeakrHub/beakr-cli/main/install.sh | sh -s -- --no-auth --no-mcp --no-skills --no-hooks
beakr auth login

Use a plugin or beakr setup, not both. Run with no flags, the installer runs beakr setup, which registers the same beakr MCP server, skill, kb-* commands and session hooks directly in Claude Code and Codex. A plugin installed on top of that gives your agent every Beakr tool, the skill and the commands twice. If you already ran the full installer or beakr setup, remove what it wired before installing a plugin with beakr setup --uninstall (your sign-in stays). For Claude Code and Codex alone, beakr setup without a plugin is enough; the plugins add Cursor, VS Code and Gemini CLI, the /beakr:setup check, and updates through each client's plugin manager.

The installer installs uv if needed and puts beakr in ~/.local/bin. It installs the CLI from GitHub (uv tool install git+https://github.com/BeakrHub/beakr-cli), not from PyPI: PyPI still has 0.3.3, and the session hooks and current MCP tools need 0.4.0 or later. If you installed from PyPI before, run the installer again to replace it.

Signing in. Use one of these; the local MCP server, the hooks and the Beakr SDKs all pick up whichever you choose:

beakr auth login: a browser sign-in with your Beakr account, through your organization's single sign-on when it has one. Best for a person on their own computer: there is no key to create, store or rotate, and the sign-in renews itself.
An API key, created in Beakr under Settings: save it with beakr auth login --with-api-key, which asks for the key without showing it (or reads it from a pipe: echo "$BEAKR_KEY" | beakr auth login --with-api-key), or set BEAKR_API_KEY (and BEAKR_BASE_URL for a non-production instance) in the environment your agent starts from. Never put the key itself on the command line: it stays in your shell history. Use a key for automation, CI and servers, or when you want access narrowed to some scopes or projects.

If more than one beakr is installed (for example a self-hosted installation's own client next to this one), set BEAKR_BIN to the one the plugin should run; the TypeScript SDK reads BEAKR_CLI_PATH for the same purpose.

Without the CLI the plugins still install, but the Beakr tools stay unavailable: the MCP server exits with install instructions and the hooks do nothing.

Claude Code

/plugin marketplace add BeakrHub/beakr-agent-plugins
/plugin install beakr@beakr

From a terminal: claude plugin marketplace add BeakrHub/beakr-agent-plugins && claude plugin install beakr@beakr. Restart the session, then run /beakr:setup to check that everything is connected.

What it installs:

The beakr skill: how to search, research, write and audit the knowledge base, and when to propose capturing something durable.
The beakr MCP server (beakr mcp): research, knowledge_base, knowledge_base_write, list_projects and the rest of Beakr's tools, all listed from the start (see MCP server settings).
Slash commands: /beakr:kb-search, /beakr:kb-research, /beakr:kb-write, /beakr:kb-audit, and /beakr:setup.
Session hooks, the same ones beakr hooks install writes into settings.json:
- SessionStart runs beakr context --format claude_md --project auto --hook, which adds your Beakr context (profile, recent activity, relevant memories and skills) to the session.
- Stop and SessionEnd run beakr compound --hook --client claude-code --background, which captures the session into Beakr. Capture only happens in a repository that opted in with beakr init --capture or beakr hooks capture on; everywhere else these hooks upload nothing.
If you already ran beakr hooks install, the plugin's hooks stand down so nothing runs twice. To stop capture in a repository, run beakr hooks capture off there; to drop the hooks entirely, disable the plugin with /plugin.

Codex

codex plugin marketplace add BeakrHub/beakr-agent-plugins
codex plugin add beakr@beakr

This installs the beakr skill and the beakr MCP server. Codex plugins get no session hooks here. For Beakr context and capture in Codex, start it through the CLI with beakr codex (refreshes a Beakr block in ~/.codex/AGENTS.md before each session and captures the session afterwards, if the repository allows it).

Without the plugin, register the server by hand: codex mcp add beakr -- beakr mcp, or paste examples/codex/config.toml into ~/.codex/config.toml. Then add examples/codex/AGENTS.md to ~/.codex/AGENTS.md so Codex knows when to use Beakr.

Cursor

Plugin (skill and MCP server): in Cursor's Customize panel, add a plugin From GitHub Repository and enter BeakrHub/beakr-agent-plugins.

MCP server only: use the one-click link below, or copy examples/cursor/mcp.json into ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project).

VS Code

Plugin (skill and MCP server): add the repository as a plugin marketplace in your user settings, then install beakr from the Chat view's plugins list.

"chat.plugins.marketplaces": ["BeakrHub/beakr-agent-plugins"]

MCP server only: use the install link or code --add-mcp command below, or copy examples/vscode/mcp.json into .vscode/mcp.json.

Gemini CLI

gemini extensions install https://github.com/BeakrHub/beakr-agent-plugins

This installs the beakr skill, the beakr MCP server and a short GEMINI.md context file. Gemini CLI does not pass your shell's environment variables to extensions, so sign in with beakr auth login rather than relying on BEAKR_API_KEY.

Claude.ai, Cowork, Claude Desktop and ChatGPT

Not live in production yet. Once it is, the hosted server's address is https://api.thebeakr.com/mcp.

Claude.ai, Cowork and ChatGPT run in the cloud, so they cannot start beakr mcp on your computer; they can only connect to a URL. Beakr's hosted MCP server offers the same tools at that URL. You connect it once and sign in with your Beakr account, through your organization's single sign-on when it has one, and approve the connection. Nothing to install, and no key to paste.

Claude.ai (and from there, Cowork):

Settings > Connectors > Add custom connector. On a Team or Enterprise plan, an owner may need to allow custom connectors first.
Name it Beakr and enter https://api.thebeakr.com/mcp as the server URL. Leave the advanced OAuth client ID and secret empty: Claude identifies itself to Beakr's sign-in on its own.
Connect, sign in to Beakr, and Allow.
In a chat, turn Beakr on from the tools menu. Connectors added on claude.ai are available in Cowork in the Claude desktop app.

ChatGPT:

Plugins > Add > Add custom MCP server.
Name it Beakr, enter https://api.thebeakr.com/mcp as the server URL, and choose OAuth authentication. Under advanced OAuth settings, pick the Client ID Metadata Document (CIMD) client setup and the scopes openid profile email offline_access if they are not filled in already.
Create it, sign in to Beakr, and allow the connection.

What the connector can do is what you can do in Beakr: it sees only your organizations and projects, writes go through Knowledge proposals, and actions such as creating keys or deleting projects stay in the Beakr app.

Until the hosted server is live, Claude Desktop can use the local server: add the beakr entry from examples/cursor/mcp.json to claude_desktop_config.json, with the full path from which beakr as the command.

One-click links and commands

Local server (beakr mcp; needs the beakr CLI installed and signed in):

Cursor: Add Beakr to Cursor (desktop deeplink: cursor://anysphere.cursor-deeplink/mcp/install?name=beakr&config=eyJjb21tYW5kIjoiYmVha3IiLCJhcmdzIjpbIm1jcCJdfQ%3D%3D)
VS Code: vscode:mcp/install?%7B%22name%22%3A%22beakr%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22beakr%22%2C%22args%22%3A%5B%22mcp%22%5D%7D or from a terminal: code --add-mcp '{"name":"beakr","type":"stdio","command":"beakr","args":["mcp"]}'
Codex: codex mcp add beakr -- beakr mcp
Claude Code: claude mcp add beakr -- beakr mcp

Hosted server (https://api.thebeakr.com/mcp, OAuth sign-in; not live yet: these will work once it ships):

Cursor: Add hosted Beakr to Cursor
VS Code: code --add-mcp '{"name":"beakr","type":"http","url":"https://api.thebeakr.com/mcp"}'
Codex: codex mcp add beakr --url https://api.thebeakr.com/mcp then codex mcp login beakr
Claude Code: claude mcp add --transport http beakr https://api.thebeakr.com/mcp, then /mcp to sign in
Gemini CLI: gemini mcp add --transport http beakr https://api.thebeakr.com/mcp

MCP server settings

Needs beakr-cli 0.4.0 or later (run the installer above to get it). Set these in the environment your agent starts from, or in the env of the beakr MCP entry:

Tool listing. The server lists every Beakr tool, because Claude Code calls only the tools a server lists. BEAKR_MCP_TOOLS=eager lists a smaller set plus discover_tools, which adds the tools it finds to the listing.
Write attribution. Every Knowledge write the server makes records the agent that made it: the client's own name and version (claude-code/2.1.283, codex-mcp-client/0.40.0), shown on proposals as "filed by Dana Reyes via claude-code/2.1". When several agents share one API key, give each MCP entry its own BEAKR_AGENT label ("env": {"BEAKR_AGENT": "reviewer"}); it overrides the client's name.
Self-hosted Beakr. On an installation that leaves out hosted features (integrations, skills, organization administration), the server does not list their tools (skills and org_audit_log, for example), and beakr doctor names the missing areas. When the CLI came with the installation, beakr_version says so and update_beakr does not run: the installation upgrades it.
Update checks. BEAKR_NO_UPDATE_CHECK=1 stops the CLI asking PyPI for a newer release; beakr_version and update_beakr then say update checks are off.

Local or hosted MCP server

The plugins ship the local server (beakr mcp over stdio). Beakr's hosted MCP server (streamable HTTP with OAuth, so no CLI needed) is not live in production yet. One switch moves every plugin over when it is:

In mcp-variant.json, set "remote_live": true (only once remote_url serves Beakr in production) and "variant": "remote".
Run tools/render_configs.py. It rewrites .mcp.json (Claude Code), mcp.json (Codex, Cursor, VS Code) and gemini-extension.json; the examples for both servers are always generated.
Bump the version (see Releasing) and commit.

The hooks keep needing the CLI either way; with the hosted server and no CLI they do nothing.

Troubleshooting

Symptom	Fix
The plugin runs a different `beakr` than the one you signed in with	`which -a beakr` lists every copy; the plugin runs the first. Set `BEAKR_BIN` to the full path of the one you want in the environment your agent starts from.
Beakr tools missing; the MCP server shows as failed (`/mcp` in Claude Code, `codex mcp list`)	The CLI is not installed or not on the agent's PATH. Install it (above). If it lives somewhere unusual, set `BEAKR_BIN` to its full path in the environment your agent starts from.
The server connects but tool calls fail with an auth error	Run `beakr auth login`, or check `BEAKR_API_KEY`. `beakr doctor` shows what the CLI can reach.
Cursor, VS Code or Claude Desktop launched from the Dock cannot find `beakr`	GUI apps may not inherit your shell's PATH. The plugins' launcher also checks `~/.local/bin`, `/opt/homebrew/bin` and `/usr/local/bin`; for hand-written configs, use the full path from `which beakr` as the command.
No Beakr context at session start	Check `beakr doctor`. The context comes from the project bound to the repository (`beakr init`), or your default project. On beakr-cli older than 0.4.0 (for example a PyPI install), the session starts with a note asking you to reinstall the CLI with the installer above.
Sessions are not captured	Capture is opt-in per repository: `beakr hooks capture status`, then `beakr hooks capture on`. Headless runs (`claude -p`) are captured but never teach personal learning.
A captured session is still compounding and should stop	`beakr conversations ls`, then `beakr conversations compound cancel ID`. Proposals it already filed stay; `beakr compound ID` resumes it.
`accept_proposal` is refused with `person_review_required`	The organization or project requires a person to accept what agents write. The user accepts it in Beakr; `beakr kb agent-review show -P <project>` says which policy is in force and where it comes from.
A `scope` is refused with `scope_not_found` or `scope_ambiguous`, or a `project` with `project_id must be a valid UUID`	No single project you can read has that name; a `scope` refusal names the closest. Pass the id `list_projects` prints: every Beakr server takes it. The local `beakr mcp` server also takes a name for any `project`; the hosted server takes a name on `documents` and `read_file`, but `research`, `wiki_stats` and `wiki_graph` there need the id.
Some files never reach Knowledge	`beakr projects status -P <project>` names the files that failed and `beakr projects retry -P <project>` resends them. `beakr projects refusals <project>` shows, by file, where models refused or fell back.
Only a few Beakr tools are listed	`BEAKR_MCP_TOOLS=eager` is set; unset it, or call `discover_tools`. On a self-hosted installation, `beakr doctor` lists the areas it does not provide.
`beakr doctor` says MCP "not registered" and hooks "not installed"	Expected: it checks only what `beakr setup` and `beakr hooks install` registered, not what a plugin provides.
Every Beakr tool, the skill or the `kb-*` commands appear twice	`beakr setup` (or the installer run without flags) registered them as well as the plugin. Keep the plugin and run `beakr setup --uninstall`, which removes setup's MCP server, skill, commands and hooks and keeps your sign-in.
Context appears twice	You installed the hooks with `beakr hooks install` as well. The plugin stands down when it sees them in `~/.claude/settings.json`; if you keep your settings elsewhere, run `beakr hooks uninstall`.
Windows	The launcher and hooks are POSIX shell scripts. On Windows, register the server by hand (`claude mcp add beakr -- beakr mcp`, `codex mcp add beakr -- beakr mcp`) and use `beakr hooks install` for hooks.

Repository layout

.claude-plugin/plugin.json        Claude Code plugin manifest
.claude-plugin/marketplace.json   Claude Code marketplace (also read by Codex and VS Code)
.agents/plugins/marketplace.json  Codex marketplace
.cursor-plugin/marketplace.json   Cursor marketplace
plugin.json                       Agent Plugins 1.0 manifest (Codex, Cursor, VS Code)
mcp.json, .mcp.json               MCP server config: Agent Plugins / Claude Code (generated)
gemini-extension.json, GEMINI.md  Gemini CLI extension (manifest generated)
skills/beakr/                     the Beakr skill, copied from beakr-cli (synced, do not edit)
commands/                         Claude Code slash commands (kb-* synced from beakr-cli)
hooks/claude-hooks.json           Claude Code session hooks
scripts/                          MCP launcher, hook runner, CLI finder
examples/                         hand-install configs for Codex, Cursor and VS Code
mcp-variant.json                  local or hosted MCP server switch
tools/                            sync, render, validate and smoke-test scripts
schemas/                          vendored JSON schemas used by CI

The repository root is the plugin root, because Gemini CLI installs only whole repositories.

Maintaining

The skill and the kb-* commands come from beakr-cli, which bundles the same skill into the CLI. Never edit them here.

tools/sync_from_beakr_cli.py --check       # are the copies identical to the pinned beakr-cli commit?
tools/sync_from_beakr_cli.py               # re-copy after changing tools/beakr-cli.ref
tools/render_configs.py --check            # are the generated MCP configs and links current?
uv run --with jsonschema tools/validate.py # manifests against their schemas, plus consistency checks
claude plugin validate . --strict          # Claude Code's own validator
tools/smoke_install.sh                     # install into Claude Code and Codex under a throwaway HOME

To take a newer skill: put the beakr-cli commit SHA in tools/beakr-cli.ref, run tools/sync_from_beakr_cli.py, review the diff and commit both together. CI runs all of the checks above except the smoke install.

Releasing

The version lives in plugin.json, .claude-plugin/plugin.json, the three marketplace files and (generated) gemini-extension.json; tools/validate.py fails if they disagree. Claude Code and Codex only offer users an update when the version changes, so bump it in every place for each release, run tools/render_configs.py, and tag the commit vX.Y.Z.

Publishing

This repository is public, and it is its own marketplace: every install command above reads it from GitHub, so a tagged release reaches users through their client's plugin manager.

Nothing is submitted to the public directories yet (the Claude Code plugin directory, OpenAI's Codex plugin directory, Cursor's marketplace and the Gemini CLI extensions gallery). Each has its own review.

License

Apache-2.0, like beakr-cli.