# ox session (/docs/cli/commands/session)



ox session [#ox-session]

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

What are sessions? [#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 [#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 [#usage]

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

Subcommands [#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 [#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 [#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 [#manual-session-commands]

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

Commit [#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]

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

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

Hydrate [#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 [#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-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 [#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 [#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 [#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 [#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 [#whats-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)