ox session

Manage AI coworker sessions: view, commit, and upload conversations between humans and AI coworkers to the Ledger.

What are sessions?

Sessions are conversations between a human and an AI coworker in a specific repository. They capture:

• The code changes made during the session
• Decisions and rationale
• Prompts and responses
• Files touched and commits created

Sessions are stored in the Ledger (the per-repo work history). They are NOT audio recordings, those are Discussions, which go to Team Context.

Session lifecycle

ox agent <id> session start  →  work with AI coworker  →  ox agent <id> session stop
                                                                 │
                                                                 ▼
                                                          (auto-commits,
                                                           uploads to Ledger)

Most session management is automatic. The ox session subcommands exist for manual recovery and advanced workflows.

Usage

Subcommands

Import past coding sessions

Bring in Claude Code and Codex sessions you ran in this repository before SageOx, or while recording was off. The command reads those tools' native session history on this computer and saves selected sessions to this repository's Ledger.

Prepare to import

Use an up-to-date ox CLI with ox session import available. Follow the CLI quickstart to sign in and initialize the repository, then sync its Ledger if it isn't cloned on this computer.

Session recording must be enabled, and you need write access to the Ledger. Install and sign in to Claude Code or Codex so it can prepare summaries; by default, each session uses the CLI that created it.

The command imports available history for this repository from Claude Code and Codex. It doesn't import arbitrary exported files or history from every tool connected over MCP, and it can't reconstruct deleted history.

Review and upload

An uploaded session includes its full conversation transcript and summary in the destination Ledger. Read the conversation for content you don't want to share before confirming.

Run from inside the repository:

1. Check the destination Ledger and its visibility. A public Ledger can be read by anyone.
2. Browse the opening request, human prompts, and last AI reply. Press Space to select sessions, or b to review them in a local browser.
3. Confirm the upload in your terminal. Browser review returns your selection to the terminal; it doesn't upload on its own.
4. Open the session links printed for successful uploads.

To start with browser review:

Previewing calls no summarizer. After confirmation, your installed Claude Code or Codex CLI prepares summaries using your own login, then the ox CLI uploads the sessions to the Ledger. That CLI may use a hosted model and your existing usage allowance; running it on this computer doesn't mean inference stays on this computer.

Preview or narrow the selection

Preview the candidates without uploading:

Limit the review to Codex sessions active in the last seven days:

Read one session without importing it. Replace native-session-id with its ID from the preview:

AI coworker invocations and non-interactive runs return a preview by default. Only use --yes after explicitly authorizing the selected sessions and destination; it bypasses terminal confirmation.

Read the result

The final report counts selected sessions as uploaded, committed locally, failed, or skipped. A local commit alone doesn't mean the session reached SageOx; only successful uploads get a session link.

Sessions already imported or recorded live are recognized and skipped on later runs. Import doesn't append later messages to an already imported session or fill gaps in a session recorded live.

Sessions still in progress are skipped. A session the summarizer judges not worth sharing stays on this computer.

A session whose ox recording you aborted is listed as aborted and never uploaded. To upload one anyway, name it with --session and add --include-aborted; the confirmation says it was aborted.

For a failed session, follow the printed retry command. For a session committed locally but not pushed, follow the report's rerun instruction to finish uploading.

Troubleshoot an import

Enable recording for this repository

To enable session_recording for this repository:

This also affects future sessions here. If a user-level override still disables recording, inspect the setting:

Check configuration priorities before changing that override.

List sessions

Shows the date, time, user, and hydration status of recent sessions in the Ledger, newest first. By default, it lists only sessions from the last 7 days; an explicit --since/--until window replaces that default.

View a session

Opens the session in your configured viewer format (HTML, text, or JSON). Without a session name, it shows the most recent session. Set the format with:

If the session shows status "stub", its content hasn't been downloaded yet. Sessions from other coworkers arrive as stubs (metadata only); run ox session download <session-name> to fetch the content.

Check and stop recordings

Shows all active recordings in this project. With several worktrees or agents, more than one recording can be in progress at once; --current shows only the calling agent's recording (uses SAGEOX_AGENT_ID).

Without an agent ID, ox session stop lists active recordings.

Wait for sessions to reach the Ledger

Makes sure every session recorded on this machine is in the Ledger before the machine goes away, such as a CI-like pod. Run it after the AI coworkers exit. wait never uploads anything itself: where the daemon uploads sessions, it hands the daemon every ended session and waits up to --timeout; elsewhere, it only reports.

The report counts the sessions finished since --since and how many of them are in the Ledger, lists older pending sessions, and names every session not in the Ledger with the reason. wait exits 0 only when all of them are in the Ledger.

Manual session commands

These commands handle steps that normally happen automatically during ox agent <id> session stop.

Commit

