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

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 already-recorded sessions in the Ledger.

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)