coincide command-line reference

Where it comes from

The tool ships inside the app, at Coincide.app/Contents/Helpers/coincide. It only works while Coincide is running with Command-line control on, in Settings › General › Command Line. That setting is on by default.

In Terminal. At launch, Coincide links the tool into the first folder it can write to among /opt/homebrew/bin, /usr/local/bin and ~/.local/bin, preferring one that’s already on your shell’s PATH. Settings › General › Command Line shows where it went. If that folder isn’t on your PATH, the setting tells you which folder to add. Coincide never replaces another program called coincide: it shows “… already exists and isn’t Coincide’s tool, so it was left alone.”
For agents. Every agent Coincide starts gets the tool on its PATH, plus COINCIDE_CONTROL_SOCKET and COINCIDE_THREAD_ID, so it can run coincide without any setup and refer to its own thread as this. When Command-line control is off, agents get none of these.

Run coincide help (or -h, --help) for the built-in summary.

Naming threads and projects

Commands that take THREAD accept, in this order:

this: the thread whose agent is running the command. It works only inside a thread Coincide started; elsewhere you get “this works only inside a thread Coincide started.”
a full thread ID, or a unique start of one at least four characters long;
the thread’s exact title (case doesn’t matter).

If a name matches more than one thread, the command lists the matches and stops, so use the ID. Archived threads are found too.

--project P accepts a project’s ID (or a unique start of it), its name, or its folder path (~ works). chats means the chats that have no project.

Commands

Command	What it does
`coincide projects`	Lists projects: ID, name and folder.
`coincide threads [--project P \| --chats] [--archived] [--running]`	Lists threads, newest first, with ID, state (idle, starting, running, needs approval, has a question, archived), project and title. `--archived` includes archived threads; `--running` shows only those starting or running.
`coincide agents`	Lists each agent with its ID, name and state, and under it the models it offers, with their reasoning-effort levels.
`coincide new [--chat \| --project P] [--agent A] [--model M] [--effort E] [--access full\|approval] [--plan] [--title T] [--wait] [--timeout S] [--open] [MESSAGE…]`	Starts a chat (the default) or a thread in a project, applies the options, and sends `MESSAGE` if you give one. With `--wait` it prints the reply when the turn ends.
`coincide send THREAD [--wait] [--timeout S] [--alternate] MESSAGE…`	Sends a message to a thread. While a turn runs, the message steers or queues as that thread’s follow-up setting says; `--alternate` does the other.
`coincide wait THREAD [--timeout S]`	Waits until the thread’s turn ends or the agent needs you, then prints the latest replies.
`coincide read THREAD [--count N]`	Prints the latest turn’s replies, or the last `N` replies.
`coincide status THREAD`	Shows the thread’s state, agent and model, how many messages are queued, and any approval or question waiting, with its ID.
`coincide stop THREAD`	Stops the running turn.
`coincide approve THREAD [--item ID] [--always]`	Approves the waiting approval request. `--always` picks the request’s “always allow” choice when it has one.
`coincide deny THREAD [--item ID] [--message TEXT]`	Denies it. `--message` goes to the agent when the request accepts a reason.
`coincide questions THREAD`	Shows the agent’s waiting questions, with each question’s ID and its choices.
`coincide answer THREAD [--item ID] [--answer QUESTION=ANSWER …] [ANSWER…]`	Answers them. With a single question, just give the answer.
`coincide archive THREAD`, `coincide unarchive THREAD`	Moves the thread to or from the archive.
`coincide open THREAD`	Brings Coincide forward and shows the thread.
`coincide help`	Prints the summary.

Options of `new`

Option	Meaning
`--chat` / `--project P`	Where the thread goes. A chat is the default; you can’t give both.
`--agent A`	The agent, by ID (`claude`, `codex`, `cursor`, `grok`, `opencode`, `antigravity`), name or the start of its name. Without it, the thread uses your default for new threads.
`--model M`	A model of that agent, by ID, name or the start of either. Without `--agent`, it’s looked up in the new thread’s default agent. Run `coincide agents` for the list.
`--effort E`	The reasoning effort, as `coincide agents` lists it for the model.
`--access full\|approval`	Full access, or ask for approval (`fullAccess` and `ask` work too).
`--plan`	Starts the thread in plan mode.
`--title T`	Names the thread.
`--wait`, `--timeout S`	Waits for the reply; needs a message.
`--open`	Shows the new thread in Coincide’s window.

Global options

--json prints JSON instead of text (see below).
--socket PATH talks to another socket than COINCIDE_CONTROL_SOCKET or the default, ~/Library/Application Support/Coincide/control.sock.
A MESSAGE of - is read from standard input, so you can pipe a file or another command’s output into a thread.
Options can go anywhere. After --, everything is part of the message, even words that start with --.
Options take their value as the next word or after =, as in --timeout=600.

Sending, waiting and reading

send reports how the message was delivered: sent when the thread was idle, queued for after the running turn, steered into the running turn, or interrupting when the thread’s follow-up setting is Interrupt. Steering works with Claude Code, Codex and OpenCode; with the other agents a steered message is queued. See the composer for how follow-ups behave.

--wait and wait poll the thread about once a second until its turn ends (including any queued messages) or it waits for an approval or an answer. The default timeout is 1,800 seconds; --timeout 0 waits as long as it takes. When the wait times out, the turn keeps running and the command prints “Still working; stopped waiting.”

The replies printed are the agent’s messages and errors after your last message. read --count N prints the last N replies instead, whatever turn they came from.

Approvals and questions

A thread that runs with Ask for approval stops at each command or file change the agent wants to make. status and a waiting --wait show each request’s ID. With one request waiting you can leave out --item; with several, Coincide lists their IDs and asks you to pick one.

For questions, questions prints each question’s ID and choices. Answer one question with plain text, or several with --answer QUESTION=ANSWER, repeated as often as needed (repeat the same question to give it several answers).

Exit status

Status	Meaning
`0`	Done.
`1`	Failed, for example Coincide isn’t reachable or a thread or model doesn’t exist. The reason goes to standard error.
`2`	Wrong usage: an unknown command or option, or a missing value.
`3`	The thread waits for an approval or an answer.
`4`	Timed out while waiting.

When Coincide isn’t running, or Command-line control is off, every command fails with “Couldn’t reach Coincide at … Is Coincide running, with Settings › General › Command-line control on?”

JSON output

With --json, each command prints one compact JSON value. Lists (projects, threads, agents, questions) print arrays. Commands that wait print an object with threadID, state (done, needsInput or timedOut), replies (an array of strings) and, when something waits for you, waiting; new and send add delivery. read prints threadID, running and replies.

# Start a Codex chat, wait for the answer and keep only the text
coincide new --agent codex --wait --json "List the TODOs in this repo" | jq -r '.replies[]'

How it connects

The tool sends requests over a Unix socket in Coincide’s data folder, one line of JSON each way. The socket is created for your user only, and Coincide checks that each connection comes from your user. There’s no network access and no pairing. That also means any process running as your Mac user can control threads while Command-line control is on; turn it off in Settings › General › Command Line if you don’t want that. When the data folder’s path is too long for a socket (with a long COINCIDE_DATA_DIR, say), the socket goes in your temporary folder instead.

A Debug build of Coincide (built from source) has its own data folder and socket, and its tool talks only to it. It leaves Terminal’s coincide to the installed app.