Getting started

Preview. The tools this path installs are in preview and may change.

This page takes you from nothing to one visible result: a coding agent that opens every session already holding your project's kit. The agent's own part, turning a handful of documents into staged changes, took a few minutes in our test; the rest is your review.

One rule shapes every step: the agent proposes, you publish. The agent can read your project's context, stage changes to it, and write kits from assets you have already published. It cannot publish. Nothing it proposes goes live until a person reviews it and merges it in the Workspace.

What you will have at the end

• A project with a first published release of your own context.
• A kit that holds it.
• A coding agent that, in a second session, starts with that kit already loaded.

Before you start

• Access to a Coelevate project. You need to be a member of an organization on Coelevate; any member can create a project in it.
• A coding agent that can run shell commands. These steps use Claude Code. Any other agent that can run commands can use the command line directly.
• uv and git on your machine, and a GitHub account that can read the plugin and command-line repositories.
• A few source documents of your own to onboard: a handbook, a policy, an FAQ.

1. Find or create your project

Sign in to the Workspace and open your project. If your organization has none yet, create one with New project on the organization's page: a name, a short handle, and an optional description.

The Workspace Home page has its own Getting Started panel that tours the Workspace side. This page does not repeat it.

2. Create a project key

The agent talks to your project with an API key. In the Workspace, open the project's settings, go to the API keys tab and choose Create API key.

1. Give it a name that says who uses it, for example claude-code-laptop.
2. Tick the permissions context:read, context:assets and context:kits. These let the agent read, stage changes, and write kits. Leave context:review and context:gaps unticked: context:review is what approves and merges, and that stays with a person.
3. Choose an expiry. A dated expiry is safer than none.
4. The next screen shows the credentials once: a client id, a client secret, a token address and an API address, with a ready-made .env block. Copy the block now. You cannot see the secret again.

Treat the secret like a password. Keep it in a .env file that is not committed, and never paste it into a chat with the agent. See Credentials and scopes.

3. Install the client and the plugin

Create a folder for the work, or use an existing repository, and put the .env block from step 2 in a file named .env in it. Add .env to your .gitignore.

Install the command-line client the plugin's skills call:

uv tool install --from "git+https://github.com/GravityBreak-AI/coelevate-cli" coelevate-context-cli
coelevate-context --version

Then add the plugin to Claude Code, for this project:

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

The first line makes Claude Code fetch the plugin over HTTPS. Without it, Claude Code tries SSH first and fails if your SSH key does not reach the repository. Both repositories are fetched with your own GitHub credentials; if a command is refused, run gh auth login and then gh auth setup-git.

Check the setup:

coelevate-context doctor

doctor checks the configuration, the token, the scopes and one read, and says which step fails. When everything is right, each check reports ok. Until your .env is in place it reports the missing variables and exits with code 2.

4. Start a session and bind the folder

Start Claude Code in the folder. The plugin's start-up hook tells the agent that Coelevate is available and which project your key reaches, and the agent runs its start-session skill. The folder is not bound yet, so ask the agent to bind it:

Bind this folder to my Coelevate project.

The agent writes a small .coelevate.json (the project id and a label) and one line in CLAUDE.md that points future sessions at the same project. It binds the project only; the kit is chosen in each session from what you ask for. Commit both files if the repository is shared.

5. Onboard your first documents

Put a few source documents in the folder and ask:

Onboard these documents into Coelevate.

The agent uses the onboard-context skill. It cuts each document into small topical pages, names the people, products and terms they mention as entities, links them, and stages all of it with the sources recorded. It then tells you what it staged and where to review it. For a handful of documents this takes a few minutes. A longer run is normal for a larger set.

Nothing is live yet. The release number of your project has not moved.

6. Review and publish in the Workspace

This is the step only you can do. Open the review link the agent printed, or go to Context then Changes in the Workspace. You will see one change request holding everything staged. Read the pages, check them against your documents, approve what is right and reject what is not, then choose Merge change request. Merging publishes the approved items as a new release.

Ask the agent what is waiting if you want a summary first: the review-staged-changes skill describes the open change request per kit and hands the decision back to you.

7. Create the first kit

A kit can only hold assets that are already published, so this comes after step 6. Ask:

Create a kit from the pages we just published.

The agent writes the kit (it needs the context:kits permission from step 2). Open Context then Kits in the Workspace to see it. Its description should name the situations it serves, in the words a first request would use, because a session picks its kit by matching your request against those descriptions.

8. Start a second session and see the kit arrive

Close the session and start a new one in the same folder. This time the start-up hook lists the project's kits to the agent before you type anything. Ask a question your documents answer. The agent states the project it is connected to, picks the kit that fits, reads it, and answers from it, citing the pages.

If that is what you see, you are done: your agent starts every session with your project's context.

If the kit does not arrive

• The agent does not mention Coelevate. Run coelevate-context doctor in the folder. A missing .env, a wrong address or a key without context:read is named there.
• The agent says the key is read-only or cannot stage. The key lacks context:assets. Create a new key with the right permissions.
• The agent stops and reports a project mismatch. .coelevate.json names a different project than your key reaches. Use the right key, or rebind the folder.
• No kit is offered. Nothing is published yet, or no kit was created. Repeat steps 6 and 7.
• The first call after a quiet spell is slow. The service starts on demand. The client retries reads once; running the command again is safe.

Where to go next

• Connect your agent: the other ways in, and what each door can do.
• Credentials and scopes: permissions, expiry, and how a key decides the project.
• Keep your kits right after a release: what to do to your kits after every later release.
• A2A Reference: run a deployed Coelevate agent from your own code.
• Glossary: the words this documentation uses.