Type to search the docs and updates.

Browse documentation

Companion list

The list of the companion shows your conversations. Each row opens its chat where it lives.

The list

Click the companion circle, or press its shortcut, to open the list. Type to search.

GroupWhat it holds
Needs youChats waiting for a permission, then an answer, then unread replies. Newest first.
WorkingThe agent is busy.
ActiveOpen chats, and app or cloud chats until you archive them.
ArchivedClosed chats, and chats you archived in their app.
Details: keys
KeyWhat it does
⌃⌥V on a Mac (Ctrl+Alt+V elsewhere)Open the send picker from any app. You can change it.
Cmd+Shift+VOpen the send picker in the open list, keeping your search.
Arrow keys, EnterPick a chat, then open it or send to it. In the right-click menu, move between its items.
EscapeCancel the picker, or keep the old name in a rename.
F2Rename the selected row.

Open a chat

Click a row to reach its chat.

ChatWhat a click does
Running in Terminal or GhosttySelects its tab.
Ended terminal chatResumes it in a new tab.
Claude Code --bg sessionSelects the tab that runs claude attach, or opens one.
Anything elseOpens its app, editor or browser.

If a chat does not open, the reason stays above the list.

Details: tabs, background sessions, slow opens, resume command
  • The first time, macOS asks to let the companion control each terminal app.
  • The reason a chat did not open stays above the list until you dismiss it or open another chat.
  • An ended terminal chat resumes in a new tab of the app it last ran in.
  • When only the app can come forward, the list stays open and says where the chat runs.
  • claude --bg runs in Claude's own background service, not in a terminal app.
  • The tab is found by its short id, such as e3469759, or its exact full name. A tab attached with the start of an id or part of a name is not recognized, since it may be another session.
  • With no such tab, a new tab runs claude attach <id> in the session's folder, in the app it last ran in when it remembers one.
  • The short id comes from claude agents --json.
  • claude is looked up on PATH, then in ~/.local/bin, ~/.claude/local, /opt/homebrew/bin and /usr/local/bin.
  • Leaving that tab does not stop the session.
  • When switching fails, or claude agents cannot run or does not list the session, the list offers the claude attach command to copy, or says to find its id with claude agents and run claude attach <id>.
  • An open over 60 seconds keeps the list hidden and goes on in the background.
  • If it then fails, such as when macOS asks to allow Automation, the list shows the reason, the chat's name and Copy resume command as soon as it shows, whatever the search. Another message on screen comes first; the late one follows once you dismiss it.
  • No answer at all says "agnostic-ai did not answer in time. The chat may still have opened."
  • Clicking the same chat again while it opens starts no second copy.
  • Copy resume command copies the command to run in a terminal.
  • It is also offered for a chat still running where no tab shows it, such as in a detached tmux session or after its tab closed. It comes with a note to end that process first, since two copies of one session would compete.
  • A chat whose tab was found, and a Codex thread Codex's background service keeps, never offer it.

Send copied text

Send text you copied to any chat without switching apps.

  1. Copy text anywhere.
  2. Press ⌃⌥V on a Mac (Ctrl+Alt+V elsewhere). The list opens with a banner such as "Click a chat or press Enter to paste these 14 words there".
  3. Click a chat, or pick one with the arrow keys and Enter. Escape cancels.
ChatWhat happens
Live Terminal or Ghostty tabIt comes forward with the text in its input. Press Enter.
Any other chatIt comes forward. Paste with Cmd+V.

Only one chat can take text? It goes straight there. Change the shortcut under Send copied text in the list's ⋯ menu or the circle's right-click menu.

Details: which chats, search, Markdown, permissions, errors
  • Offered chats: this machine's chats under Needs you, Working and Active. Archived chats are never offered, even in a search; a search narrows the rest.
  • With the list already open, Cmd+Shift+V opens the same picker but keeps your search, and never sends by itself.
  • While a search is on its way, Enter does nothing. Its answer keeps the selected chat when it still matches, else selects the first.
  • "Straight there" means: exactly one chat can take typed text and its row is visible (not inside a folded group). The banner names the chat, the text flies into its row, and the list hides.
  • Text copied from a web page goes as Markdown when it holds links, tables, code blocks, headings or lists, and the reply says so.
  • Nothing copied shows "Nothing to send: copy some text first." A clipboard the companion cannot read says so. Neither sends anything.
  • A send waits up to 60 seconds. With no answer by then, the list says the text may have been typed: check the chat before you send again.
  • Pasting into Terminal needs macOS Accessibility access, granted once in System Settings › Privacy & Security › Accessibility to the companion or to the terminal that runs agnostic-ai serve.
  • What the server refuses: POST /api/conversations/send.

Rename a chat

