Projects and tasks

Plain xcb opens your thread from any directory: one conversation for all your projects. Each prompt becomes a task in one project folder, and tasks keep running after you close the terminal.

How xcb picks a task’s folder

A project is a folder. For each prompt in the thread, xcb uses the first of these that applies:

a path in the prompt, such as in ~/src/app;
a registered project name in the prompt;
the project you focused with /workspace;
the project of your last task, when the prompt reads as a continuation;
the folder you started xcb from (--cwd sets it), then recent work.

The reply names the folder and the reason, such as “Started Fix the parser in app · named app · /workspace to move”. When a prompt names a folder xcb hasn’t seen, or matches several projects, xcb asks, keeps your draft, and saves nothing. A less certain choice waits 8 seconds before it starts so you can move it.

xcb --cwd /absolute/path/to/your/project   # the thread, hinting this project
xcb chat --new                              # a project view: every task runs in this directory

xcb picks only folders you have used or registered, and never your home folder, its hidden folders, ~/Library, or system folders. Register one with /workspace add <dir> or xcb workspaces add <dir>. The managed harness guide lists every rule.

Follow your tasks

/tasks lists running and finished work; xcb tasks does the same from a script.
/attention collects questions and approvals from every task. Answer a question with /reply <task-id> <answer>.
The session cards above the chat show each task’s model and latest response. Press F6 to browse them.
Open another terminal for a second view of the same tasks.

Guide or stop a task

/steer <task-id> <guidance> adds guidance for the task’s next turn without interrupting it. In /agents, select a task and press s to write guidance or a to answer its question; /task returns to new work.
/cancel <task-id> asks a task to stop. With several running tasks and none selected, a bare /cancel asks which one.
/workspace move <task> <name|path> moves a task that hasn’t started. A started task can’t move; cancel it and send the prompt again.

Cancellation finishes when the provider has stopped and xcb has recorded the result.

Come back to your work

xcb                                   # your thread, from any directory
xcb conversations                     # the thread and project views
xcb chat --resume <conversation-id>   # reopen one of them
xcb workspaces                        # project folders the thread picks from
xcb attention                         # questions and approvals waiting on you

Inside xcb, /sessions switches between the thread and project views. In the thread, /new clears the project focus; in a project view it starts another view.

Direct provider sessions

xcb run and xcb --json route save direct sessions, each on one account and model.

xcb sessions                 # direct provider sessions
xcb resume                   # reopen the latest one in the terminal
xcb resume <session-id>

xcb resume reopens a session and its folder in the terminal. It is not a headless continuation command. In a direct session, /accounts and /model open the account and model pickers, /new starts another session, and /sessions switches between them. Finish the current turn before changing its account or model.

Backlog, schedules, and project agents

Each project keeps a backlog and work history shared by the thread and every project view over its folder.

/backlog add <work> saves work for later; /backlog shows this project’s queue and /backlog all every project’s.
/schedule every <seconds> <prompt> repeats a prompt. Schedules run while the background supervisor runs; on macOS, xcb service install starts it at login.
/project grant <tasks> <hours> <goal> lets a project start a limited number of follow-up tasks on its own; /project pause stops that. A grant covers only its own folder.

These commands never guess a project: without one you named, the focus, or a selected task, they ask and save nothing. The project agents reference covers programs, daemons, and Wordcell memory, and the terminal guide covers keys, search, Vim editing, and draft recovery.