Skip to content
Docket

Quickstart

This takes you from nothing to your coding agent finishing its first card. You need a GitHub account, Node.js 18 or later, git, and one of Claude Code, Cursor or Codex.

Sign in

Section titled “Sign in”

Go to app.usedocket.dev and press Continue with GitHub. Docket asks GitHub for read:user only: your public profile. It never asks for access to a repository. See What GitHub is asked for.

Copy your key

Section titled “Copy your key”

The first time you sign in, you land on Connect an agent, and your first API key is made there. It starts with dk_.

The key is shown once. Docket keeps only a hash of it, so it cannot show you the key again: copy it before you leave the page. The page has already put it in the command for your client, below the key. If you lose it, make a new one on the keys page.

Add Docket to your agent

Section titled “Add Docket to your agent”

Your client runs Docket’s adapter, @usedocket/mcp, on your machine with npx; the first start downloads it. The key goes in your client’s settings. Below, put your key where it says dk_your_key. These are the commands the app gives you, so you can copy them from either place.

Claude Code

Section titled “Claude Code”

Run this in a terminal. Then run /mcp in Claude Code, or restart it.

Terminal window
claude mcp add docket --scope user -e DOCKET_API_KEY=dk_your_key -- npx -y @usedocket/mcp@latest

--scope user adds Docket to Claude Code everywhere, not only in the directory you run the command in.

Cursor

Section titled “Cursor”

Put this in ~/.cursor/mcp.json (make the file if it is not there), then restart Cursor. If the file already has an mcpServers block, add the docket entry to it.

{
  "mcpServers": {
    "docket": {
      "command": "npx",
      "args": [
        "-y",
        "@usedocket/mcp@latest"
      ],
      "env": {
        "DOCKET_API_KEY": "dk_your_key"
      }
    }
  }
}

Codex

Section titled “Codex”

Run this in a terminal, then start Codex again.

Terminal window
codex mcp add docket --env DOCKET_API_KEY=dk_your_key -- npx -y @usedocket/mcp@latest

Start it in your repository

Section titled “Start it in your repository”

The adapter reads git from the directory your client starts it in, and that decides which board you get. Start your agent in a repository that has a remote, such as one on GitHub. Docket makes a project for it on the first call, named after the repository: one called hello-docket gets the key HEL, and its cards are HEL-1, HEL-2 and so on.

In a directory with no remote, Docket still works, but the cards go to a project called Default, and the board can never see their work merged. See Outside a git repository.

A new project has no git rules: your agent can work on the branch it is on and finish a card without pushing. See Git rules.

Give it its first card

Section titled “Give it its first card”

Ask your agent:

“Create a Docket card called Hello, then list my cards.”

It calls create_card, then list_cards, and is told:

Created HEL-1 — Hello.
HEL-1  todo       Hello

The Connect an agent page notices by itself and says Connected, naming the project. There is nothing to reload.

Then ask it to do the card:

“Claim the next Docket card and finish it.”

It calls claim_next and is handed the card’s brief. A card that is only a title has a short one: the title, the branch and commit the work starts from, and a claim number, which the agent passes back when it finishes.

# HEL-1 — Hello


---
claim 3 · branch main · base ab59486 · lease until 09:11Z


Pass claim_id 3 to finish_card or release_card. The lease extends automatically while you leave notes.

It does the work, then calls finish_card and is told HEL-1 is done.

What success looks like

Section titled “What success looks like”

On the board, your repository is under Projects, and the card is under Recently finished.

Ask the agent to list your cards again and it will say:

HEL-1  done       Hello  — merge not seen

Done is not merged. A finished card is a proposal, and the board counts it merged once a commit carrying Card-Id: HEL-1 is on your remote’s main branch, as your checkout last saw it: after you push main, or pull once its pull request is merged. The agent is asked to put that line in its commits. A card whose work changed nothing has no such commit, and keeps “merge not seen”. See Why done is not merged.

Next

Section titled “Next”