Give a chat your own name. The web interface shows the same name.

  1. Right-click a row and choose Rename… (or press F2, or use the pencil).
  2. Type the name. Enter saves, Escape keeps the old name.

The chat's own tool takes the name first. Only then is it saved, so every serve on the machine shows it and finds it in a search. If the tool refuses, the field stays open with the reason, such as "Codex is not installed". Claude app chats, Cowork tasks and Codex cloud threads cannot be renamed yet.

Details: how each tool is renamed, where the name lives, errors
ChatHow it is renamed
Claude CodeAdds the custom-title line Claude Code's own /rename writes.
Claude Code cloud sessionChanges the title on claude.ai/code, using the login Claude Code keeps in the macOS keychain.
CodexAsks codex app-server to rename the thread (thread/name/set). Needs codex.
CursorChanges the name in Cursor's own database. Needs sqlite3.
ChatGPTAsks chatgpt.com to change the title, using the ChatGPT login the Codex command keeps.
Claude app chat, Cowork task, Codex cloud threadCannot be renamed yet.
  • Other reasons shown: "Sign in to ChatGPT in the Codex app".
  • Marks file: the name is saved in conversation-marks.json, only once the tool has it.
  • A new message keeps the name.
  • Right-clicking does not open the chat or mark it as read.
  • A click on the name still opens the chat.
  • A running chat's Terminal or Ghostty tab takes the name as its title, and keeps it after the session ends.
  • Claude Code: a session that is still running may write its old name back.
  • Cursor editor chat: the name changes in the chat list and in the chat's own data, and nowhere else. Cursor may write the old name back if it has the chat loaded.
  • cursor-agent chat: the name changes in its store.db, only when a look at the open files just before the write finds the chat not running.
  • Cursor renames keep the chat's done and read marks.
  • ChatGPT: the app shows the new name once it syncs.
  • On failure the row keeps its old name. The server logs what the tool said on its standard error, with the tool and the conversation id.

Mark chats as read

Clear a chat that needs you without opening it.

  • Mark as read: right-click the chat.
  • Mark all as read: the button beside Needs you, while the group is unfolded. It marks each chat the group shows, after the search and the All, Local or Cloud choice.

The chat leaves Needs you in the companion and the web interface, and moves where an opened one would: Active, or Archived when closed.

Details: same mark as opening, failures, the circle count
  • The mark is the seen mark that opening a chat saves, stored through the server.
  • When a closed chat moves at once and when it waits a day: see state.
  • On a chat resumed by hand with a reply from before, it clears the orange ring. The next write brings it to Needs you.
  • If the save fails, the row stays and the list shows why.
  • Mark all as read saves one chat after another.
  • A chat written in since the list was drawn is skipped and stays.
  • The first failed save stops the run and says why.
  • The list holds every blocked and unread chat of any age.
  • The circle counts them all, whatever the search or place. With All chosen and no search, it shows zero after the run until something new is written.

Rows and order

A row shows the title, the agent's latest reply in one line, and a meta line.

PartWhat it shows
Meta lineTool, where it runs when not here (Cloud, Chat, Cowork or Shared), folder, age.
Reply lineThe agent's question, or the start of its last message.
Approval pillOrange, replaces the reply line while a call waits for approval.
Approval reasonUnder the pill, why approvals left the request to you.
Approved for you"▸ 3 approved for you" under the meta line, while approvals answer prompts.

A chat started with conversations start sits under its parent in the same group.

See what a chat waits for for where each tool's wait comes from.

Details: pill kinds, folders, replies, pill limits, child chats
PillWaiting on
Approve git push origin…A command (its first words).
Approve edit dashboard.tsxAn edit or a write.
Approve read .env.exampleA read.
Approve github.comA fetch.
Approve Notion fetchAn MCP tool.
Needs permissionA call that is not known, as for a Codex cloud thread.
  • A row names the conversation's folder when it has one. A cloud session has none.
  • When two folders end in the same name, the row adds the parent folders that tell them apart, such as shop/api and billing/api.
  • The tooltip and screen-reader description give the full path.
  • Local Claude Code, Codex and Cursor chats show the reply line. Cloud sessions do not yet.
  • A reply older than your latest prompt is not shown.
  • A reply that may hold a password or key is left out. See reply.
  • Needs you already says a chat waits, so the meta line does not repeat it.
  • A detail that may hold a password or key is left out of the pill, and the pill names the tool only.
  • The agent's reply moves to the row's tooltip while the pill shows.
  • A question, or a wait whose kind the tool does not say, keeps the reply line.
  • A child chat that waits for you stays under Needs you, even when its parent is active or archived.
  • A chat started from another stays under it. The two move up together to the place of the more urgent one.

Working rows and subagents

Working chats show an animated gyroscope. Each working Claude Code or Codex subagent adds a small blue copy.

