hero brain threads
The commands for saving a named checkpoint of work in a workspace, and for loading a saved checkpoint again.
What hero brain threads does
A thread is a named checkpoint of work in one workspace, with versions. These commands are for creating a thread, listing threads, saving a checkpoint as a new version, listing a thread's versions, and loading one version for Claude Code or Codex. Nothing saves by itself: a checkpoint is saved only when save runs.
- Use it when you want to see which threads exist, or work with a thread's saved checkpoints.
- Use something else when you want to see or add to your Brain (
hero brain), or enroll the agent identity threads need (hero identity). - Reads or changes:
list,historyandresumeread.createandsaveadd to your saved threads.
Every verb refuses with identity_not_enrolled until an agent identity is enrolled.
Synopsis for hero brain threads
hero brain threads create --title <title> (--workspace <path> | --workspace-id <id>) [--json]
hero brain threads list [--workspace-id <id>] [--limit <n>] [--json]
hero brain threads save --thread <id> --expected-version <n> --source-surface claude|codex --input <file>|- [--json]
hero brain threads history --thread <id> [--limit <n>] [--json]
hero brain threads resume --thread <id> [--version <n>] --target-surface claude|codex [--json]
With no verb, it refuses with brain threads needs a verb.
Subcommands of hero brain threads
| Subcommand | What it does | Reads or changes |
|---|---|---|
create | Creates a thread for one workspace. | Changes |
list | Lists saved threads without loading their content. | Reads |
save | Saves a checkpoint as a new version. A save based on an older version than the thread's current one is refused with checkpoint_conflict. | Changes |
history | Lists a thread's saved versions. | Reads |
resume | Loads one exact saved checkpoint for the agent you name. It brings back the checkpoint, not the conversation, your workspace files or your permissions. | Reads |
Arguments for hero brain threads
Every verb also takes --json.
| Verb | Argument | Type | Required | Default | What it does |
|---|---|---|---|---|---|
create | --title <title> | Text | Yes | None | The thread's title. |
create | --workspace <path> | Directory | One of the two | None | The workspace the thread belongs to. |
create | --workspace-id <id> | Workspace id | One of the two | None | An existing workspace, by its id. |
list | --workspace-id <id> | Workspace id | No | All workspaces | Lists only that workspace's threads. |
list, history | --limit <n> | Integer | No | 50 | How many rows to return. |
save, history, resume | --thread <id> | Thread id | Yes | None | The thread, as list prints it. |
save | --expected-version <n> | Integer, 0 or more | Yes | None | The version your save is based on. |
save | --source-surface claude|codex | Agent name | Yes | None | The agent the checkpoint came from. |
save | --input <file>|- | File, or - for standard input | Yes | None | The checkpoint, as JSON, at most 64 KiB. See Checkpoint format. |
resume | --version <n> | Integer | No | The latest | The exact version to load. |
resume | --target-surface claude|codex | Agent name | Yes | None | The agent the checkpoint is loaded for. |
Checkpoint format for save
A checkpoint is one JSON object with exactly these fields, all required. Lists can be empty. Each text entry is an object with text and provenance, which is user_explicit or agent_summary.
| Field | Holds |
|---|---|
schema | hero.brain.thread-checkpoint.v1 |
objective | What the work is for. |
constraints, decisions, unresolved_questions, blockers | Lists of text entries. |
completed_work | A list of claims, each linked to an artifact or reference. |
artifacts | Files in the workspace, by relative path and fingerprint. |
external_references | URLs, commits, pull requests or other references. |
recent_interaction_summary | A summary, with provenance agent_summary. |
next_action | What to do next. |
How hero brain threads works
Threads are kept by Ekamyth Agent OS on your machine, under your enrolled agent identity. Each save adds a version; resume loads the version you name. See How the Brain works.
Get started with hero brain threads
Before you start: an agent identity is enrolled. hero setup enrolls one. To check, run hero identity status; it reads Enrolled — agent id ….
See which threads exist.
hero brain threads listYou should see your threads, or
No threads are saved.and thecreatecommand. Without an enrolled identity you seeidentity_not_enrolled. See Example output.
Move a thread between Claude Code and Codex
A thread isn't tied to one agent. You save a checkpoint from the agent you're leaving and load it in the other one, from the same thread. This example goes from Claude Code to Codex; to go the other way, swap claude and codex.
Before you start: both agents run on the same machine, as the same user, so they share one Agent OS home (~/.hero) and one enrolled agent identity. hero setup has connected both. Threads are kept on this machine only; nothing is synced to another device.
In Claude Code, find the thread, or create one for the workspace you're working in.
hero brain threads list hero brain threads create --title "<title>" --workspace <path>Note the thread id and its current version. A new thread is at version 0.
Save a checkpoint from Claude Code, based on the current version.
hero brain threads save --thread <id> --expected-version <n> --source-surface claude --input checkpoint.jsonYou should see
Saved checkpoint <n+1> for <id>.The file follows the Checkpoint format. In Claude Code,/hero:braindoes steps 1 and 2 for you: it builds the checkpoint from the visible conversation and passes it on standard input (--input -).Start a new Codex session. If this is your most recently saved thread, Codex's session memory names it, with the command to load it:
hero brain threads resume --thread <id> --target-surface codexRun it, or ask Codex to use its
hero-brainskill, which runs the same command. You should seeLoaded checkpoint from <saved_at> (version <n>)., then the checkpoint as JSON.Keep working in Codex. To hand back, save from Codex against the version you loaded.
hero brain threads save --thread <id> --expected-version <n> --source-surface codex --input checkpoint.jsonClaude Code loads it with
--target-surface claude. If either agent saved in the meantime, the save is refused withcheckpoint_conflict; runlistfor the current version and load it first.
What resume checks and adds when it loads a thread for the other agent:
- It opens the thread's workspace and refuses if the folder is gone (
workspace_missing), was replaced by another folder or a link (workspace_replaced), or has a new owner (workspace_identity_changed). - It reads each file the checkpoint lists and compares its fingerprint:
verified,changed,missing, orunverifiedwhen the file is too large to check. - It marks every external reference
unverified. It doesn't fetch them. - It adds your Brain's pinned sections, and your projects and areas notes when they fit, prepared for the agent you name with
--target-surface. The whole load is at most 128 KiB; areas, then projects, are left out first, and the output lists what was left out. - It adds these warnings:
explicit_checkpoint_only,not_full_conversation,not_authorization,workspace_files_not_restored,workspace_writer_coordination_not_providedandcheckpoint_content_is_untrusted_data.
--source-surface records which agent a checkpoint came from, as you state it. Agent OS doesn't check it. Provider sign-ins, permissions and the conversation itself don't move with the thread.
Example output of hero brain threads
A thread with one saved version
hero brain threads list
Output from version 0.1.36rc13. Trimmed where you see …
With no threads:
Output from version 0.1.36rc13. Trimmed where you see …
No threads are saved. Create one to save work you can resume in another agent:
hero brain threads create --title <title> --workspace <path>
Without an enrolled identity:
Example output. The format is the command's; the numbers are examples.
identity_not_enrolled: Enroll your default agent before using threads
How to read hero brain threads output
| Line | What it means | What to do |
|---|---|---|
| 1. Thread | The thread id, its title and its current version. Version 0 means nothing has been saved. | Use the id with --thread. |
| 2. Workspace and last save | The workspace path, when the latest version was saved (or never saved), and the agent it came from (or no source). | No action is required for the workspace and last-save information. |
More hero brain threads examples
Example 1. To save a checkpoint
hero brain threads save --thread <id> --expected-version <n> --source-surface claude --input checkpoint.json
Example output. The format is the command's; the numbers are examples.
Saved checkpoint 1 for thr_0123456789abcdef0123456789abcdef.
Example 2. To load a saved checkpoint
hero brain threads resume --thread <id> --target-surface codex
The first lines, before the checkpoint itself:
Example output. The format is the command's; the numbers are examples.
Loaded checkpoint from 2026-11-04T09:00:00Z (version 1).
Work after this save is not included. Workspace files and permissions are not restored.
The checkpoint follows as JSON, with warnings that include that it isn't the full conversation, grants no permissions and is to be treated as data.
Example 3. To see a thread's versions
hero brain threads history --thread <id>
Output from version 0.1.36rc13. Trimmed where you see …
{
"schema": "hero.brain.checkpoint-history.v1",
"thread_id": "thr_8ce11f0010e3332f26584e69e5b9387b",
"current_version": 1,
"versions": [
{
"version": 1,
"saved_at": "2026-11-06T05:27:53Z",
"source_surface": "claude",
"payload_hash": "sha256:e9380aa5ab0fac009dfee31d820fc9ef123dad966a5c695116dfdb1f16829537",
"prior_payload_hash": "",
"payload_bytes": 587
}
]
}
Exit codes and errors for hero brain threads
| Code | Meaning | What to do |
|---|---|---|
0 | Success. | Nothing. |
2 | Refused: a missing or unknown verb, a missing argument, or checkpoint input that is invalid or too large. | See the errors below. |
3 | Unavailable: no enrolled identity, a stale version, a full thread history, or a thread or workspace that can't be found, was replaced or changed owner. | See the errors below. |
4 | The thread store or a file it needs couldn't be read or written safely, or a resume load is over its 128 KiB bound even after optional notes are left out. | Read the error code and message on the error output. |
A missing verb prints four lines: refused, reason, governing_rule and remedy. With --json, it prints the same keys, with "refused": true.
| Error | Cause | Fix |
|---|---|---|
identity_not_enrolled: Enroll your default agent before using threads | No agent identity is enrolled. | Run hero setup, which enrolls one. You can also run hero identity enroll, the step hero identity names when no identity is enrolled. |
checkpoint_conflict: checkpoint version is stale | --expected-version isn't the thread's current version. | Use the thread's current version, which list shows. |
checkpoint_too_large: Checkpoint input exceeds 64 KiB | The checkpoint file is over 64 KiB. | Shorten the checkpoint. |
checkpoint_invalid: <detail> | The checkpoint isn't valid JSON, or its fields don't match. The detail names the field. | Fix the named field. See Checkpoint format. |
workspace_missing, workspace_replaced or workspace_identity_changed | resume found the thread's workspace folder gone, replaced by another folder or a link, or owned by someone else. Exit 3. | Put the workspace back where the thread was created, or create a new thread for the folder you're in now. |
brain threads needs a verb | threads with no verb. | Add create, list, save, history or resume. |
Files and environment for hero brain threads
| Name | Kind | Purpose |
|---|---|---|
| Your checkpoint file | JSON file passed to save --input | The checkpoint to save. See Checkpoint format. |
Limits of hero brain threads
| Limit | Behaviour | Can you change it? | What to do |
|---|---|---|---|
| Identity | Every verb refuses until an agent identity is enrolled. | Yes | Run hero setup, which enrolls one. Check it with hero identity status, which prints Enrolled — agent id agp_… and says the id names your agent in its Brain threads and grants no permissions. |
| Saving | Nothing saves by itself. A checkpoint is at most 64 KiB, and a thread keeps up to 50 versions. | No | Run save to keep a checkpoint. |
| What resume loads | The saved checkpoint only: not the conversation, workspace files or permissions. | No | Use history to find the version, then resume it. |
Resume after hero brain init | Once the Brain has a manifest, resume refuses with required_brain_section_unreadable: Required section is missing (exit 4) while your identity file (~/.hero/SOUL.md) or memory file (~/.hero/MEMORY.md) is missing. | Yes | Create both files, then resume again. |
| Latest thread at session start | When session memory shows a thread, it's the newest saved thread from any project, not only this one. | No | Use list with --workspace-id to find a workspace's threads. |
Commands related to hero brain threads
Checked against Agent OS 0.1.36rc14 (build 599c5e120c18) on 17 Nov 2026.