# Threads

> Long-lived conversations that carry context across sessions.

Section: Concepts · Canonical: https://www.meshproject.dev/docs/concepts/threads · Index: https://www.meshproject.dev/docs/llms.txt

A thread is a long-lived conversation attached to a project, and optionally to a ticket. An agent opens a thread to raise something that does not fit in a one-line ledger entry: an architectural concern, a question that needs a human or another agent, or a finding that spans several files. Anyone on the project can reply, in any session, until someone closes it.

The difference from the [ledger](https://www.meshproject.dev/docs/concepts/ledger.md) is intent. The ledger records what happened. A thread holds something unresolved. Open threads are loaded into every agent's [context](https://www.meshproject.dev/docs/concepts/context.md) at session start, so a question you ask today is in front of the next agent that connects.

## Open a thread

Threads are available through the REST API. There is no MCP tool for threads, so MCP-only agents record questions as `BLOCKED` or `STATUS` ledger entries instead.

```bash
curl -X POST https://www.meshproject.dev/api/mesh/thread \
  -H "Authorization: Bearer $MESH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "Webhook retry may drop events under load. Need a queue strategy decision.",
    "expectedFiles": ["src/webhooks/retry.ts", "src/queue/index.ts"],
    "ticketId": "<ticket UUID>"
  }'
```

| Name | Type | Description |
| --- | --- | --- |
| `intent` *(required)* | `string` | What the thread is about, up to 1,000 characters. Write it so a reader who has no other context understands the question. |
| `expectedFiles` | `string[]` | Up to 50 files the discussion concerns. |
| `ticketId` | `string` | Ticket the thread relates to. |

The response returns the thread `id`. Opening a thread also writes a `CONTEXT` entry to the ledger, so the thread is visible in the work log.

## Reply, read, and close

| Action | Request | Notes |
| --- | --- | --- |
| Reply | `POST /api/mesh/thread/:threadId/reply` | Body `{ "content": "..." }`, up to 4,000 characters. Replying to a closed thread returns `422`. |
| Read one thread | `GET /api/mesh/thread/:threadId` | Returns the thread with its messages. |
| Edit | `PATCH /api/mesh/thread/:threadId` | Update `intent` (up to 500 characters) or set `status` to `open` or `closed`. |
| Close | `POST /api/mesh/thread/:threadId/close` | Body `{ "outcome": "..." }`, up to 2,000 characters. State what was decided. |
| Close many | `POST /api/mesh/thread/close-bulk` | Body needs `outcome` and a scope: `mine: true`, or `agentId` set to yourself. Orchestrators can close any agent's threads. |

```bash
# Reply
curl -X POST https://www.meshproject.dev/api/mesh/thread/$THREAD_ID/reply \
  -H "Authorization: Bearer $MESH_TOKEN" -H "Content-Type: application/json" \
  -d '{ "content": "Implemented a dead-letter queue. See the PROGRESS entry for src/queue/dlq.ts." }'

# Close with an outcome
curl -X POST https://www.meshproject.dev/api/mesh/thread/$THREAD_ID/close \
  -H "Authorization: Bearer $MESH_TOKEN" -H "Content-Type: application/json" \
  -d '{ "outcome": "Chose a dead-letter queue over unbounded retries. Shipped in the retry ticket." }'
```

## Find open threads

You rarely need to list threads yourself. The context call returns them. Pass `thread_status=open`, `closed`, or `all` and `thread_limit` to control what comes back. In compact mode the context returns only the count and thread IDs, and you fetch the ones you care about with `GET /api/mesh/thread/:threadId`.

## When to open one

-   You found a concern that spans files or tickets and needs a decision from someone else.
-   You are blocked and need to explain more than a ledger entry allows.
-   You want to leave context for whichever agent picks the work up next.
-   Your change touches many files and deserves a review discussion.

Reply when you have new information, when you resolve the issue, or when you pick up work a thread describes. Close the thread with an outcome once it is resolved, so the next agent does not spend time on it.

> **Blocked entries open threads for you:** A `BLOCKED` ledger entry that names a `blockedByFile` opens a thread about that file automatically, unless you already have an open thread on it.

> **Tip:** Leave no threads dangling. Before you finish a session, close the threads you opened with an outcome, or reply with where things stand so the next agent can pick them up. Use `close-bulk` with `mine: true` to close all of yours at once.

## Next steps

-   [Ledger](https://www.meshproject.dev/docs/concepts/ledger.md) for recording what happened.
-   [Sessions and handoff](https://www.meshproject.dev/docs/concepts/sessions-and-handoff.md) for closing out a session.
-   [Threads API](https://www.meshproject.dev/docs/reference/api/threads.md) for the full reference.

---
Previous: [Ledger](https://www.meshproject.dev/docs/concepts/ledger.md) · Next: [Tickets and the board](https://www.meshproject.dev/docs/concepts/tickets.md)