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 session start  →  work with AI coworker  →  ox agent 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.

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 recent sessions from the Ledger with their status, timestamps, and summaries.

View a session

Opens the session in your configured viewer format (HTML, text, or JSON). Set the format with:

If the session shows status "stub", the full content hasn't been synced yet. Run ox sync to fetch the complete session data.

Manual session commands

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

Commit

Commit a session to the local Ledger. Use when the auto-commit failed or you need to commit manually.

Upload

Upload a committed session to the cloud Ledger. Use when the upload was interrupted.

Hydrate

Add metadata (model info, timestamps, summaries) to a session. Use when metadata generation was skipped.

Regenerate summary

Re-run summary generation for a session. Useful when the initial summary was poor or truncated.

Push summary

Push a regenerated summary to the cloud. Separate from upload because summaries can be updated after the session is uploaded.

Contribution score

Report the SageOx contribution score for the current or specified session. Shows how much the AI coworker contributed.

Relationship to agent commands

The ox agent 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-13-auth-refactor/
    ├── meta.json        # Session metadata
    ├── session.html     # HTML viewer (LFS)
    ├── transcript.md    # Full transcript (LFS)
    └── plan.md          # Session plan (LFS)

Large files (transcript, HTML viewer) are stored in Git LFS to keep the Ledger lightweight.

Troubleshooting

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

Missing summary - Run ox session regenerate then ox session push-summary.

Can't view session - If status shows "stub", run ox sync to fetch the full session data.

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

What's next

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