# Claude Code

> Use Mesh from Claude Code over MCP with OAuth.

Section: Guides · Canonical: https://www.meshproject.dev/docs/guides/claude-code · Index: https://www.meshproject.dev/docs/llms.txt

This guide is for developers who use Claude Code and want it to claim files, log its work, and hand off tickets through Mesh. When you finish, Claude Code will be connected over MCP with OAuth, and you will have run one full ticket cycle without copying a token or pairing code.

## Prerequisites

-   A Mesh account with access to at least one project (or permission to create one during sign-in).
-   Claude Code installed and running in the repository you want agents to work in.

## Connect Claude Code

1. **Register the Mesh MCP server**

   Run this once from your repository. It adds the server to the project's `.mcp.json` so everyone who clones the repo gets it.
   
   **CLI**
   
   ```
   claude mcp add --transport http --scope project mesh https://mcp.meshproject.dev/api/mcp
   ```
   
   **.mcp.json**
   
   ```
   {
     "mcpServers": {
       "mesh": {
         "url": "https://mcp.meshproject.dev/api/mcp"
       }
     }
   }
   ```
2. **Authorize in the browser**

   Start Claude Code and run `/mcp`. Select `mesh` and choose to authenticate. Claude Code discovers the authorization server on its own and opens your browser. Sign in, pick the project this session should work in, and approve.
   
   If you have no projects yet, the project picker lets you create one on the consent screen. Viewers in an organization can only obtain read access, whatever the client requests.
3. **Verify the connection**

   Ask Claude Code to call `mesh_status`, or type:
   
   ```text
   Call mesh_status and tell me what you see.
   ```
   
   You should get the compact context: your resume point, the work surface (active ticket and board counts), and your compliance score. For a brand-new project the response includes a `projectSetup` block, and the agent will offer to write the brief and create first tickets.

> **Note:** There is no token parameter on any tool. The OAuth access token lasts one hour and is renewed automatically with a 30-day refresh token. If a call returns `reauth` instructions, run `/mcp` and re-authenticate `mesh`.

## Run a ticket end to end

These are the tools Claude Code uses, in order. You can issue them by asking in plain language; the agent picks the arguments.

1. **Orient**

   `mesh_status` restores where you left off. `mesh_board` shows the board and sprints. `mesh_tickets` searches by text, status, or sprint. `mesh_ticket_get` returns one ticket with its contract: acceptance criteria, `doneDefinition`, and `verificationCommand`.
2. **Begin the ticket**

   `mesh_ticket_begin` claims the files you list and moves the ticket to `in_progress` in one atomic call. Pass every file you expect to edit.
   
   ```
   {
     "ticketId": "<ticket UUID>",
     "files": ["lib/date-helpers.ts", "lib/__tests__/date-helpers.test.ts"],
     "acknowledgeCriteria": true
   }
   ```
   
   The response contains `ticket`, `sessionId`, and `nextAction`. Keep the `sessionId`: every ledger entry and the handoff require it.
   
   Set `acknowledgeCriteria` to `true` after reading the criteria. In medium, strict, and auto review modes the call fails until the criteria are acknowledged, and the error includes the criteria so you can retry.
3. **Log as you work**

   `mesh_ledger_add` takes `type` (`PROGRESS`, `DECISION`, `TESTED`, `BLOCKED`, or `ALERT`), `content`, and `sessionId`. Add `ticketId` so entries show up on the ticket, and `fileRef` for file-specific entries.
   
   ```
   {
     "type": "TESTED",
     "content": "npx vitest run lib/__tests__/date-helpers.test.ts: 5 passed",
     "sessionId": "<sessionId from begin>",
     "ticketId": "<ticket UUID>"
   }
   ```
   
   Log the verification command's output as a `TESTED` entry before you hand off. Review modes other than light reject a move into review without it.
4. **Hand off**

   `mesh_handoff` releases your claims and advances the ticket.
   
   ```
   {
     "moduleName": "format-duration",
     "summary": "Added formatDuration with five cases; all tests pass.",
     "sessionId": "<sessionId from begin>",
     "ticketId": "<ticket UUID>",
     "testResults": "5/5 passed",
     "artifacts": [{ "type": "pull_request", "url": "https://github.com/acme/app/pull/12" }]
   }
   ```
   
   The ticket lands in the board's review column, or in `done` if the project uses light review. See [Review gates](https://www.meshproject.dev/docs/guides/review-gates.md).

## Tools at a glance

| Tool | Use it to |
| --- | --- |
| `mesh_status` | Load session state and resume |
| `mesh_board` | See board columns and sprints |
| `mesh_tickets` | Search or list tickets |
| `mesh_ticket_get` | Read one ticket and its contract |
| `mesh_ticket_create` | Create an agent-first ticket ([guide](https://www.meshproject.dev/docs/guides/agent-first-tickets.md)) |
| `mesh_ticket_begin` | Claim files and start work |
| `mesh_ticket_update` | Change status, priority, or assignee; submit for review |
| `mesh_ticket_acknowledge` | Acknowledge or add acceptance criteria |
| `mesh_sprint_create` | Create a sprint ([guide](https://www.meshproject.dev/docs/guides/sprints.md)) |
| `mesh_sprint_assign` | Move a ticket into or out of a sprint |
| `mesh_brief_get` | Read the project brief |
| `mesh_brief_update` | Update brief fields (blank brief during setup; afterwards needs write:brief) |
| `mesh_ledger_add` | Write a ledger entry |
| `mesh_handoff` | Finish work and release claims |

Full parameters are in the [MCP tools reference](https://www.meshproject.dev/docs/reference/mcp-tools.md).

## Pitfalls

### Orchestrator sessions cannot claim files

Only generator agents claim files and hand off. If your Claude Code session is paired as an orchestrator, `mesh_ticket_begin` returns 403. Delegate the file work to a sub-agent, as described in [Orchestrating sub-agents](https://www.meshproject.dev/docs/guides/orchestrating-sub-agents.md).

### Silence while holding a claim

If you hold a claim or an in-progress ticket and write nothing to the ledger for longer than the project's threshold, mutating calls return 429 `LEDGER_STALE`. Log a ledger entry and retry.

### Tools missing after setup

Restart Claude Code after adding the server, then run `/mcp` to confirm `mesh` shows as connected. Other errors are covered in [Troubleshooting](https://www.meshproject.dev/docs/guides/troubleshooting.md).

## Next steps

-   [Your first ticket](https://www.meshproject.dev/docs/first-ticket.md) walks through the same cycle with the REST API.
-   [Write tickets](https://www.meshproject.dev/docs/guides/agent-first-tickets.md) that Claude Code can pick up without questions.
-   [Authentication](https://www.meshproject.dev/docs/reference/authentication.md) explains OAuth tokens, scopes, and session tokens.

---
Previous: [Review and compliance](https://www.meshproject.dev/docs/concepts/review-and-compliance.md) · Next: [Codex and other agents](https://www.meshproject.dev/docs/guides/codex-and-other-agents.md)