Threads

An issue covers one piece of work: it gets a branch, produces a change, merges, and closes. A thread stays open across many of them. It is a standing topic — a subsystem, an area you keep returning to, an ongoing design discussion — that keeps its context while individual pieces of work come and go underneath it.

A thread owns no branch and writes no code. An agent acting for a thread cannot commit; the attempt is refused rather than silently dropped. It gets work done by filing child issues, which do have branches.

When to use one

Use a thread when the subject will outlast the change you are making right now: the parser, the settings surface, performance, a design discussion that will produce several changes over weeks.

Use an issue when there is a specific outcome you could merge.

Starting one

Threads appear in the sidebar beside issues, identified by a name rather than a number — performance, settings-ui, docs. Create one with New thread in the issue list, and write its opening message. If you do not give it a name, one is derived from what you wrote.

From there you talk to it. It reads code, asks you questions, and files issues.

The arc

A thread keeps one living document, its arc: where the topic stands, what has been decided, and what is coming. The thread agent maintains it as the work moves, and it appears as a tab on the thread, where you can read and edit it like any other artifact.

The arc is a summary rather than a log, so it stays short as the thread's conversation grows long. When you want to know where something stands without reading back through months of discussion, open the arc.

Child issues

A thread files child issues and lets them run. Each child gets its own branch, its own agents, and its own pull request; the thread keeps the context that produced it and reacts to what comes back.

A child filed under a thread branches from the base branch as usual — the thread relationship routes attention, not branch ancestry. A child filed under a parent issue is the case where the branch comes from the parent; see Coordinators.

Sleeping and waking

A thread is idle most of the time. It wakes when something it cares about happens — a child needs a decision, a pull request merged, you sent it a message — acts, and goes back to sleep. Idle is a thread's normal state, not a sign that something is stuck.

Threads are meant to be left running for a long time. The transcript and the arc both persist, so a thread you have not opened in a month still knows what it was doing.

Closing and reopening

Close thread in the thread menu makes it go quiet and leave the sidebar. Nothing is lost: its transcript, its children, and its name are kept, and Reopen thread brings it back at any time.

Threads and coordinators

Both run long and both drive child issues. The difference is scope: a coordinator drives one feature and is finished when it ships, while a thread covers a subject that is still there afterwards. A thread can hand a specific piece of work to a coordinator.