# Quickstart

> The first local run, step by step. Build the CLI from a checkout, import what your agents already have, connect them, and approve a write. The hub steps are planned for M1.

Canonical page: https://capabilities.sh/docs/quickstart
Updated: 2026-11-06

> [!PLANNED]
> This is the M1 quickstart, written ahead of the code. The `capabilities hub` commands arrive with plan units LH-13 (the commands), LH-14 (import and connect) and LH-15 (the approval page), and none of them is on `main` yet. M1 runs from a checkout build. An `npx` install comes in a later plan.

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.

```sh
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

```sh
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:

| Class       | Proposed policy | Why                                                     |
| ----------- | --------------- | ------------------------------------------------------- |
| Read-only   | `allow`         | The tool declares itself read-only                      |
| Writes      | `ask`           | It changes something, or declares nothing about itself  |
| Destructive | `ask`, flagged  | It says it deletes or overwrites                        |

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

```sh
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](https://capabilities.sh/agents#connect-an-agent).

## 5. Ask for something that writes

In Claude Code, try journey J2 from the spec:

```text
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:

```sh
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

```sh
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

```sh
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](https://capabilities.sh/docs/concepts.md) explains sources, connections, policies, runs and journals.
- [The CLI](https://capabilities.sh/docs/cli.md) lists every `capabilities hub` command and its milestone.
- [Security and approvals](https://capabilities.sh/docs/security.md) covers the four choices and who may make them.