Visibility: public.
Claude Desktop extension: download
one-conv-cli.mcpb,
double-click it and click Install. It serves the cloud commands only
(ChatGPT, Claude Chat, Codex cloud, Cowork), and ships the credential helper
prebuilt so connect needs no developer tools.
Read and search your AI conversations from one CLI. Pull cloud conversations into a local history, or read sessions already saved by your coding tools.
Message any running agent session from any other, on this machine or another one, and read or continue a session wherever it ran.
| Namespace | Sources |
|---|---|
cloud |
ChatGPT, Claude Chat, Codex cloud, Cowork cloud |
local |
Claude Code, Codex CLI, Cursor (IDE and CLI), Oh My Pi, on this machine and every machine syncing to the archive |
live |
Messages between running agent sessions, names, and the relay that links machines |
Cloud conversations are addressed by ID or title. Local sessions are grouped by the project where the agent ran.
You need Python 3.12+ and uv. The launcher declares its dependencies inline; uv resolves them on first use.
Clone this repository and run ./bin/one-conv --help. The CLI is
one_conv_cli.py; bin/one-conv and bin/agent-conv are
symlinks to it, and bin/one-conv.cmd launches it on Windows. Add the
checkout's bin directory to your PATH to use the shorter one-conv command
shown below.
The repository also includes an agent skill. Install the checkout as a skill in your agent runtime to give it the same launcher and usage guide.
Local history readers use files on your machine. Browser-session discovery and login currently target macOS. Initial Keychain setup requires Apple's command-line developer tools to build the native credential helper.
one-conv reads the provider logins of your everyday browser (Chrome, Arc, Brave, Edge, or Chromium). To add any other account, sign in to it with:
one-conv cloud claude connect --loginThis opens a browser window on a profile only one-conv uses (browser-profiles/
in the one-conv state folder, private to you), so each account you add this way
has a login of its own. Sign in to as many accounts as you like, one window
each, and sign in and out freely in your everyday browser: signing out there
never disconnects them. When one of these logins expires, accounts names it;
renew it with connect --login --profile claude-1. Opening the page does not
verify the login.
Every session one-conv verifies is also saved in a private session vault
(sessions/ in the one-conv state folder), so an everyday-browser account stays
available after you switch that browser to another account, until its session
expires or you sign out of it on the provider's site.
Authorize one-conv to read that browser's session, then verify account access:
one-conv cloud claude connect --browser chrome
one-conv cloud claude accountsThe authorization command may show a macOS Keychain dialog for
credential-helper-v1. Choose Always Allow to let the persistent helper
reuse this authorization. Normal reads, discovery, and pulls never open
password dialogs.
accounts lists sessions the CLI can actually access. An empty result means
no account is accessible, not that its conversation history is empty.
Replace claude with chatgpt, codex, or cowork for the other products.
Claude Chat and Cowork use the Claude login; ChatGPT and Codex use the OpenAI
login. Keychain authorization for a browser is shared across these products.
Refresh accessible accounts across all cloud products and list conversations:
one-conv cloud chats --refreshEach row shows activity time, source, account label, short conversation ID,
turn count, and title. Copy the ID in square brackets into read:
one-conv cloud read IDReplace ID with the displayed value, or use a unique title. Ambiguous matches
require a more specific ID. cloud chat ID and cloud thread ID are aliases.
The default reader shows conversation text. Claude Chat and Cowork tool calls,
tool results, and thinking blocks are hidden. --raw exposes additional
retained details; tool calls and results are summarized by the renderer.
| Reading option | Effect |
|---|---|
--limit 20 |
Show the last 20 visible turns; 0 shows all |
--no-mark-read |
Preserve the unread marker |
--json |
Emit structured data on stdout |
--refresh |
Refresh accessible accounts before reading saved history |
The ● marker means unread in one-conv, independently of the provider's
read state. Reading marks the conversation read unless --no-mark-read is
set. A later cache-file update can make it unread again. ? tok means a token
count is unavailable for that source.
Cloud readers use saved history unless you explicitly request a refresh. They announce the mode on stderr, keeping JSON stdout suitable for pipelines.
| Command | Network behavior |
|---|---|
cloud chats |
List saved conversations; no fetch |
cloud read ID |
Read a saved conversation; no fetch |
cloud search TEXT |
Search saved message text; no fetch |
cloud find TEXT |
Find saved conversations by title; no fetch |
cloud chats --refresh |
Refresh accessible accounts, then list |
cloud read ID --refresh |
Refresh accessible accounts, then read the saved conversation |
cloud claude pull |
Fetch Claude history into the cache |
cloud claude accounts |
Contact Claude to discover accessible browser accounts |
cloud cached-accounts |
Show saved account groups and counts; no fetch |
Refresh fetches up to 100 conversations per account and product. Results
can also include older saved conversations and accounts that were not
refreshed. This is a bounded update, not a guarantee that every cached
conversation is current. Reading an older ID with --refresh does not fetch
that specific conversation if it falls outside the batch.
Global refresh reports inaccessible sources as skipped. If a discovered account's pull fails, it attempts the other accounts, preserves successful pulls, and exits with an error before displaying results. It does not silently substitute old results for a failed refresh.
Use a product's pull --limit to request a larger batch, up to 10,000
conversations. Pulls are resumable: conversations whose cached copy is complete
and current are not read again, and a conversation listed twice while paging
is read once. Pulls run from the CLI wait out provider throttling (ChatGPT
spaces out conversation reads) instead of failing; MCP refreshes keep short
timeouts. The sync report distinguishes ready, partial, and error.
partial can mean the batch limit was reached or a transcript was incomplete.
A complete Cowork event snapshot does not mean the task itself has finished.
Discover account selectors before an explicit pull:
one-conv cloud claude accounts --json
one-conv cloud claude pull --account ACCOUNT --limit 1000Replace ACCOUNT with a selector from discovery. OpenAI accepts an exact email
or account ID. Claude accepts an organization name or ID, or the full account
ID. Ambiguous selectors require the full ID. A product's pull automatically
selects the account when only one is accessible.
For one product, use cloud chatgpt, cloud claude, cloud codex, or
cloud cowork. Each has connect, accounts, pull, chats, read,
thread, search, find, and unread. Product readers accept --refresh.
Shared commands accept --source with the stored names chatgpt,
claude-chat, codex-cloud, or cowork-cloud. On cloud chats --refresh,
this restricts both fetching and listing.
chats --limit controls displayed rows, not the refresh batch size. It defaults
to 30; --limit 0 lists all saved conversations.
Local commands organize sessions by project:
one-conv local chats
one-conv local read PROJECT
one-conv local thread PROJECT
one-conv local search TEXT
one-conv local search 'bridge reconnect' --ranked
one-conv local search 'agent dies when the websocket drops' --semanticlocal search matches TEXT as one exact substring, newest first. --ranked matches
turns holding every word of TEXT in any order, each as a word or the start of one,
and orders them by BM25 relevance. It reads a full-text index kept in the state
directory ($ONE_CONV_SEARCH_INDEX overrides its path). Each search re-indexes
only the sessions that changed, so the first ranked search indexes all history
once and later ones skip parsing. Archived conversations join the index the
first time the hub lists them for a query.
--semantic also finds turns that share no word with TEXT. Each turn gets an
embedding from potion-retrieval-32M,
a static model run locally on the CPU with no GPU or ML framework: the CLI downloads
it once into the state directory (about 130 MB, pinned by revision and checksum;
$ONE_CONV_SEMANTIC_MODEL points to another copy). Turns rank by reciprocal rank
fusion of their similarity to TEXT and BM25 over turns holding any word of TEXT.
The first semantic search embeds every indexed turn, a few thousand per second;
later ones embed only new turns. Archived conversations join when the hub lists
them for any word of TEXT, and stay searchable once indexed.
Replace PROJECT with a name from the listing. local read lists its sessions;
local thread reads the newest one. Choose another with --session ID or
--nth 2, or use local read PROJECT --expand to read all of them.
--source claude|codex|cursor|cursor-cli|omp|corpus narrows the source: cursor (or
cursor-ide) is the Cursor IDE's chats, cursor-cli those of Cursor's terminal agent, the
agent command, which keeps them under ~/.cursor/chats. corpus is sessions imported
into the archive from the retired shared corpus. Local readers never
discover cloud accounts.
For agent workflows, local fork starts a new Claude Code thread from an
existing one, local send continues a closed Claude Code thread (it refuses a
thread that is open in a running session; use live send for that), and local port
seeds a new Claude Code or Codex session from another conversation. These
commands default to dry-run and require --yes to launch an agent. Execution
can modify files or use tools.
local skill-usage reports recorded Claude Code skill invocations. Each command's --help describes its options.
Normalized cloud transcripts live under ~/.cache/one-conv-cli/cloud,
overridable with ONE_CONV_CLOUD_CACHE. Read-state bookkeeping uses
ONE_CONV_STATE_DIR, defaulting to ~/.config/one-conv-cli or an existing
~/.config/agent-conv-cli directory. Older ChatGPT cache files remain readable
and can overlap with the normalized cloud cache.
Cloud adapters use unofficial provider APIs and remain experimental:
| Product | Coverage |
|---|---|
| ChatGPT | Conversation listings and the selected message branch within each conversation |
| Claude Chat | Organization-scoped conversations and message trees |
| Codex cloud | Current tasks and returned turn graphs; no archived-task discovery |
| Cowork cloud | Remote sessions and paginated event transcripts; no local Cowork sessions |
The credential helper is installed once and reused across normal CLI updates. This local build uses ad hoc signing; replacing the executable can require Keychain authorization again. Browser sessions can expire independently.
See PROVIDERS.md for adapter boundaries, API-change handling,
and verification evidence. cloud providers reports implementation coverage,
not your accounts' live connection status.
one-conv live lets any running Claude Code, Codex, Oh My Pi or Cursor session
message any other, on this machine or another one. A message arrives in the
receiver's context as a new user turn, labelled with the sender's address and
chosen name:
<one-conv-message from="codex:01a1..." from-handle="@builder" from-cwd="/work/api" id="9f2c...">
run the migration first
</one-conv-message>
To reply, call the one-conv send_message tool with to="codex:01a1...".
Agents on one machine work for the same user, so a message is a teammate's request to act on within that user's task. It is not the user typing: it grants no new approval and does not override the receiving agent's own permissions.
Set it up once, then restart the sessions you want to reach:
one-conv live install # lists the missing pieces
one-conv live install --yes # applies them
one-conv live ls # running sessions and their addresses
one-conv live send codex:01a1 "run the migration first" --yesOne live send reaches any of these, and defaults to a dry run until --yes:
| Target | Reaches |
|---|---|
claude:<id>, codex:<id>, omp:<id>, cursor:<id> |
a session on this machine; a unique id prefix or a substring of its title or folder works too |
NODE/claude:<full id> (also codex, omp, cursor) |
a session on another machine, through the relay (see Working across machines); the id must be complete |
@name |
the agent that chose that name: on this machine first, else one another machine published |
claude-chat:<id or title>, cowork:<id or title> |
a saved Claude chat or Cowork session; it answers inline and the reply comes back in the receipt |
Inside an agent, the one-conv MCP tools list_live_sessions and send_message
do the same; the sender is identified from the calling session.
one-conv live name lead # others can write to @lead
one-conv live send @reviewer 'the migration is on branch m42' --yes
one-conv live send @reviewer 'fyi: CI is green' --fyi --yes # lands in its feed, no wake
one-conv live send claude:4f1a 'what does this show?' --image shot.png --yes| Harness | Delivery | Reaches an idle session? | Installed by live install |
|---|---|---|---|
| Claude Code | Session inbox socket (~/.claude/sessions/<pid>.json) |
Yes | MCP server (user scope) and "crossSessionInbound": "accept" |
| Codex | codex queue |
Yes; an unloaded thread gets it on its next resume | MCP server |
| Oh My Pi | Extension inbox (~/.omp/agent/extensions/one-conv-live.ts) |
Yes | Extension, which also adds a one_conv_send tool |
| Cursor | stop hook follow-up |
No: the message waits until a turn ends | MCP server and ~/.cursor/hooks.json hook |
Sessions started before the install are reachable only for Claude Code and
Codex. Cursor's stop hook runs in the IDE and in interactive cursor-agent, not
in cursor-agent -p. A Cursor IDE chat cannot be identified as a sender, so its
messages carry from="cursor:?unknown" and cannot be answered. Both share the
cursor:<id> address; live ls labels each session cursor-cli (a chat the
agent command stored under ~/.cursor/chats) or cursor-ide.
one-conv live name reviewer # others can now write to @reviewer
one-conv live names # names on this machine and their addresses
one-conv live whoami # the calling session, as others address itA name is an alias: messages route and reply by address, so renaming never
breaks a reply. A name held by a running session is refused; one held by a
stopped session is taken only with --replace. The bridge publishes names with
the sessions, so @name reaches a session on another machine; a name already
taken on another machine is not published. The MCP tool set_name does the same
from inside an agent.
crossSessionInbound: "accept" lets any local process running as you inject
user turns into every Claude Code session, including sessions that skip
permission prompts; without it, those sessions hold each message for approval.
The relay is messaging between trusted local processes of one user, not an
authenticated channel. A sender that is not an agent session is labelled user
from an interactive terminal and unknown otherwise; a message from a human
asks the receiver to answer in its own conversation.
These labels are self-reported, not proof of identity or of your approval:
--from must name a running session, but any local process can name any of
them. Message bodies cannot open or close an envelope of their own. A
sender may send at most 10 messages to one target per 5 minutes; this throttles
two agents that keep replying to each other but does not end the exchange. Live state lives in
~/.config/agent-conv-cli/live (override with ONE_CONV_LIVE_DIR). After a
delivery between two identified sessions, peers.json there records the pair
(both addresses sorted, joined by a space) with the time of its last exchange;
if that record cannot be written, the send still reports delivered with a warning.
The record only chooses what local feed follows by default; it grants no
permission and is not evidence of anyone's approval.
Agents on different machines reach each other through a relay. Each machine runs
one bridge, live serve, which needs no inbound network access. Agents never
need to know where another one runs beyond its address, NODE/harness:id with
the full id, as live serve publishes it, or its @name.
The relay is one process that serves the message API and the conversation archive every bridge syncs to, both behind the same node tokens. On the machine that hosts it (it binds to localhost by default):
(umask 077; uv run scripts/live-hub.py token add laptop --db relay.db > laptop.token) # one per machine, private
uv run scripts/live-hub.py serve --db relay.db # 127.0.0.1:8789; the archive goes to archive.db beside itOn each machine, with the token issued to it:
one-conv live serve --hub ssh://me@relay-box --node laptop --token-stdin < laptop.token
one-conv live serve --hub https://relay.example.com --node ci-runner --token-stdin < ci-runner.token
one-conv live serve --status
one-conv live serve --install --yes # launchd or systemd: start on its own, restart after a crash
one-conv live send ci-runner/codex:019a0c5e-7b1d-7f30-9c4e-2d8a5b6f1e03 'rerun the flaky test' --yes
one-conv local thread ci-runner/codex:019a0c5e-7b1d-7f30-9c4e-2d8a5b6f1e03 # read it from here, and continue it--install --yeshands the bridge to launchd on a Mac, or to a systemd user unit (one-conv-bridge.service) on Linux, once its settings are saved: it starts at every login (at boot on Linux when lingering is on) and restarts after a crash, while a clean stop (--stop) keeps it stopped.--uninstall --yesremoves it.ssh://opensssh -N -Lto the relay's port, non-interactively and only to a host whose key is already known;https://verifies the certificate; plainhttp://is accepted only to a loopback address (127.0.0.1, ::1). The token travels only in a request header, no redirect is followed, and no proxy from the environment is used. Throughssh://,live senduses the forwarded port only while the bridge's own ssh process holds it; once the bridge has stopped, sends are queued instead.- The bridge publishes this machine's live sessions every 15 seconds and
receives messages addressed to them, handing each to that session's own
harness as a local send would. On the Cloudflare Worker relay messages are
pushed over a WebSocket (
/v1/stream), which lets the relay sleep between messages; the bridge redials a dropped one with backoff, and the relay pushes again whatever is still undelivered. The self-hosted Python relay (scripts/live-hub.py, also behindssh://) has no stream, so there the bridge long-polls/v1/inboxinstead. A message for a session that is not live here is refused, not queued. An attached image is uploaded to the relay and saved on the receiving machine, whose agent gets its path. - While the relay is unreachable,
live sendqueues the message and the bridge posts it later under the same id, so the relay never stores it twice. - Each message is recorded on the receiving machine before its harness is
called. A message the relay hands out again is not delivered again. If the
bridge stopped in the middle of a delivery, the sender sees
unconfirmedrather than a second prompt.live status ID, with the id the send printed, shows what the recipient's harness did (accepted,refusedorunconfirmed, orstoreduntil it is handed over), not whether the agent has read it yet. - The bridge also syncs this machine's agent histories to the relay's archive
every minute (Cursor IDE chats every 15 minutes), under its node name. Any
machine then reads them as
NODE/harness:idwithlocal thread,local searchor the MCPread_conversation, so an agent elsewhere can pick up a session where it stopped. A node uploads only under its own name. - A machine's token vouches for the sessions its bridge publishes, not for each
process on that machine.
token revoke NODEcuts one machine off.
Any agent can read another agent's thread with one-conv local thread, so an
exchange can be reconstructed from the transcripts. A relayed message lands as
a user turn in the receiver's thread. In the sender's thread it exists only
as a tool call, which local thread hides unless --raw is given, so a
reference must point at the receiver's thread.
- Start each message with a header line such as
to: codex:01a1 cc: claude:6c51 re: migration order, so either side of the exchange can be rebuilt. - Reference instead of copying when the content is long, when a recipient may
not need it, or when several agents follow the same exchange. Make the pointer
precise: the receiver's address, the send time, and a quoted phrase to search
for, for example
replied to claude:6c51 at 23:19Z, find it with one-conv local search "Round 2 review" --source claude. Choose a phrase distinctive enough that later messages quoting it are unlikely.local threadselects only the last N turns, so "see its latest turn" goes stale as soon as the receiver takes another turn. - Copy instead when the content is short, when the recipient must act on the exact wording (a decision, an approval scope, a command), or when the recipient cannot read the thread (another machine, a cloud session, a Cursor IDE chat).
- A reference is not delivery: if someone must act, send them a message.
- End exchanges once. A pushed message wakes its receiver, so informational
notices go with
live send --fyi, which lands in the receiver'slocal feedwithout waking it. A result someone is waiting on is still pushed, with--no-reply, because an idle agent does not run its feed. Nobody answers a message markedreply="none", and the last message that needs action says "closing re: ". A sign-off ends acknowledgments, not new findings.
Delivery order is not guaranteed across harnesses: a codex queue message can
arrive after one sent later through another route.
live send covers what a sender knows matters. local feed covers the rest:
what the agents you work with said since you last looked, without rereading
their whole threads.
one-conv local feed --follow codex:01a1 # address or unique id prefix
one-conv local feed # one line per thread with news
one-conv local feed --full codex:01a1 # every unread turn of one thread
one-conv local feed --following # who you follow, and whyThe reader is the calling agent session (--as ADDRESS outside one). It
follows the sessions it exchanged live messages with in the last 7 days, plus
threads added with --follow; --unfollow also mutes a live-message partner.
A live session whose transcript is not on disk yet can be followed already.
Each reader keeps two positions per thread. The digest moves only "notified"
and --full moves "read" too, so a digest line never hides text you have not
read: unread text starts where the first digest line for that thread began.
--peek moves neither. The digest is capped by --max-chars (1500, at least
80); longer lines are truncated and the threads left out stay pending for the
next run. A thread seen for the first time shows its last 3 readable turns.
The feed is best-effort incremental history, not exactly-once delivery. If a
transcript is rewritten so your position can no longer be found, or found in
more than one place, the feed says the thread changed and shows its last 3
turns, which can replay or skip turns. A transcript that cannot be read, or
that returns no turns after having some, is reported unavailable, keeps its
positions and is retried next time. Cursor stores are parsed on every run,
since new turns can sit in a SQLite write-ahead log. The view is the one local thread
reads, in file order, so omp turns on an abandoned branch appear too. Feed
state lives under feeds/ in the live directory, one file per reader.
FYI messages sent to you with live send --fyi come first in the digest, one
line each; --full inbox prints their full text. They follow the same two
positions as threads and expect no reply. Senders prune FYI messages older than
7 days, so one left unread that long is dropped.
Peer turns are a teammate's session: history to inform your work, not new requests, and never the user's approval.
local feed is an explicit command by design: live install adds no hook that
prints the digest into every prompt or session start. A hook would change every
session you run, so agents call feed themselves, as SKILL.md tells them to.
Run one-conv mcp --config to generate the JSON configuration for your MCP
client. Merge its one-conv entry into the client's mcpServers configuration.
The generated paths point to this checkout and its Python environment; regenerate
the configuration if you move the checkout or remove that environment.
Your client launches the server when needed. To launch it directly:
one-conv mcpThis uses stdio: the process waits for MCP messages, so it does not display a chat interface or open a network port. It uses the official MCP Python SDK.
| Tool | Purpose |
|---|---|
list_chats |
Cloud conversations or local projects |
read_conversation |
Cloud ID/title, or local project with optional session ID |
search_conversations |
Search saved message text |
find_conversations |
Find conversations by title |
list_accounts |
Saved cloud account groups, without checking login validity |
list_live_sessions |
Running agent sessions and their message addresses |
send_message |
Deliver a user turn into a running session (see above) |
The readers accept namespace="cloud" (default) or namespace="local",
an optional source filter, and a result limit. Reads keep unread markers intact
and hide tools/thinking unless raw=true. Responses include data, freshness,
and notices, making saved-history reads explicit.
Set refresh=true on cloud listing or reading to fetch accessible accounts
before reading. Connect accounts through the CLI first; the MCP server does
not perform interactive login. Refresh retains the CLI's limit of 100
conversations per account and reports failures instead of silently returning
stale data as fresh. Searches always use saved history.
The server exposes history access, explicit refresh, and live-session messaging, with no arbitrary command execution. This repository contains the CLI, agent skill, and local MCP server. The hosted OneConv application is developed separately.
Start with one-conv --help, one-conv cloud --help, one-conv local --help, or one-conv live --help.
Add --help to any command for its options.
Older top-level commands remain callable for existing scripts but are hidden
from root help. Their project-based behavior differs from the cloud namespace.
LEGACY_COMMANDS.md documents that interface, including the
older ChatGPT sync and asset-download workflow. Use cloud and local for new
integrations.
The Claude Desktop extension built from this repository keeps your data on your Mac and talks only to the service it connects to. Full policy: https://clementwalter.github.io/claude-extensions/privacy/
Each test file is a PEP 723 script with the same exact pins. Run the offline suite in parallel:
uv run --no-project --with-requirements tests/conftest.py python -m pytest -n auto tests