> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperspell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex

> Save local work notes, capture activity in Hyperspell, and continue recent work in Codex.

Connect Codex to Hyperspell through [MCP](/agents/mcp) or the
[command line tool](/agents/cli). 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](https://app.hyperspell.com/plugins/hyperspell-codex-activity-latest.zip),
extract it to a directory you will keep, and run:

```bash theme={null}
codex plugin marketplace add /absolute/path/to/extracted-marketplace
codex plugin add hyperspell-activity@hyperspell-codex
```

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:

```text theme={null}
Use $hyperspell-activity to configure capture suggest and handoff on,
using my hyperspell-context MCP server.
```

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](/integrations/all/vault#read-or-share-an-earlier-capture) for the
tools, permissions and deletion behavior.

See [one fix across two sessions](/integrations/all/vault#example-one-fix-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](/agents/cli#review-session-sharing-from-the-terminal)
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:

```bash theme={null}
codex plugin remove hyperspell-activity@hyperspell-codex
```

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](/agents/cursor). The clients share
capture safeguards but keep separate local notes and installation settings.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.