Commit pending sessions to the local Ledger. Use when the auto-commit failed or you need to commit manually; add -m for a custom commit message. Run ox sync to also push to the remote.

Upload

Publish a session to the Ledger. This is the only way a session held on this machine (session_publishing: manual) is published. It also publishes a session whose content was left in the local cache by an interrupted stop or an orphaned recording, and retries one whose stop failed during the network phase.

The session name can be the full directory name or the agent ID suffix. Publishing uploads the content, writes meta.json, commits, and pushes; the summary is generated afterward in the background.

Download

Download the content files (raw.jsonl, summary.md, session.md, session.html) of a session that arrived as a stub. ox stores the content in the ledger cache (.sageox/cache/sessions/) instead of overwriting pointer files, which keeps the git working tree clean.

Export

Export a session to a standalone markdown file. Without arguments, it exports the most recent session.

Pass a session name to export a specific session, or --input <file> to export a JSONL file outside the managed store.

Regenerate

Regenerate session artifacts (summary.md, session.md) from raw session data. The session name supports partial matching, such as the agent ID suffix.

--summary requires the claude CLI and works on one session at a time. --redact re-applies all current REDACT.md rules (team, repo, and user layers), regenerates the downstream artifacts, and uploads the updated content to LFS. Add --all to regenerate every session, and --force to skip confirmation prompts.

Push summary

Push a generated summary JSON file to the session's Ledger directory. Coding agents call it automatically after they process the summary prompt from session stop. The summary file is committed directly to git (no LFS) alongside meta.json.

Use --file - to read the summary from stdin.

Contribution score

Report how much SageOx team context influenced this session's work. The score determines whether commits receive SageOx attribution.

Audit and redact credentials

ox automatically redacts secrets from sessions and captured data. These commands find credential patterns left in session recordings and clean them up.

ox session audit never modifies files, amends commits, or uploads. It reports each finding with the detector name, file, and line, and never prints the matched bytes. Both commands first hydrate every LFS-pointer session file, so on a large Ledger they can take minutes and pull tens of megabytes.

ox session redact works on committed-but-not-yet-pushed recordings. Before it changes anything, it snapshots the entire Ledger to an immutable backup and prints the snapshot path and SHA-256. It asks about every file individually: there is no bulk-approve flag, the global --yes does not approve redactions, and q quits with the snapshot intact.

Inspect the redaction policy

The policy covers cloud provider keys, API tokens, database connection strings, private keys and JWTs, and generic secrets. Add --json to policy for output suitable for security audits. verify checks the release build's Ed25519 signature and exits 0 when it is valid (or not configured for dev builds) and 1 otherwise.

Clean up local sessions

ox session prune removes finalized sessions that exist locally but were never pushed to the Ledger. With --all, it removes every local session not in the Ledger, including paused, canceled, ghost, and orphan sessions. Active recordings are always skipped, and sessions already in the Ledger are never touched.

ox session remove searches both the local cache and the Ledger. Removing a session from the Ledger affects all coworkers, so it needs --force or interactive confirmation.

Validate and compress raw sessions

ox session lint checks that every entry has a valid type and the required fields. Use --file to lint a standalone JSONL file, --all to lint every session, and --skip-eid for older sessions without entry IDs.

ox session token-optimize applies deterministic streaming transforms, such as stripping ANSI codes and eliding base64 images, and writes to stdout by default. It never modifies the original raw.jsonl.

Relationship to agent commands

The ox agent <id> session commands handle the active session lifecycle:

The ox session commands (without agent) manage saved sessions and import native coding history into the Ledger.

Three import commands serve different purposes:

Where sessions are stored

Sessions live in the Ledger at sessions/<session-name>/:

sessions/
└── 2026-04-13T10-30-user-Oxa7b3/
    ├── meta.json        # Session metadata
    ├── summary.json     # Session summary (plain git, no LFS)
    ├── raw.jsonl        # Raw session recording (LFS)
    ├── session.md       # Session as markdown (LFS)
    ├── summary.md       # Summary as markdown (LFS)
    └── session.html     # HTML viewer (LFS)

Content files are stored in Git LFS to keep the Ledger lightweight. Sessions from other coworkers arrive as stubs until you run ox session download.

Troubleshooting

Session stuck in "uploading" - Run ox session upload <session-name> to retry the upload.

Missing summary - Run ox session regenerate <session-name> --summary to re-generate it (requires the claude CLI).

Can't view session - If status shows "stub", run ox session download <session-name> to fetch the content.

Session not appearing - Check ox session list to verify it was committed. If not, run ox session commit.

Machine about to shut down - Run ox session wait --since <time> to confirm every session recorded here reached the Ledger.

What's next

• ox agent prime - Context injection for agents
• ox init - Initialize repository
• Team Context - Team-wide knowledge (vs per-repo Ledger)