Conversations API
These routes of the local API serve the Conversations list and the companion. Use them to list your AI chats, reopen one where it lives, send it text, or mark it read.
The three calls most people use, against agnostic-ai serve --global on the default port:
curl -s "http://127.0.0.1:4310/api/views/conversations?tool=claude"
curl -s -X POST http://127.0.0.1:4310/api/conversations/open \
-H 'Content-Type: application/json' -d '{"tool":"claude","id":"<id>"}'
curl -s -X POST http://127.0.0.1:4310/api/conversations/mark \
-H 'Content-Type: application/json' -d '{"tool":"claude","id":"<id>","as":"seen"}'
The first call lists chats and their state. The second reopens one. The third marks one read. POST routes must come from the server's own origin. The sections below list every route, field and status code.
GET /api/views/conversations
List conversations, newest first, one week per page.
| Query | Meaning |
|---|---|
editor=<id> | The editor chosen in Settings, so editor links use its scheme. |
before=<time> | The next page, which holds older conversations. |
q=<words> | A search. |
tool=claude, codex, cursor or chatgpt | List one tool. |
Each row has a state, the first of these that holds:
blocked: open, and its tool says it waits for you.working: open, and its tool says the agent is busy.dormant: archived in its app.completed: you marked it completed. It holds until something is written or its tool reports work.dormant: a terminal session no process holds, even with a reply you have not read.unread: written after you last saw it.active: open; a desktop, chat, Cowork or cloud conversation of any age; or written within 24 hours when the server cannot tell whether it is closed.dormant: otherwise.
Search, paging and scope
A search keeps the conversations of every age where each word appears in the title, folder, branch, latest prompt, latest reply, tool or app, as the row shows them. Case is ignored.
- A withheld field does not match.
- Its pages hold only matches, and the page adds
matches, the count across all pages. - A
qover 200 characters, or anothertool, is a 400.
The route lists Claude Code, Codex and Cursor conversations, and ChatGPT chats when its desktop app is installed, from each tool's own store. The newest come first, by the last message from the person or the agent.
- Each page holds one week. The first page holds every open conversation, every blocked or unread one, and the past week, so, without a search or tool filter, it holds every conversation
needsYoucounts. A later page leaves those out. - A page asked for with
beforeholds the week before that time, and reaches past weeks with no conversation. - The page returns
fromandto, andnext, thebeforevalue of the following page, absent when no older conversation remains. - A
beforethat is not an RFC 3339 time is a 400. - A project server lists the conversations started in the project or one of its Git worktrees. A global server lists them all.
- Runs a program started (Claude Code SDK sessions,
codex exec) are left out. Acodex execrun that a local Claude Code session started shows in that session'shelpersinstead while it runs. - A Claude Code session or Codex thread that was opened and never typed in is left out: it has no title and no prompt to show. A Codex thread stays when the agent replied, or when you named it with
POST /api/conversations/rename. A left-out one is not counted inneedsYouor a tool'scount.
Codex and Cursor stores are read with the sqlite3 command.
Response fields
Returns tools and conversations:
toolsis{tool, label, found, count, shown, note?}.countis every conversation the tool holds,shownis how many this page holds, andnotesays why a store was not read.- Each of
conversationsis{tool, app, id, title, folder?, branch?, startedAt?, updatedAt, opening?, prompt?, reply?, withheld?, live?, activity?, waiting?, quietSince?, workingSubagents?, helpers?, deleteUnsupported?, parent?, cloud?, approvals?, open}. approvalsModeisrevieworyolo, the loosest approvals mode the home config sets; absent inask.
Conversation fields:
appiscli,ide,desktop,background,cloud,chatorcowork.folderis where the conversation started and where it resumes.liveis true while it is open: a running Claude Code process holds it, a Codex process has its thread loaded, a runningcursor-agenthas its chat open, a Cursor window shows it selected, or a cloud provider reports an active session.activityisworking,waitingoridlewhen available. Claude Code reports local session status. Local Codex activity is inferred from its rollout. Cloud sessions use provider status.waitingis{for, tool?, detail?}: an approval or an answer. See waiting.approvalsis{approved?, recent?, reason?}: how many requests the approvals hook approved for this session, the latest 10 of them as{time, call, detail?}newest first, and why a permission wait reached you. Inreviewandyoloa wait the hook approved, or may still answer, isworkingand not counted inneedsYou, exactly so only on the first page with no search or tool filter. See approvals.quietSinceis set only with awaitingactivity that was inferred from silence, not reported by the tool. It is the time of the last write, so a client can say how long nothing came. Today only local Codex sets it.workingSubagentsis an optional native task count for local Claude Code and Codex. Zero means none; omission means unavailable. Claude uses task dispatch, launch, completion, stop and resume events from the current live process; Codex uses native parent relationships, live writer locks and unfinished turn events, including nested workers. It does not count linked child conversations or cloud workers. An unfinished native task may be waiting on a tool. Native logs that cannot be read leave the count unavailable. Worker event writes invalidate the cached list; process exits can take up to a minute to show. Positive counts keep an otherwise idle parent inworking, while a parent's unread question still takes priority.helperslists the agents this conversation started that are no rows of their own and still work, each{tool, id, title, kind?, reply?, state, updatedAt}. They are its native Claude Code or Codex subagents, and thecodex execruns a local Claude Code session started. A helper that finished is not listed.stateis alwaysworking.kindis the agent type the tool gives, such asExplore.titleis empty when the tool gave none or it may hold a credential.replyis a Claude Code subagent's latest message, as one line like a row'sreply; it is read from the last 256 KB of the subagent's transcript, and a message to the subagent after it, such as a teammate's, keeps it. It is left out before the subagent wrote one, when it may hold a credential, or when its latest message is further back than that. Omitted when none works, or when the states cannot be read.- A Claude Code subagent comes from the session's
subagentsfolder and the meta file Claude Code writes beside each one. It is listed while the live process's task events say it works. A session no process runs lists none. It has no route of its own: open its conversation, with itsidashelper. - A Codex subagent is a direct child of a Codex thread. It is listed while a process holds its thread and its rollout says a turn runs. Open it with
POST /api/conversations/openand its owntoolandid. One in a terminal switches to the process that runs it, never a secondcodex resume. - A
codex execrun is linked to its Claude Code session only from the runningcodexprocess: the process holds the run's writer lock, and its environment holdsCLAUDE_CODE_SESSION_IDandCLAUDE_CODE_CHILD_SESSION=1, which Claude Code's Bash tool sets. The server reads the environment the kernel keeps for the process (kern.procargs2on macOS,/proc/<pid>/environon Linux), keeps only those two variables, and links nothing when either is missing or set twice. Every scan reads the link again; nothing is saved, so a run that ended is listed nowhere. Titles, folders and times are never used to guess. When process environments cannot be read, the Codex tool'snotesays so. POST /api/conversations/openopens a helper only when a conversation in the server's scope lists it.workingSubagentsstays as it was and does not countcodex execruns.
- A Claude Code subagent comes from the session's
unreadistrueonly on anactiverow whose latest write you have not seen: a terminal session resumed by hand after it closed with a reply. It stays until you open the chat or mark it read. It does not count towardneedsYou. An archived row is neverunread.deleteUnsupportedis set only on acompletedordormantrow thatPOST /api/conversations/deletecannot delete. It is the sentence that says why, such as a Codex thread or a cloud session.openingholds up to three lines of the first prompt, andpromptholds the latest one.parentis{tool, id}, the conversation this one continues. It is read from the lineContinues <tool>:<id>that starts the first prompt, whichconversations startwrites. That line is cut fromtitle,openingandprompt. The parent may be on no page: hidden, older than the page, of another tool than the filter, or deleted. Hiding, archiving or renaming a parent never changes its children.cloudis{id, link}, set on a local Claude Code session that Remote Control also shows on claude.ai: a live one, or one that closed while this server ran and whose cloud session wrote nothing more than two minutes after the session's last write. A restarted server sets it again only once the session runs; the cloud row it lists meanwhile is notunreadfor a write the local row showed, except a last reply that reached claude.ai after this server last read the list while the session ran and was never marked read. That cloud session is not listed as its own row.POST /api/conversations/openwith the cloudidopenslink. See Remote Control.replyis the agent's latest message since the latest prompt, as one line of at most 200 characters. When the agent asks a question, the line is the question. Otherwise it is the start of the message. It never holds tool calls, tool results or subagent output.- Only local Claude Code, Codex and Cursor conversations have a
reply. Cloud sessions have none. - Any of
title,opening,promptandreplythat may hold a credential is left out and named inwithheld, by the rule/api/views/sourceuses. The check reads the whole title and prompts, and the first 4 KB of a reply. titleis the name you chose withPOST /api/conversations/rename, when you chose one. Otherwise it is the tool's own title, or the first line of the first prompt.openis{kind, label, command?, link?}:focusswitches to the Terminal or Ghostty tab that runs it.labelthen names the app, such asSwitch to Ghostty. For a Codex thread that Codex's background service holds, the server looks for the Codex terminal that shows it.terminalrunscommandin a new tab of the app the session last ran in, Terminal or Ghostty. It never types into the old tab: a shell waiting inreadlooks the same as one at its prompt. With no tab remembered, it opens a new Terminal window. For a terminal sessionlabelsays it resumes, such asResume in GhosttyorResume in Terminal. Acursor-agentchat whose folder is not known has nocommand, becausecursor-agentresumes a chat only from the folder it started in; opening it says so.linkopens the editor extension, Cursor chat or desktop app it came from, or a cloud session in its browser or app. For an editor extension, the server first opens the conversation's folder in that editor, so the link reaches the window that holds it.
How closed sessions are detected
The server knows a terminal session is closed for local Claude Code and Codex sessions started in a terminal, and for cursor-agent chats, on macOS and Linux: a full read of ps or lsof finds no process that holds them, whatever their age. A session file Claude Code left behind after a crash, a kill or a reboot does not count when its process is gone or its pid now belongs to another process. A session stays open while any process holds it: in a detached tmux, screen or zellij session, stopped with Ctrl+Z, or after its tab closed. With two holders it closes when the last one ends.
A process that ends shows within a minute: the server reads processes again at most once a minute for a list that did not change.
Desktop app sessions, Claude chats, Cowork tasks, ChatGPT chats and cloud sessions stay active until you archive them here or in their app. Quitting the app archives none of them. A cloud session whose status says it works or waits, and that wrote nothing for 24 hours, no longer counts as working or waiting; it is active or unread, never archived by its age.
Editor panels and Claude Code background jobs keep the 24 hours: nothing reliable says when they close. So does every chat whose process read failed or cannot run: every chat on Windows, Codex and cursor-agent chats on a system without lsof, Codex threads from a version that keeps no thread-writer-locks folder, Claude Code sessions from a version that writes no sessions folder, and every chat in a scan where ps or lsof failed. So does a Codex lock or cursor-agent store that lsof cannot reach: under a folder it cannot read, or behind a link, since lsof skips both without saying so. So does every Claude Code session while a session file cannot be read and the process its name gives still runs; the Claude Code tool's note then names the file. A file whose process is gone, as a crash leaves it, is skipped. Such a failure never shows a session closed, so an unread reply there stays unread.
Process ids are read on this computer only. A conversation store shared with a container, WSL or another user account can name a process this computer cannot see, so that session may show closed while it runs elsewhere. The server does not detect another process namespace.
After you resume a closed session by hand, the reply it had while closed does not count as new: the server keeps the time of the last write it read while the session was closed, without marking it seen. The row is active with unread until you open it or mark it read. A later reply counts. The server can only keep what it read: a session closed and resumed between two reads, within the same minute, shows its old reply as new.
A Claude Code session that began in the desktop app or an editor, and was last used in a terminal, is a terminal session only while a terminal holds it. Once closed it opens where it began and follows that app's rule.
After /clear, an in-process /resume or a fork, the old session id is archived once no process holds it, and the new id stays hidden until it holds a prompt. This is tested only on the scanner's side: it assumes Claude Code points sessions/<pid>.json at the new id, which was not checked against Claude Code itself. A fork copies the old reply under the new id, so that reply can show under Needs you once more on the fork. What a real fork transcript looks like could not be confirmed, so nothing links the fork to its parent.
Codex thread locks and cursor-agent chat stores are checked with one lsof run over their folder, so a held thread of any age stays open and the cost does not grow with old threads.
The activity of a loaded local Codex thread is working during an unfinished turn. It is inferred to be waiting after five minutes without a rollout write, which makes the state blocked until you see it. A long-running command can also meet that threshold. Such a row carries quietSince, shown as "No activity for 7m".
Marks, cloud sessions and refresh
Marks:
seenAtandcompletedAtare your marks, when set.needsYoucounts the blocked and unread conversations of every age and tool the server lists, whatever the page or the search.- The marks live in
conversation-marks.jsonin theagnostic-aifolder of your user configuration folder. The file holds tool names, ids, times, the names you chose, the folder of each store and where each conversation's own file sits, never conversation text. A Claude Code project folder's name spells the folder the session ran in, and a Codex rollout outsideCODEX_HOMEis kept as a full path. - The first read starts the file, and what was written before it counts as seen.
- An older
servethat still runs after an upgrade drops the chosen names when it rewrites the file. Restart it, and the companion, after you upgrade. - A read clears a completion or a hiding once a later message overtook it or the conversation started working. The entry keeps its seen time and chosen name. After a new message the conversation is unread. After work that wrote nothing it is active again when the work ends.
marksNotesays why the file could not be read or written. Rows then carry no marks.- A chat its store no longer holds leaves the list on the next read. A Claude chat is the exception: it shows under Archived for a while, as the companion list page says.
- Its marks are removed once full reads of its store have missed it for 30 days, but only for a store the server reads in full: Claude Code transcripts, Codex threads and
cursor-agentchats. The 30 days start at the first full read without the chat. A pause of more than 8 days between two such reads, such as a computer that was off, starts them again, so one read after a month away removes nothing. A pause of 7 days or less never does. A server that reads a store less often than every 8 days never removes its marks. The server saves the missing marks of one store together, at most once a day. A read that fails, is canceled, lists nothing, or cannot open a folder or a chat's store changes nothing. A chat that comes back starts the 30 days again. - Each mark keeps which store listed it, by a short name for its folder with links followed, and where its own transcript, rollout or chat folder sits there. A server that reads another store, such as one started from a terminal with another
CLAUDE_CONFIG_DIRorCODEX_HOMEthan the companion, never ages it. When the store's folder is gone and a full read of another store lists the chat, as after a home folder was renamed, the mark moves to that store. Two stores that both exist and hold the same chat, such as a copied folder, keep the first. Whether a store exists is judged at each read, so a store on a disk that is not mounted reads as gone: if another store holds a copy of the chat, the mark moves there and does not move back. A chat whose store moved and that is gone from the new one too keeps its marks for good, and so does a store whose folder still exists under its old path but that no server reads any more. Before a mark goes, the server checks that this file or folder is gone. When it is still there, as when Codex rebuilds its thread index, the mark stays and the 30 days start again. A mark whose file is not known stays. - Marks of Claude chats, Cowork tasks, ChatGPT chats, Cursor editor chats and cloud sessions stay. The Claude app keeps only the pages of its list you scrolled to, a cloud list is cut at a limit, and the ChatGPT list and Cursor's editor index are not known to hold every chat. Marks saved before this release stay too, until a full read lists their chat.
- A chat that returns after its marks went, restored from a backup or synced back, loses its chosen name and its completed and hidden marks, and shows as unread.
- The file keeps fields this server does not know, so a newer server's fields survive its writes. An older server drops the store and missing times when it rewrites the file. For a listed chat that only starts the 30 days again. A chat already missing then can never be tied to its store again, so its marks stay for good.
Cloud sessions and refresh:
- On a server started with
--cloud-sessions, Claude Code cloud sessions and Codex cloud threads are listed too, withappcloud.cloudNotesays why they are missing when they could not be read. A machine where no one signed in to Codex has no Codex cloud threads, so that gets no note; a Codex sign-in with an API key instead of a ChatGPT login does. - When the ChatGPT desktop app is installed, its chats are listed as the tool
chatgptwithappchat, read from the chat list the app keeps in$CODEX_HOME/sqlite/codex.db, with no network call and no flag. A project server lists none. Without the app thechatgpttool is left out. - Claude chats (
appchat) and Cowork tasks (appcowork) are listed under Claude Code, from what the Claude desktop app keeps on this computer. The server reads only the lists the app last fetched, never a chat's messages, and makes no network call. A chat you have not opened in the app since claude.ai changed it may be missing or out of date. These rows open in the Claude app and cannot be deleted from here. A project server lists no chats, because a chat names no folder. It lists a Cowork task whose folder is inside the project. When the app's lists cannot be read, the Claude Code tool'snotesays so and none of these rows are listed; the server reads them again after the app's next write. - Codex and Cursor chats are read again only when their files change, for at most a minute. One of them can show as open for up to a minute after its app quit.
- The reply has an
ETag. It changes when a chat or a mark changed, when the approvals settings or log changed, when a new minute began (a process that ended or a chat that went dormant shows no other way), or when the query differs. - Sent back as
If-None-Match, an unchanged list answers 304 with no body and reads no chat.
POST /api/conversations/open
Body: {tool, id, editor?, helper?} with Content-Type: application/json, from the server's own origin.
- Reopens a conversation the list holds along its
openroute and returns{opened, message, command?, helper?}. helperis theidof a Claude Code subagent the conversation lists inhelpers. Its conversation opens as without it. When it opened,messagekeeps what the open says and adds the subagent's name; for a terminal tab it also says to switch to it in the agent rows below the prompt. The reply'shelperis that subagent. A subagent the conversation does not list, such as one that finished, opens nothing:openedis false andmessagesays so. A companion sends an open withouthelperagain once to a server that refuses the field. A Codex subagent opens with its owntoolandidinstead.
Open details, results and status codes
- For a
focusroute,openedis true only when the session's own tab came to the front. A running session is never started a second time. openedis false when the app came forward but its tab could not be chosen (Warp, or an editor's terminal), when Codex does not say which of its sessions shows the thread, when no terminal shows a running session, when the system cannot open a terminal, or when macOS refuses Automation access.messagesays where the session runs.command, when set, resumes the session by hand. A Claude Code or Codex session that still runs in a terminal gets none, because running it would start a second copy.- Not supported yet: iTerm2, tmux, WezTerm, kitty and Warp. For their sessions the app comes forward, or
messagenames the terminal device. - The route comes from the server's own scan, never from the request.
- macOS asks once for Automation access to each app the server controls: Terminal and Ghostty. The prompt names the companion app, or the terminal that runs
agnostic-ai serve. - The tab each running session uses is kept in
conversation-tabs.json, beside the marks file: the app and the terminal device. It holds no conversation text. - A conversation that opened is marked seen, and a completion on it is taken back.
- A second open of the same conversation while one runs starts nothing: it waits for the first and returns the same reply. Opens of different conversations run side by side.
- While a list read runs, an open takes its row from the read before it, so it does not wait. A row that would resume a session waits for a fresh read instead: an ended terminal session, and any Claude Code session of the desktop app or an editor, which may run in a terminal since. Such an open can take as long as that read.
- An open may take up to 90 seconds to answer. When its caller left before that, the server logs whether it opened on its standard error, without the reason.
| Status | Meaning |
|---|---|
| 200 | {opened, message, command?, helper?}. opened says whether the chat came to the front. |
| 404 | A conversation outside the list. |
| 400 | Any other field, or a helper that is not an agent id: 1 to 128 letters, digits, - or _. |
POST /api/conversations/send
Body: {tool, id, text, html?} with Content-Type: application/json, from the server's own origin.
Types text into a conversation's input, never pressing Enter, and returns {sent, message}.Send details, which chats get no text, and status codes
sent is true only when the text was typed into a live Terminal or Ghostty tab.html, the copied HTML, goes as Markdown instead when it holds links, tables, code blocks, headings or lists, and shows only words of text, in order. It keeps no attribute but short http, https and mailto link targets.message says so; plain text that cleaning would change, such as a trailing newline, is not pasted.POST /api/conversations/open does, and message says to paste with Cmd+V, such as for editor terminals.Status Meaning 200 {sent, message}A send that typed, and one that did not. 400 An unknown tool or any other field. 404 A conversation outside the list. 413 text is over 256 KB.
POST /api/conversations/mark
Body: {tool, id, as} with Content-Type: application/json, from the server's own origin.
as | Meaning |
|---|---|
seen | Read up to now. |
completed | Done until something new is written or it starts working. Also marks it seen. |
open | Takes a completion back. |
hidden | Left out of every list, search and count until something new is written or it starts working. The tool's own store keeps it. Also marks it seen. |
Mark status codes
| Status | Meaning |
|---|---|
| 204 | Marked. |
| 404 | A conversation outside the list. |
| 400 | Another as, or any other field. |
POST /api/conversations/rename
Body: {tool, id, title} with Content-Type: application/json, from the server's own origin.
Renames a conversation in its own tool first, then saves the name for every server that shares the marks file. When the tool does not take the name, the reply is Rename details and status codes
title as the conversation's name in the marks file. Every server that shares the file shows it and finds it in a search. A name the tool did not take is not saved.Status Meaning 204 The tool and the marks file both have the name. 404 A conversation outside the list. 400 An empty name, a name longer than 120 characters, a name that may hold a credential, or any other field. 409 Another rename of the same conversation runs, on this server or another one that shares the marks file. Nothing changes. 501 This kind of conversation cannot be renamed yet. 503 The program the tool needs is not installed, such as codex or sqlite3.403 The tool's sign-in is missing or expired. 409 A running program holds the conversation and would write the old name back. 502 The tool refused the name, did not answer in time, or keeps the conversation in a way this version does not know. {"error": "..."} with a sentence for the person that names the tool and what to do. What the tool said goes to the server's standard error only.
POST /api/conversations/delete
Body: {tool, id} with Content-Type: application/json, from the server's own origin.
Deletes one conversation under Archived from this machine for good. Only a local Claude Code session can be deleted, and only when all of these hold:
- Its
stateiscompletedordormant, read from a fresh scan. - No Claude Code process or background job holds it. The server asks again right before it removes anything, and once more before the transcript.
- None of its files was written at or after the moment it was archived. For
completedthat is your archive mark: archiving it again makes a new mark. Fordormantit is the moment the server read the row for this request, so a write in that second or later is refused. - Its session id names exactly one transcript.
What delete removes, what stays, status codes and limits
What it removes, each only when its name is exactly the session id:
projects/<project>/<id>/: subagent transcripts, saved tool output and the chosen title.file-history/<id>/: file backups for undo.session-env/<id>/: hook environment.uploads/<id>/: images pasted into the session.projects/<project>/<id>.jsonl: the transcript, last, so a failure leaves the row listed and the delete can be retried.- Its marks and its remembered terminal tab.
What stays:
history.jsonl: Claude Code's prompt history, one file shared by every session.projects/<project>/memory/: project memory, shared by every session of the project.tasks/session-<prefix>/andtelemetry/files: named after part of the id, or after more than the id, so the server cannot prove they belong to this session alone.
A location that is a link, or that holds a link, is refused, since the data it points to would stay.
Accepted limits:
- A session that starts in the moment between the last check and the removal is not seen.
- A forked session may still point at saved tool output under its parent's
projects/<project>/<parent id>/tool-results/. Deleting the parent removes that output.
| Status | Meaning |
|---|---|
| 200 | {deleted: true, freedBytes?, note?}, sent only once the transcript is gone. freedBytes is what its files held. note says what could not be tidied after the data went, such as its entry in the marks file. |
| 400 | for an unknown tool or any other field. |
| 404 | for a conversation outside the list, or one you hid. |
| 409 | {error, reason} with reason not-archived (not completed or dormant now), running (a process or job holds it) or changed (a file was written at or after the moment it was archived). |
| 422 | {error, reason: "unsupported"}: Codex threads (Codex deletes a thread even while it is open, so close it first and run codex delete <id> yourself), Cursor editor chats (Cursor keeps them all in one shared database), cursor-agent chats, cloud sessions, and any session on Windows, where the server cannot tell whether a session still runs. Also a session whose files the server cannot verify: its id is in two project folders, or its transcript or one of its locations is not a regular file or folder, such as a link. |
| 500 | {error, reason: "failed", removed?, remaining?}. Nothing was removed when the marks could not be locked or read, the files could not be measured, or the process list could not be read. When a removal began and then stopped, removed and remaining list what is gone and what is still on disk: a removal failed, or the session started running before its transcript went. The marks are kept. |
error is always a complete sentence.