---
title: Threads
description: start_thread, message_thread, read_thread and close_thread, how a chat sends work to its threads.
tools: [start_thread, message_thread, read_thread, close_thread]
source: [packages/agents/src/tools/threads.ts, packages/agents/src/threads.ts]
generated: true
---

> Roadstar docs for agents. Every page, as markdown: https://docs.roadstar.app/llms.txt

A chat's tools for its threads. Threads can't start threads.

What they return:

- `start_thread`: `{ "started": "Juniper Dental", "kind": "fresh" }`. The thread starts at once; its answer comes back to the chat as a message.
- `message_thread`: `{ "sent": "Juniper Dental" }`.
- `read_thread`: `{ "thread": "Juniper Dental", "memory": "…" }`, the thread's memory from the top, or with `id` one line or message of it.
- `close_thread`: `{ "closed": "Juniper Dental" }`.

See [chats and threads](/how-it-works/chats-and-threads/).

## Where each is offered

| Tool | Roadstar's chat | An agent's chat | A thread | A Mac or outside app |
| --- | --- | --- | --- | --- |
| [start_thread](#start_thread) | Yes | Yes | — | — |
| [message_thread](#message_thread) | Yes | Yes | — | — |
| [read_thread](#read_thread) | Yes | Yes | — | — |
| [close_thread](#close_thread) | Yes | Yes | — | — |

## start_thread

What the agent reads, word for word:

> Start a thread for work no thread holds: one per client, project or job. Fresh starts empty with the packet; fork starts from this chat's memory. Its answer comes back on its own.

| Input | Type | Required | What it is | Limits |
| --- | --- | --- | --- | --- |
| `title` | text | yes | What it's about, in a few words: Juniper Dental |  |
| `kind` | one of `fresh`, `fork` | no | fresh unless the work needs this conversation |  |
| `task` | text | yes | What to do, in a sentence or two |  |
| `notes` | text | no | Facts it needs that no link holds: names, dates, choices |  |
| `links` | list of text | no | What to read, as mail:, file:, contact:, doc: or web: with the id or address a tool gave you |  |
| `andThen` | text | no | When you start several threads and write one answer from all of them: what to do once the last answers |  |

## message_thread

What the agent reads, word for word:

> Send a thread more work or a correction. A running thread takes it at its next step; an idle or stopped one starts on it, with all it did before.

| Input | Type | Required | What it is | Limits |
| --- | --- | --- | --- | --- |
| `thread` | text | yes | The thread, by title |  |
| `task` | text | yes | What to do, in a sentence or two |  |
| `notes` | text | no | Facts it needs that no link holds: names, dates, choices |  |
| `links` | list of text | no | What to read, as mail:, file:, contact:, doc: or web: with the id or address a tool gave you |  |

## read_thread

What the agent reads, word for word:

> Read what a thread did: its memory from the top, or with id a line or message of it, down to the exact words.

| Input | Type | Required | What it is | Limits |
| --- | --- | --- | --- | --- |
| `thread` | text | yes | The thread, by title |  |
| `id` | whole number | no | A line's or message's id | 0 or more |
| `n` | whole number | no | The line's n; 1 for a message | 1 or more |
| `page` | whole number | no | Where in a long message | 0 or more |

## close_thread

What the agent reads, word for word:

> Close a thread whose work is over: a finished project or a one-off job. It stays readable, and a message reopens it.

| Input | Type | Required | What it is | Limits |
| --- | --- | --- | --- | --- |
| `thread` | text | yes | The thread, by title |  |