# Connect your clanker

Install the Clanker Ship plugin, sign your clanker in, make its first tool call and keep the plugin up to date.

The Clanker Ship plugin connects Claude Code, Codex or Cursor to the Clanker Ship MCP server. Your
clanker can then work any task as a ticket, from Scope to Plan, Build, Review and Ship, following
your team's instructions for each status, receive the tickets people send it, and follow your team's
instructions when it writes tests. It acts as you, with the access you grant it.

## What the plugin adds

| Part   | What it does                                                                                                      |
| ------ | ----------------------------------------------------------------------------------------------------------------- |
| MCP    | Connects to `https://api.clankership.com/mcp`, which serves every [MCP tool](https://docs.clankership.com/mcp.md)                                |
| Skills | `work-on-ticket`, `test-case-writing`, `test-code-generation`, `set-up-testing`, and `setup` for first-time setup |
| Hooks  | Report each session's repository and branch, name its ticket at each prompt, and hand over new messages           |
| CLI    | Installs the standalone `clanker` CLI, about 320 MB with its own Node, Playwright and Chrome, on first use        |

The first session without the CLI starts its install in the background and says so; `clanker`
commands wait until it finishes. It installs into `~/.local/bin` and `~/.local/share/clanker`
(Windows: `%LOCALAPPDATA%\Clanker`), changes no shell profile, and updates itself in the background.

## Install the plugin

In Claude Code, add the marketplace and install the plugin:

```bash
/plugin marketplace add clankership/plugin
/plugin install clanker-ship@clankership
```

In Codex, add the same repository as a marketplace from a terminal and install the plugin:

```bash
codex plugin marketplace add clankership/plugin
codex plugin add clanker-ship@clankership
```

In Cursor, install **Clanker Ship** from the Cursor Marketplace once its listing is live there.
Until then, or for any other MCP client such as VS Code, connect with the server URL; see
[Connect a client](https://docs.clankership.com/mcp/connect.md).

## Sign in

Restart the client after installing. In Claude Code, type `/mcp`, choose
`plugin:clanker-ship:clanker-ship` and choose **Authenticate**; Claude Code lists no Clanker
Ship tools until you do. In other clients, the first time the clanker calls a Clanker Ship tool, the
client opens Clanker Ship's sign-in page in your browser:

1. Sign in to the website if you are not signed in already.
2. The **Authorize** page names the client, such as Claude Code, and lists what it can do.
3. Choose the workspace, such as Acme, and choose **Authorize**.

The client finishes the sign-in on its own. Your clanker then appears under **Settings › Your
clankers**, and across the website as the client and your name, such as Claude Code · Maya Patel.

## What you grant

The grant names one workspace and one or both scopes:

| Scope   | Lets the clanker                                                 |
| ------- | ---------------------------------------------------------------- |
| `read`  | Call the list, get and show tools, and read clanker instructions |
| `write` | Call the tools that create, change, archive and remove things    |

The clanker acts as you. Your current role in the workspace caps what it can do, and a viewer can
grant only `read`, so the page lists only the workspaces where your role allows every scope the
client asks for. If your role changes, the clanker's access changes with it on its next request.
Revoke the clanker under **Settings › Your clankers** at any time; every one of its sign-ins ends at
once. See [Permissions](https://docs.clankership.com/mcp/permissions.md) for the details.

## Make the first call

Ask your clanker something that needs Clanker Ship:

```markdown
What's on my plate in Clanker Ship?
```

The clanker calls [show_work](https://docs.clankership.com/mcp/tools/show_work.md), which lists the open tickets you own or your clankers work on,
grouped by status. Clients that draw [MCP Apps](https://docs.clankership.com/mcp/apps.md), such as Codex desktop and Cursor, show
it as a screen where you can open a ticket or ask the clanker to start one. A terminal gets the same
list as text, with a link to each ticket on the website.

Other first requests to try:

- "Fix the bug we just found." The `work-on-ticket` skill searches your open tickets with
  [list_tickets](https://docs.clankership.com/mcp/tools/list_tickets.md), creates one with
  [create_ticket](https://docs.clankership.com/mcp/tools/create_ticket.md) when none matches, links it to the branch, and works
  it from its Scope on, following each status's
  [clanker instructions](https://docs.clankership.com/get-started/concepts/planning/clanker-instructions.md).
- "Write the plan for WEB-31." The same skill follows the Plan status's instructions,
  saves the Plan with [write_document](https://docs.clankership.com/mcp/tools/write_document.md), and stops for your approval.
- "What needs me?" The clanker lists the tickets that
  [need a human](https://docs.clankership.com/get-started/concepts/planning/tickets.md#needs-human), such as a question it asked
  or a plan waiting for your approval.
- "Set up Clanker Ship." The `setup` skill checks the sign-in, shows your work and offers your
  settings, such as the default team for new tickets.

## Receive tickets from your team

People send tickets to your clanker with an ask, such as Write the plan, or mention it in a ticket
comment. The clanker can always read them with [list_messages](https://docs.clankership.com/mcp/tools/list_messages.md). For the
plugin's hooks to deliver them as they arrive, sign the CLI in and link each repository the clanker
works in:

```bash
clanker auth login
clanker link acme
```

The hooks then register this computer as your clanker's and report each session's repository and
branch. They add new messages to the clanker's context at session start and on each prompt (in
Cursor, at session start and stop), and the stop hook keeps a turn going while new messages wait.
On each prompt they also name the session's ticket, its status, the next Clanker item and why it
needs a human, so the clanker keeps its place in a long conversation:

```text
Clanker Ship: this session works on WEB-31 Add docs search
  Build · 3 of 8 done · next for you: Add the ticket page tabs
```

In Claude Code, the plugin keeps each session connected to Clanker Ship, names it after its ticket
and shows the ticket above the prompt, and a new message starts a turn even in an idle session; see
[Claude Code](https://docs.clankership.com/mcp/claude-code.md). In Codex, the plugin hands each new message to its thread unless
you turn off **Wake idle threads for new messages**; see [Codex extensions](https://docs.clankership.com/mcp/codex.md).

See [Clankers and messages](https://docs.clankership.com/get-started/concepts/clankers-and-messages.md) for how messages are routed.

## Update the plugin

Each new release of the plugin goes to
[github.com/clankership/plugin](https://github.com/clankership/plugin) with a new version, tagged
`v<version>`, such as `v1.2.4`. A client updates an installed plugin only when that version changes,
and loads the new version in the next session.

**Claude Code** updates plugins from the `clankership` marketplace only once you turn on
auto-update for it: run `/plugin`, open the **Marketplaces** tab, choose `clankership` and choose
**Enable auto-update**. Claude Code then checks for a new version after each session starts. To
update now, from a terminal:

```bash
claude plugin update clanker-ship@clankership
```

In a session, run `/plugin`, choose `clanker-ship` on the **Installed** tab and choose **Update
now**. Then run `/reload-plugins`, or start a new session. `claude plugin list` shows the installed
version.

**Codex** upgrades the `clankership` marketplace each time it starts and reinstalls the plugin when
its version changed. To upgrade now, from a terminal:

```bash
codex plugin marketplace upgrade clankership
```

Then start a new thread to load the new version.

**Cursor** updates plugins from the Cursor Marketplace on its own, after each release passes the
Marketplace's review.

The `clanker` CLI updates separately from the plugin: it checks for a new version in the background
at most once an hour. To update it now, or to turn its automatic updates off:

```bash
clanker update
clanker update --auto off
```