AI threads

Persistent AI conversations that execute on a connected machine and stream back into the app.

Threads are persistent AI conversations attached to project work. They can be project-level or task-related, and they execute through a connected Convoy CLI profile — the agent runs on a teammate's machine, against a real checkout of your code, and its output streams back into the thread for everyone with project access to see.

Requirements

Threads only execute live when at least one compatible CLI profile is online for the project. Connecting one is covered in Quickstart: join a deployment. Claude Code, Codex, and OpenCode threads execute today; see the Roadmap for per-runtime capabilities and the status of other runtimes.

Sending a message

Open a project thread or start a new one (N).
Select the online profile (and working directory) the agent should run in. The working-directory selector can also target a git worktree — pick an existing one or create a new one from any branch (the CLI creates it on first run), so parallel threads never collide in one checkout.
Pick the runtime, and where the runtime has a catalog, the model and reasoning effort. Modes (Agent, Ask to approve, Plan, ...) control what the agent may do without asking; the offered set depends on the runtime.
Attach context: task references, files, or images (Mod+U).
Send the prompt. Shift+Tab toggles plan mode where supported.

The web app stores your message and queues the thread. The connected CLI claims it, runs the selected runtime in the chosen local working directory, and streams output back.

What you see while it runs

A thread message moves through pending → streaming → completed (or failed, which is retryable). While streaming, the thread renders:

assistant text and reasoning (token-by-token, unless the connection runs convoy connect --buffered)
tool calls and tool output from the agent
runtime notices (for example provider rate-limit retries)
a context-window meter where the runtime reports token usage
interactive approval cards between the conversation and the composer when the run's mode asks before acting: tool approvals, questions, and plan review. Supported for Claude Code, OpenCode, and Codex over the app-server transport (the connect default).

Queued messages and steering

If you send more messages while the agent is working, they queue up and are processed as the next batch after the current response finishes — within one thread, responses are sequential.

While a run is streaming, queued messages appear in a strip above the composer with three actions:

Steer — inject the message into the live run as its next turn instead of waiting for the run to finish. Offered when the runtime and the connected CLI support it: Claude Code always, Codex unless the connection runs --codex-exec.
Edit — remove the queued message and move its text back into the composer.
Delete — discard the queued message without sending it.

When something fails

A failed response can be retried from the UI; retrying requeues the user messages from the failed batch. If a thread sits in pending and never starts, the usual cause is that no compatible profile is online — check the profile selector, or convoy status on the machine that should be connected. See CLI troubleshooting.

Threads vs. MCP

Use threads when you want persistent conversation history in the app, streamed output visible to teammates, and AI work tied to project records. Use MCP when you want direct task access from inside your own editor or AI client. See MCP workflows and scoping.

How Convoy works — what happens between send and stream
Security model — what a connected agent can do, and who can drive it