Skip to main content
Connect Codex to Hyperspell through MCP or the command line tool. The optional native Hyperspell Activity plugin adds local work notes, opted-in activity capture and explicit session handoff. Connecting MCP alone does not install this plugin.

​
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. Download the Codex activity marketplace ZIP, extract it to a directory you will keep, and run:
Start a new conversation and review and trust the plugin’s hooks when prompted. Managed organization policy may restrict hooks. The plugin uses your existing Hyperspell MCP connection and does not install credentials.

​
Enable capture and handoff

Capture and handoff start off. Ask Codex:
Replace the server name if your connection uses another name. With a personal credential, suggest keeps each entry yours until you approve sharing through your agent or the Hyperspell Inbox. A workspace credential makes entries company-visible. personal requires a personal credential; shared requests immediate sharing where allowed.

​
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 MCP list_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. An entry saved as personal has no pending request. 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:
If a capture fails, inspect 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.