# ox session (https://sageox.ai/docs/cli/session)

# 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](/docs/context-capture/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

<Terminal>
  <TerminalCommand>ox session [command]</TerminalCommand>
</Terminal>

## Subcommands

| Command | Description |
|---------|-------------|
| `ox session list` | List sessions in the Ledger |
| `ox session view <name>` | View a session's content |
| `ox session commit` | Commit session to Ledger |
| `ox session hydrate` | Hydrate session with metadata |
| `ox session upload` | Upload session to cloud |
| `ox session push-summary` | Push session summary |
| `ox session regenerate` | Regenerate session summary |
| `ox session score` | Report SageOx contribution score |

## List sessions

<Terminal>
  <TerminalCommand>ox session list --limit 5</TerminalCommand>
</Terminal>

Shows recent sessions from the Ledger with their status, timestamps, and summaries.

## View a session

<Terminal>
  <TerminalCommand>ox session view 2026-04-13-auth-refactor</TerminalCommand>
</Terminal>

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

<Terminal>
  <TerminalCommand>ox config set view_format html</TerminalCommand>
</Terminal>

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.

<Terminal>
  <TerminalCommand>ox session commit</TerminalCommand>
</Terminal>

### Upload

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

<Terminal>
  <TerminalCommand>ox session upload</TerminalCommand>
</Terminal>

### Hydrate

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

<Terminal>
  <TerminalCommand>ox session hydrate</TerminalCommand>
</Terminal>

### Regenerate summary

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

<Terminal>
  <TerminalCommand>ox session regenerate</TerminalCommand>
</Terminal>

### Push summary

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

<Terminal>
  <TerminalCommand>ox session push-summary</TerminalCommand>
</Terminal>

### Contribution score

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

<Terminal>
  <TerminalCommand>ox session score</TerminalCommand>
</Terminal>

## Relationship to agent commands

The `ox agent session` commands handle the active session lifecycle:

| Command | Purpose |
|---------|---------|
| `ox agent session start` | Begin recording a new session |
| `ox agent session stop` | End recording and auto-commit/upload |

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](/docs/cli/prime) - Context injection for agents
- [ox init](/docs/cli/init) - Initialize repository
- [Team Context](/docs/features/team-context) - Team-wide knowledge (vs per-repo Ledger)