Threads and Conversations
Learn how Bridge handles long-running threads, comments, and subthreads. This guide explains how to steer work in progress without losing context.
Overview
Bridge helps you manage long-running work as a set of threads. Each thread can keep moving, pause for review, accept new direction, or branch into a subthread without losing the original context.
Use this model when you want to coordinate agent work over time instead of treating every request as a one-off prompt. It works best when tasks are related, need review, or may spawn follow-up work.
This page is a starter kit template. Adapt the examples and labels to match your own product language and workflow.
Core ideas
Thread lifecycle
Understand how a thread starts, runs, pauses, and continues.
Steering messages
Learn when a message changes the current run and when it waits.
Comments
Annotate a reply without interrupting the whole conversation.
Subthreads
Split off alternative paths while keeping the original thread intact.
Thread lifecycle
A thread usually follows a simple pattern: it starts with a task, runs until it needs more input, and then continues with your next message. In practice, that means you can keep a thread open while the agent works through a larger job.
You can think of the lifecycle as a loop. The thread receives context, produces output, and then waits for the next action. That action may be a steering message, a queued follow-up, or a branch into a new subthread.
Start the thread
Begin with a clear goal and enough context for the agent to make progress.
bridge thread start "Review the release notes and draft a summary"
Let it run
The thread works through the task and returns progress as it goes.
Review the result
Read the reply, inspect the changes, and decide whether to steer, queue, or branch.
Continue work
Send another message to refine the same thread or split the work into a subthread.
Steering versus queueing
Sometimes you want your message to change what the agent is doing right now. Other times you want it to wait until the current action finishes. Bridge treats those cases differently so you can stay in control without interrupting useful work.
Use steering when the new instruction should affect the current run immediately. Use queueing when you want the thread to finish its current step first and then process your follow-up.
Send a message that changes the current direction.
bridge thread send 42 "Focus on the database schema instead of the API layer"
Use this when the agent is still actively working and you want a correction right away.
Add a message that the thread should handle after its current work completes.
bridge thread queue 42 "After that, add tests for the migration"
Use this when the current task is still valid and the next step should happen afterward.
If a task is already producing useful output, queue the next instruction. If the current direction is wrong, steer it immediately.
Comments on replies
Comments let you react to a specific part of a reply instead of changing the whole thread. This is useful when you want to ask for clarification, approve a section, or request a small revision.
A good comment is specific. Refer to the exact paragraph, claim, or code block you want adjusted. That keeps the discussion focused and reduces unnecessary rework.
const threadReply = {
id: 42,
author: "Bridge",
text: "The migration is ready, but the rollback plan needs more detail.",
comments: [
{
author: "You",
text: "Please add a note about restoring the previous schema snapshot."
}
]
};
console.log(threadReply);
Branching subthreads
When you want to try a different approach, branch a subthread instead of overwriting the current path. The original thread stays as a record of what happened, while the new branch can explore an alternative.
This pattern is especially useful for implementation options, review revisions, and experiments. You can compare outcomes side by side and keep the decision trail intact.
bridge thread branch 42 "Try a simpler retry strategy"
await bridge.threads.branch({
threadId: 42,
message: "Try a simpler retry strategy"
});
Grouping threads by project
You can group threads by project folder so related work stays together. This makes it easier to switch between tasks, review history, and understand which thread belongs to which codebase or workspace.
A practical setup is to keep one group per project and then use thread names that describe the current objective. For example, you might keep one group for releases, another for bug fixes, and another for experiments.
| Grouping strategy | Best for | Result |
|---|---|---|
| One group per project | Ongoing development | Easier navigation and shared context |
| One group per release | Shipping work | Clear focus on a specific milestone |
| One group per investigation | Debugging | Separate evidence from implementation |
| One group per experiment | Comparative work | Cleaner branching and review |
Example workflow
Use this sequence when you want a thread to move from planning to execution without losing context.
Create a project thread
Start with a task that belongs to a single project folder.
Let the agent work
Allow the thread to produce a first pass before you intervene.
Add a comment
Comment on the reply when you only need a local correction.
Branch a subthread
Fork the work if you want to test another approach.
Queue follow-up work
Add the next task once the current run is complete.
Practical tips
Be specific
State what you want changed, not just that something is wrong.
Preserve context
Keep related work in the same thread until you need a branch.
Review before branching
Check whether a comment is enough before creating a new path.
Avoid flooding a thread with unrelated instructions. A small, focused message usually produces better results than a long list of changes.
Summary
Threads give you a way to manage agent work as an ongoing conversation. You can steer active work, queue follow-ups, comment on specific replies, branch subthreads when needed, and group related threads by project.
Use the simplest control that fits the moment. That keeps the workflow readable and makes it easier to revisit decisions later.