Run and navigate agents

Use a named workspace for each piece of work you want an agent to handle. Each workspace has a separate Git checkout and keeps its conversation for you to return to.

Start work

Inside a Git repository with at least one commit:

coco create

The walkthrough lets you choose the name, code and conversation starting points, profile, model, and what to do after creation. Press Enter to keep the highlighted default. Existing workspaces appear when you choose one as the conversation source. When you run it inside a reusable CoCo workspace, that current workspace is offered directly. You can also enter an exact Codex thread ID.

For a faster direct command, provide the name and instruction:

coco create fix/login -s "Fix the login redirect and run its tests"
coco create review/cache -s "Review the cache for correctness issues"

-s is short for --send. Add -j to open the Codex UI after sending:

coco create investigate/search -s "Investigate slow searches" -j

Use coco create fix/login -i when you already know the name but still want the walkthrough. Any other flags you provide prefill and skip those decisions.

To prepare a workspace before giving it an instruction, use coco create fix/login. Its status is Prepared until work begins. The first create also adds that repository to CoCo.

CoCo normally starts from your current commit on a new coco/<workspace-name> branch. See Choose code and context to select another base, reuse a conversation, or bring local changes.

See who needs attention

coco list
coco status -f

Both show workspaces in the current repository. status -f keeps the display updated until Ctrl+C. Use coco status fix/login for one workspace’s details and any pending request. While an agent is working, status may add a short live detail such as Working · Checking tests or Working · Compacting context.

State	What to do
Prepared	Send an instruction or open the Codex UI
Working	Let the agent continue or enter its conversation
Needs approval / input	Use the displayed decide command or jump
Ready	Review the response or send more work
Unloaded	Use send or jump to continue the saved conversation
Failed / Unavailable	Inspect the workspace details and troubleshoot

Ready means the agent can accept another instruction. Review its changes before treating the work as complete.

Enter and leave the conversation

coco jump fix/login

Use /quit or /exit to leave the Codex UI. Active work continues while cocod stays running. An explicit interrupt inside Codex cancels that turn.

Run coco jump without a name for a selector. Navigate with arrow keys or j/k, press Enter, or press a displayed number to choose immediately.

Send another instruction

When the workspace is ready:

coco send fix/login "Add a regression test"

The command returns after the instruction is accepted. Add --wait to print the final response when it arrives. You can send from another terminal while the Codex UI is open, provided the agent is ready.

coco send fix/login prompts for the message. coco send lets you choose the workspace first. CoCo currently accepts one active turn per workspace; wait for it to finish before sending the next instruction.

Work across repositories

Point create at another repository without changing directories:

coco ../api create fix/login -s "Fix the login redirect"

CoCo adds the repository automatically. Put its path before later commands to work there:

coco ../api jump fix/login

Use coco repo add /absolute/path/to/api when you want a repository to appear in lists and selectors before creating a workspace. coco repo list shows all currently added repositories.

For an overview of every repository, use -a:

coco list -a
coco status -aft

The tree view gives each repository its own path heading and unfolds shared parts of names such as frontend/login and frontend/search. A unique path stays on one line. Omit -t for the flat table.

For one workspace whose name you want to find globally, use -g:

coco jump fix/login -g

If that name exists in several repositories, select one with its path. The CLI reference covers full IDs and scope options.

Answer a request

When status gives you a decision ID:

coco decide <decision-id>

Review the request and select a response. Questions may accept text; secret answers are hidden while typing. You can also respond from the Codex UI.

For resource measurements and token counts, see Monitor usage. When finished, review and clean up the workspace.