PartWhat it shows
"▸ 3 subagents"A line under the meta line. Click it to unfold.
Unfolded listNewest first, five at most, then "+N more".
Subagent rowGyroscope, title, a Claude Code subagent's latest message when it wrote one, tool, type if any, age.

A Codex subagent opens its own thread, or switches to its terminal. A Claude Code subagent opens its chat, and a notice names the subagent. For a chat in a terminal tab, it also says to switch to it in the agent rows below the prompt. A failure that comes later replaces the notice. In the send picker, a click on a subagent row sends the text to the chat it runs in.

Details: counts, parents, animation
  • The five-bulb gyroscope keeps constant brightness, with bulbs at different orbital radii and depths.
  • A number and agent icon show the count, with a tooltip and accessible label. Unavailable counts add none.
  • Working is named once, in the blue section header.
  • Working subagents keep an idle parent in Working, with its own still dot.
  • A parent that asks you a question stays in Needs you with a plain orange dot and no orbiting bulbs of its own. Its working satellites keep their blue cores and animation.
  • Cloud sessions and other tools' subagents are not tracked.
  • When the server counts working subagents but cannot list them, the count sits on the subagents line instead.
  • The list starts folded. Which chats are unfolded is kept until the companion quits.
  • Only working subagents are listed and counted. A finished one leaves, and the toggle goes away once none works.
  • codex exec runs count among them while they run.
  • With animation off, or the system's Reduce Motion on, the indicator stays still with its heading and worker count visible. See Animate companion.

Archived chats

A chat moves to Archived when it is closed.

ChatWhen it archives
Terminal chatAs soon as no process holds it, even with an unread reply.
Editor panel, Claude Code background jobA day after its last write.
Desktop app session, Claude chat, Cowork task, ChatGPT chat, cloud sessionOnly when you archive it, here or in its app.

Archiving here never changes the chat in its app. Click an archived chat to resume it.

Details: unread replies, resuming, working chats, silent Codex chats
  • A process that ends shows as archived within a minute. Quitting an app archives none of its chats.
  • The tooltip of an archived chat says Resume in Terminal, or the app it last ran in.
  • An archived chat has no read or unread state, even when it closed with a reply you have not read. It shows no ring, adds nothing to the Archived header, and does not count in the circle. You can delete it without reading it first.
  • If you resume such a chat by hand, its old reply does not bring it to Needs you. It shows under Active with its mark ringed in the Needs you orange until you open it or mark it read. The tooltip says "Resumed with a reply from before that you have not read". A later reply does bring it to Needs you.
  • An editor panel or background job archives after a day because nothing reliable says when it closes.
  • An archived or hidden chat that starts working moves to Working as soon as its tool reports the work, before it writes a new message. For local Claude Code that is the next poll; a cloud session can take up to a minute.
  • That clears the archive in conversation-marks.json, so the web interface agrees and the chat does not go back to Archived when the work ends.
  • A local Codex chat that wrote nothing for 5 minutes moves to Needs you. Codex does not say when it waits, so the silence is all the server knows.
  • Its tooltip and the age on its meta line say "No activity for 7m". The web interface says that in place of "Waiting for you".
  • Delete permanently… removes an archived chat. See Delete an archived chat.

Shared Remote Control rows

A local Claude Code session shared with claude.ai through Remote Control is one row, marked Shared. It stays one row once it closes. Marking it read, or opening it on claude.ai, clears both.

EventWhat happens
A claude.ai reply within two minutes of the session's last replyIt stays folded into the archived shared row, which shows no ring.
A later replyThe cloud row shows alone, under Needs you.

The server restarting, or resuming without Remote Control, shows two rows again. Deleting the local session leaves the cloud row.

Details: unconfirmed disconnect activity, restarts
  • Once closed, the one row is the archived local row.
  • After you delete the local session, the cloud row stays because claude.ai still keeps it.
  • The link is kept in memory only.
  • After a restart, the cloud row does not count a reply the local row already showed.
  • One exception: the last reply reached claude.ai after the server last read the list while the session ran, and you did not mark it read. Then the cloud row counts that reply once. The archived local row shows no ring for it.

What a chat waits for

A row that waits for you carries waiting when its tool says what for: {for, tool?, detail?}. for is permission (approve a tool call) or answer (a question). It is omitted when unknown.

