~/.codex/AGENTS.md. Its hyperspell activity status command describes the
Claude Code activity plugin. Check Codex itself with codex plugin list; if
hyperspell-activity@hyperspell-codex is absent, Codex session capture is not
installed. Codex can still call the MCP log_activity tool for a single summary.
Saved activity entries describe past sessions; use codex plugin list for the
current installation state on this machine.
Install the activity plugin
Use current Codex with local command hooks and Python 3.11 or later. The plugin is tested with CLI 0.163.0. In Codex Desktop, use a local session with Python available; cloud-orchestrated ChatGPT Work does not run these local plugin hooks. Activity 0.1.6 and later need the guardedlog_activity_if_current tool on the
connected brain. If Codex uses the local hyperbrain-mcp connector installed by
the daemon, it also needs hyperspell-brain[mcp] 0.10.1 or later. Once that CLI
release is published, close applications using the connector and run:
hyperbrain update
alone cannot cross a recorded >=0.9,<0.10 bound. If your connector instead runs
through uvx, set its --from argument to hyperspell-brain[mcp]>=0.10.1,<0.11.
A hosted /mcp connection uses the server’s catalog and does not need this local
CLI upgrade. After reopening Codex, verify log_activity_if_current is available
before enabling capture; the older log_activity tool is not a substitute.
Download the Codex activity marketplace ZIP,
extract it to a directory you will keep, and run:
No such file or directory.
Run codex plugin list to confirm it is installed, then ask
$hyperspell-activity status in the new conversation to confirm its hooks are
running. A working MCP connection alone does not verify the hooks.
Version 0.1.1 and later use the bundled local tool for status, capture and
handoff; the default Codex shell sandbox needs no extra writable root. If the
tool is missing, update the plugin and start a new conversation.
With version 0.1.0, these commands may report unavailable local storage under
workspace-write. Until you can upgrade, start one Codex session with access to
the plugin’s private data directory:
status in that new conversation.
Enable capture and handoff
Capture and handoff start off. Ask Codex:suggest or personal. These
settings create no review request themselves. A sharing rule you turned on,
including a metadata rule, can still
match one, and that match waits in your Inbox. shared requests immediate sharing where allowed. A
workspace credential makes entries company-visible, and personal requires a
personal credential.
Capture and continue work
After a working turn, the plugin saves a small local note. Use$hyperspell-activity now to capture a summary in the brain, and
$hyperspell-activity status to check the saved entry ID and any error.
If local storage is busy, work notes remain queued across process exits and recover
on the next hook or status command. A full queue or unavailable disk reports that
new work could not be saved; existing queued work is preserved.
The remote entry lives in the vault as a normal searchable memory containing the
work summary, decisions, next steps and links. Later captures update the saved
entry. The plugin does not upload the full transcript or tool outputs; its local
handoff notes remain on this machine.
What the vault keeps
The plugin groups work by repository and branch and reuses the saved entry ID across sessions. It is one evolving memory per piece of work, not necessarily one per conversation. Another machine without the saved ID can create a separate entry. Claude and Codex keep separate local notes. Each capture asks the model for a title, a two-to-five-sentence summary, decisions, next steps, and links. The sentence count is a prompt target, not a fixed storage quota. Later captures revise the memory, carrying forward earlier outcomes unless the current work supersedes them. The vault lets you search and read the current summary. An updated server also keeps private checkpoints when captured content changes, so an agent can inspect earlier decisions and links on demand. Existing entries start with the content still available at their next revision; overwritten older versions are not recovered. Prompts, replies, tool results, and files are not uploaded in full. Summarization can omit details; the vault cannot reproduce the full session. Codex’s own conversation history is separate. Sharing grants access to this evolving summary, including later revisions. It does not give colleagues the underlying Codex conversation. Read the entry before sharing, since a summary can still include sensitive details from the work. Private checkpoints do not inherit that share. To share an earlier capture, ask Codex to preview it and prepare a separate copy for sharing review. See work history for the tools, permissions and deletion behavior. See one fix across two sessions for example saved entries, how the second capture changes the first, and what a teammate can read after you share.Manage sharing from Codex
Ask: “Show my pending session entries, read the ones about this branch, and share the handoff fix. Keep the other test entry private.” Codex can perform authorized decisions without opening the dashboard. This uses hosted MCPlist_sharing_requests, get_memory, and
decide_sharing_request. It requires a personal credential and a server offering
the sharing tools. The updated CLI
offers the same operations when those tools are unavailable. Installing the
activity plugin alone does not update the server or CLI.
keep_private dismisses a pending request. It does not retract an existing share
or reverse a previous decision. Setting capture to personal or off also leaves
existing access unchanged. A new entry is pending only when a sharing rule you
turned on matches it.
Capture, sharing review and local handoff are independent controls.
Continue saved work
In a new conversation, use$hyperspell-activity continue. Select a numbered
note from the list. Codex receives the historical context and continues that work;
it does not switch your Git branch. The status shows the resume count and attached
characters. Notes are local to this machine and separate from Claude’s notes.
Automatic capture requests one continuation at a turn boundary after pending work
has been quiet for 15 minutes, or after compaction. It uses the active conversation
and normal MCP permissions. It does not wake an idle model or guarantee a write
at exit. Use now before clearing or closing when the brain must be current.
Pause or remove
Use$hyperspell-activity pause or resume for this session’s brain writes.
Configure share off to disable captures while keeping local notes. Disable the
plugin in /plugins to stop all hooks, or uninstall it with:
status and the MCP result before retrying. A pending
capture belongs to its originating session; ask to cancel that reservation by its
session ID only when you intend to release it. Cancellation does not undo a remote
write. Existing brain entries remain after uninstalling the plugin.
For Cursor, use its separate native plugin. The clients share
capture safeguards but keep separate local notes and installation settings.