Plugin

Preview. The plugin is in preview and may change.

The plugin gives Claude Code two things: a start-up hook that connects every session to your project and offers its kits, and the seven skills that teach the agent to work with Coelevate. It is stage-only: it proposes changes and a person publishes them in the Workspace.

Prerequisites

• Claude Code.
• A GitHub account that can read the plugin and command-line repositories, signed in on your machine (gh auth login, then gh auth setup-git).
• The command-line client on your PATH, from the command line page. The skills call coelevate-context by that name.
• A project API key, in a .env file in the folder you start Claude Code from. See Credentials and scopes.

Install

export CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1
claude plugin marketplace add GravityBreak-AI/coelevate-plugins --scope project
claude plugin install coelevate@coelevate-plugins --scope project

Claude Code tries SSH first when it fetches a GitHub marketplace. If your SSH key does not reach the repository, the first command fails; the environment variable makes it use HTTPS and your GitHub sign-in instead.

--scope project records the plugin in the folder's .claude/settings.json, which you can commit so the rest of your team is offered the same plugin. Without a scope the plugin is installed for you alone, in every folder. Claude Code keeps its cached copy of the plugin repository under ~/.claude/plugins whichever scope you choose.

Check it with claude plugin list: the plugin coelevate@coelevate-plugins should show as enabled. Then run coelevate-context doctor in the folder to check the connection.

What the start-up hook does

Each time a session starts (new, resumed, cleared or compacted), the hook:

1. Reads the COELEVATE_* variables from the .env in the session folder. A variable already set in your environment wins, no other variable is read from the file, and a value is never printed.
2. Looks for .coelevate.json in the folder or any parent, and asks the client which project your key reaches.
3. Gives the agent, not only you, a status line (API host, project, label, and whether the binding matches the key), the session id, and a list of the project's kits with their titles and descriptions. The list is capped at 10,000 characters, with a count of what did not fit.
4. Points the agent at the start-session skill.

If the binding and the key disagree, no kits are listed and the agent is told to stop. If nothing is configured, the agent is told Coelevate is installed but not set up, so it can offer to help; it is told not to ask you to paste a secret into the chat. The hook never blocks a session and never prints client output or credentials.

Everything the hook hands over is labelled as data from your project. It cannot override your instructions.

Bind a folder to a project

Ask the agent: "Bind this folder to my Coelevate project." The bind-project skill writes .coelevate.json:

{"project": "<project id>", "label": "<name>"}

and adds one line to CLAUDE.md that tells later sessions to run start-session. The label defaults to the folder name. The file binds the project only; which kit a session needs depends on your request, so the agent picks it each time. The key decides which project is reached, and a mismatch is refused (see Credentials and scopes).

First run

1. Start Claude Code in the bound folder. The agent states the project it is connected to in one line and carries on, because the binding matches the key. With no binding it asks you to confirm.
2. Ask for something your project knows about. The agent chooses the kit that fits, inspects its skills, rules and memories, asks for a second confirmation if anything looks risky, then loads it and answers from it.
3. To put your own documents in, ask the agent to onboard them. See Getting started.

Update

Run claude plugin update coelevate@coelevate-plugins and restart Claude Code to apply it. Check the installed version with claude plugin list.

Troubleshooting