Ekamyth Agent OS docs
Added for agents / Brain: Claude Code and Codex

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.

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

SubcommandWhat it doesReads or changes
createCreates a thread for one workspace.Changes
listLists saved threads without loading their content.Reads
saveSaves 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
historyLists a thread's saved versions.Reads
resumeLoads 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.

VerbArgumentTypeRequiredDefaultWhat it does
create--title <title>TextYesNoneThe thread's title.
create--workspace <path>DirectoryOne of the twoNoneThe workspace the thread belongs to.
create--workspace-id <id>Workspace idOne of the twoNoneAn existing workspace, by its id.
list--workspace-id <id>Workspace idNoAll workspacesLists only that workspace's threads.
list, history--limit <n>IntegerNo50How many rows to return.
save, history, resume--thread <id>Thread idYesNoneThe thread, as list prints it.
save--expected-version <n>Integer, 0 or moreYesNoneThe version your save is based on.
save--source-surface claude|codexAgent nameYesNoneThe agent the checkpoint came from.
save--input <file>|-File, or - for standard inputYesNoneThe checkpoint, as JSON, at most 64 KiB. See Checkpoint format.
resume--version <n>IntegerNoThe latestThe exact version to load.
resume--target-surface claude|codexAgent nameYesNoneThe 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.

FieldHolds
schemahero.brain.thread-checkpoint.v1
objectiveWhat the work is for.
constraints, decisions, unresolved_questions, blockersLists of text entries.
completed_workA list of claims, each linked to an artifact or reference.
artifactsFiles in the workspace, by relative path and fingerprint.
external_referencesURLs, commits, pull requests or other references.
recent_interaction_summaryA summary, with provenance agent_summary.
next_actionWhat 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 ….

  1. See which threads exist.

    hero brain threads list

    You should see your threads, or No threads are saved. and the create command. Without an enrolled identity you see identity_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.

  1. 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.

  2. 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.json

    You should see Saved checkpoint <n+1> for <id>. The file follows the Checkpoint format. In Claude Code, /hero:brain does steps 1 and 2 for you: it builds the checkpoint from the visible conversation and passes it on standard input (--input -).

  3. 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 codex

    Run it, or ask Codex to use its hero-brain skill, which runs the same command. You should see Loaded checkpoint from <saved_at> (version <n>)., then the checkpoint as JSON.

  4. 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.json

    Claude Code loads it with --target-surface claude. If either agent saved in the meantime, the save is refused with checkpoint_conflict; run list for the current version and load it first.

What resume checks and adds when it loads a thread for the other agent:

--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

LineWhat it meansWhat to do
1. ThreadThe thread id, its title and its current version. Version 0 means nothing has been saved.Use the id with --thread.
2. Workspace and last saveThe 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

CodeMeaningWhat to do
0Success.Nothing.
2Refused: a missing or unknown verb, a missing argument, or checkpoint input that is invalid or too large.See the errors below.
3Unavailable: 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.
4The 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.

ErrorCauseFix
identity_not_enrolled: Enroll your default agent before using threadsNo 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 KiBThe 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_changedresume 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 verbthreads with no verb.Add create, list, save, history or resume.

Files and environment for hero brain threads

NameKindPurpose
Your checkpoint fileJSON file passed to save --inputThe checkpoint to save. See Checkpoint format.

Limits of hero brain threads

LimitBehaviourCan you change it?What to do
IdentityEvery verb refuses until an agent identity is enrolled.YesRun 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.
SavingNothing saves by itself. A checkpoint is at most 64 KiB, and a thread keeps up to 50 versions.NoRun save to keep a checkpoint.
What resume loadsThe saved checkpoint only: not the conversation, workspace files or permissions.NoUse history to find the version, then resume it.
Resume after hero brain initOnce 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.YesCreate both files, then resume again.
Latest thread at session startWhen session memory shows a thread, it's the newest saved thread from any project, not only this one.NoUse list with --workspace-id to find a workspace's threads.

Checked against Agent OS 0.1.36rc14 (build 599c5e120c18) on 17 Nov 2026.