> ## Documentation Index
> Fetch the complete documentation index at: https://docs.capy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Working in threads

> How messages reach the agent, what thread statuses mean, and how to use todos, voice input, and the command menu day to day.

A thread is a durable conversation with one Capy agent, stored on Capy's servers: close the laptop mid-run and the agent keeps working, and the thread wakes on its own when CI finishes, a review lands, or a PR merges. Use one thread per piece of work, and message it the way you'd message a colleague; it holds the full history of the conversation, the machines, the tasks, and the PRs that came out of it.

## Sending messages

Every message you send carries a delivery mode that decides how it reaches a busy agent:

| Mode                    | What happens                                                                        |
| ----------------------- | ----------------------------------------------------------------------------------- |
| **Interrupt** (default) | Stops the agent's current generation; your message becomes the next thing it reads. |
| **Queue**               | Waits until the current work finishes, then delivers.                               |
| **Steer**               | Injects into the current work at the agent's next step, without stopping anything.  |

Enter sends as interrupt by default and Cmd+Enter sends as queue; both gestures are configurable in Settings → General under Input, and each gesture has one stable meaning; no modifier ever flips its behavior. When the thread is at rest there's nothing to interrupt or queue behind, so every send just delivers immediately.

Interrupt is the right default: if you saw the agent going the wrong way, waiting politely wastes the run. Queue follow-up work you don't want colliding with the current job; steer mid-course corrections that shouldn't throw away in-flight progress.

## The queued-message tray

A queued or steered message the agent hasn't read yet sits in a tray above the composer. The transcript only shows messages the agent has actually seen, so it never lies about what the model knows. Each tray row has two hover actions:

* **Send now** converts the waiting message into an immediate interrupt.
* **Remove** dequeues it; the agent never sees it.

When the agent starts reading a queued message, it moves from the tray into the transcript at the position the model read it. If you hit Remove just as the agent picked the message up, the removal comes back "too late" and the message lands in the transcript, which is the expected outcome.

## Thread statuses

A thread's status is derived from what the agent and its tasks are doing, in this precedence: active beats error, error beats needs-attention, and so on down to idle. The sidebar and threads page fold statuses into five buckets:

| Bucket               | Meaning                                                                            |
| -------------------- | ---------------------------------------------------------------------------------- |
| **Needs attention**  | The agent is blocked on your decision, access, or credentials, or it hit an error. |
| **Ready for review** | The agent finished work and handed it to you for review.                           |
| **Active**           | The agent or any of its tasks is working right now.                                |
| **Waiting**          | An external event owns the next move: CI, a callback, a long-running operation.    |
| **Idle**             | At rest. Nothing happens until someone messages it.                                |

Skim the needs-attention and ready-for-review buckets first; those are the threads waiting on you. Active and waiting threads don't need you yet.

## Marking status by hand

You can move a resting thread between buckets yourself: the Status submenu in any thread's context menu offers **Ready for review**, **Needs attention**, and **Idle**. Marks are the human's word until someone speaks again: your next message or the agent's next turn-ending reply overwrites them, and you can't mark a thread that's actively working.

One transition is automatic: a thread sitting in ready-for-review settles to idle on its own when a merge lands and no PR anywhere in its task tree remains open. Reviewed, merged, done: you never have to come back just to tidy the bucket. A PR closed without merging never triggers the move to idle on its own (that's a rejection signal, and the thread stays in review until you act), but an abandoned side-PR doesn't hold a finished thread out of idle when the real work merges.

## Archive is dormant

Archiving removes a thread from your lists and puts it fully to sleep: no CI result, task completion, or reminder wakes it. Events that arrive meanwhile still land as pending context (nothing is lost), but nothing runs.

One thing revives it: a human message. Sending to an archived thread unarchives it and wakes the agent with everything that accumulated while it slept. The Unarchive button only reopens the door: it restores the thread to your lists without starting a run.

Archive is for threads you're done looking at. To mark work finished without hiding it, mark the thread idle instead.

## Todos are the agent's visible plan

For multi-step work the agent keeps a todo list: its working plan, updated as it goes. Items move through `pending`, `in_progress`, `completed`, `cancelled`, and `deferred`, with at most one item in progress at a time. Watch it to see where a long run actually is, and challenge it if the plan looks wrong: "skip step 3, the migration already ran" is a perfectly good interrupt.

## Voice input

The microphone button in the composer dictates straight into the message, live, at your cursor; you can keep typing around it while you talk. Accept commits the transcript, discard throws it away, and a recording auto-accepts at the 10-minute cap so nothing you said is lost. Undo reverts the dictation as one edit.

## Attachments

Attach images and files to any message from the composer; they land on the agent's machine, where it reads them with its ordinary tools. Screenshots of a bug beat descriptions of one.

## The command menu

Cmd+K opens the command menu from anywhere:

* Typing searches your threads full-text: titles, thread codes, and message content.
* It also finds pull requests, automations, and settings pages as you type.
* At rest it lists your most relevant threads in the same priority order as the sidebar, plus navigation and theme actions.
* Tab hands off to a full new-thread composer seeded with whatever you typed, so a thought becomes a thread without leaving the keyboard.

Every keybinding here and in the composer is configurable at Settings → Shortcuts.