Quickstart

The whole loop is one journey from the design spec (J1): on a machine with Claude Code and Codex, hub init --import finds their MCP servers, shows one review screen, and after hub connect both harnesses list one capabilities server. The target is under two minutes.

Before you start

• Node.js 22 or newer, and pnpm 11.
• A checkout of the repository. It becomes public at the local alpha.
• At least one agent: Claude Code, Codex, Cursor or Claude Desktop.

1. Build the CLI

These commands work today. They build the CLI and its dependencies from the checkout.

pnpm install
pnpm exec turbo build --filter=capabilities...
alias capabilities="node $PWD/packages/cli/dist/bin.js"

The alias is only a shortcut for this guide. The CLI is unreleased, so there is no global install.

2. Create the hub and import

capabilities hub init --import

This creates ~/.capabilities/hub/ (directory mode 700, files 600) and runs the importer. The importer reads the configs of the harnesses you use (Claude Code, Codex, Cursor, Antigravity CLI, Hermes and pi), collects their MCP servers, and merges duplicates. It proposes a namespace for each server, such as github or linear.

If a harness keeps a credential in plain text, the importer offers to copy it into your OS keychain for the hub. It leaves the harness config as it was, because a harness cannot read a keychain reference. In M1 the importer counts the skills it finds and says a later release imports them.

3. Review what the hub may do

The review screen groups every new tool in three classes:

One keystroke accepts the proposal, or you adjust it. Accepting pins each tool's contract, so if a tool changes upstream it asks again. A local stdio server also asks for consent to run its exact command.

4. Connect your agents

capabilities hub connect

connect writes one MCP entry named capabilities into Claude Code, Codex, Cursor and Claude Desktop. The entry runs capabilities hub serve --stdio --profile default by the CLI's absolute path, checked before it is written. For Antigravity, Hermes and pi, which the hub reads but does not write, it prints exact instructions instead.

With --replace, connect also turns off the direct entries it imported, after taking a snapshot, and capabilities rollback restores them byte for byte. Entries your stack lock manages stay where they are, and connect prints the capabilities stack uninstall command for each. To write the entry yourself, use the setup snippets.

5. Ask for something that writes

In Claude Code, try journey J2 from the spec:

Summarize my open bugs and post the top 3 to #eng.

The model searches, reads the two tools it needs, and runs one execute across both sources. The post is a write, so the run pauses and the hub asks you:

• If your client supports MCP 2026-07-28 input requests with forms, it asks you itself.
• Otherwise the hub opens an approval page in your browser, and the model is told only that a page opened.
• From any terminal, you can always decide with the CLI:

capabilities hub approve <runId>

You get four choices: Allow once, Allow for this run, Always allow (pinned to the tool's current contract), and Deny. Then the run resumes from its journal, and nothing that already ran runs twice.

6. Check health

capabilities hub doctor

doctor reports each source's health and the tail of its error output, the store's schema version, the keychain status and the permissions on the HTTP token file.

Add a source by hand

capabilities hub add https://mcp.example.com/mcp
capabilities hub auth example

add takes a URL or a command line for a local stdio server, fetches the tool list, and opens the same review screen. auth takes a credential at a masked prompt, never as an argument. OpenAPI documents, such as capabilities hub add https://api.example.com/openapi.json, arrive in M2.

What's next

• Concepts explains sources, connections, policies, runs and journals.
• The CLI lists every capabilities hub command and its milestone.
• Security and approvals covers the four choices and who may make them.