ToolWhere the wait comes from
Local Claude CodewaitingFor in sessions/<pid>.json.
Codex cloudwaitingOnApproval is permission, waitingOnUserInput is answer.
Local Codex, Cursor, Claude app, Claude Code cloudNot said, so no waiting.
Details: Claude Code values, tool and detail fields
  • Codex cloud rows have no tool, since the cloud names no call.
  • Local Codex does not record pending approvals in its rollout.
  • permission prompt and sandbox request are permission. input needed is answer. Other values, such as dialog open, give no waiting.
  • For a permission, tool and detail come from the oldest tool call at the end of the transcript that has no result yet.
  • tool is the name Claude Code writes, such as Bash, Edit or mcp__claude_ai_Notion__notion-fetch.
  • detail for Bash: the first words of the command, about 30 characters, with … when cut. A leading cd <folder> && step is left out.
  • detail for Edit, MultiEdit, Write, Read and NotebookEdit: the file name.
  • detail for WebFetch: the domain.
  • detail for an MCP tool: the server and action, such as Notion fetch. A server registered by id is named from its action, so the id never shows.
  • Other tools have no detail.
  • A call whose line is larger than the transcript end the server reads gives no tool.
  • detail is left out when it, or the first 4 KB of the text it was read from, may hold a credential, by the rule reply uses.

Chats archived in their app

A chat you archived in its own app shows under Archived, so un-archiving it in the app brings it back.

ChatArchived in its app
Codex thread, Cursor editor chat, Claude Cowork taskListed as archived.
Claude chatListed as archived when it leaves the app's list.
ChatGPT chat, cursor-agent chatNot known: no archive flag. A normal row.

A chat that waits for you or works still shows under Needs you or Working.

Details: when an archive ends
  • The conversations API lists these chats as dormant, and the web interface lists them by date.
  • The server reads the app's archive flag on each read and writes nothing to conversation-marks.json.
  • Codex keeps the time it archived a thread. Cursor and Cowork keep no time for the archive.
  • ChatGPT's chat list and cursor-agent keep no archive flag.
  • A tool's count includes its archived chats.
  • The archive holds until something is written in the chat after it, or its tool says the agent is working, as an archive mark of your own does. The chat then shows by its usual state, even while its app still says archived.
  • Un-archiving and archiving again in the app starts a new archive.
  • A write counts when it comes after the app's archive time, in whole seconds.
  • When the app keeps no time, a write counts when it comes after the last write the server saw when it first read the chat as archived.
  • The server keeps that first write, and whether a write or work ended the archive, in memory only. A restarted server starts again from what the app says.
Details: Claude app chats and deleted chats
  • The Claude app keeps no archive flag here, only its list of chats that are not archived, and only the pages of it you scrolled to. The server remembers the Claude chats it saw in that list, in memory.
  • A chat that leaves the list shows under Archived, as last seen, when it is not older than the oldest chat still in the list. That shows it did not just fall off the pages the app keeps.
  • A chat that leaves the list and is older than every chat still in it may sit on a page the app no longer keeps. It leaves the agnostic-ai list, and the server forgets it.
  • A chat you deleted in the app cannot be told apart from one you archived. It shows under Archived until it is older than the oldest chat in the list.
  • A chat back in the list, after you un-archive it, is a normal row again.
  • A read of the app's storage that fails says so in the Claude Code tool's note, and nothing is read as archived from it.
  • A restarted server remembers nothing, so a chat archived while no server ran is not listed.
  • A chat deleted in its app leaves the list once its store no longer holds it.
  • Its marks leave conversation-marks.json once full reads have missed it for 30 days. This holds only for Claude Code, Codex and cursor-agent, whose stores the server reads in full. See Marks.

Delete an archived chat

Remove a chat from this computer for good.

  1. Right-click a chat under Archived and choose Delete permanently….
  2. Read the confirmation. It names the chat and what goes.
  3. Confirm. Cancel, Escape or a click outside the question keeps the chat. The list then says how much space it freed.
ChatCan be deleted
Claude Code, on this computerYes
CodexNo. Close it, then run codex delete <id>.
Cursor editor chat, cloud sessionNo. Delete it where it lives.
cursor-agent, any chat on WindowsNot yet.

A chat that cannot be deleted says why when you choose the item.

Details: when it is offered, refusals, limits
  • Codex deletes a thread even while it is open, so close it first.
  • Delete a Cursor editor chat in Cursor, and a cloud session where it runs. cursor-agent chats cannot be deleted yet.
  • Cursor keeps every chat in one shared database.
  • On Windows the server cannot tell whether a session still runs.
  • Offered on any archived chat that no process holds and whose latest reply you have read: one you marked complete, or one that is closed.
  • Closed means right away for a Claude Code, Codex or cursor-agent chat run in a terminal, and after a day for an editor panel or a background job.
  • A chat that went quiet by itself is checked again when you confirm. If it closed with a reply you have not read, or anything was written in it while the delete runs, it is not deleted.
  • A refused or partial delete keeps the row. The reason stays above the list until you dismiss it, with any folder still on disk.
  • POST /api/conversations/delete lists what is removed and what stays, such as Claude Code's own prompt history.
  • Limit: a session that starts in the moment between the last check and the removal is not seen.
  • Limit: a forked Claude Code session may still point at saved tool output in its parent's folder. Deleting the parent removes that output.