# ox session (https://test.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
ox session [command]
## Subcommands
| Command | Description |
|---------|-------------|
| `ox session import` | Review and upload past Claude Code and Codex sessions from this repository |
| `ox session list` | List sessions in the Ledger |
| `ox session view ` | 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 |
## 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](/docs/cli#installation) with `ox session import` available. Follow the [CLI quickstart](/docs/cli/quickstart) to sign in and initialize the repository, then [sync its Ledger](/docs/cli/sync) 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:
ox session import
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:
ox session import --browse
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:
ox session import --dry-run
Limit the review to Codex sessions active in the last seven days:
ox session import --agent codex --since 7d
Read one session without importing it. Replace `native-session-id` with its ID from the preview:
ox session import --preview --session <native-session-id>
| Flag | Purpose |
|------|---------|
| `--agent claude\|codex` | Include sessions from one tool |
| `--browse` | Review in a local browser, then confirm in the terminal |
| `--dry-run` | Preview candidates without uploading |
| `--session ` | Select by native session ID or a unique prefix of at least 8 characters; accepts comma-separated IDs |
| `--preview` | Read one session without importing; requires a single `--session` |
| `--since ` | Include sessions active within a window such as `7d` or `48h`, or since a date such as `2026-09-01` |
| `--summarizer claude\|codex` | Use this installed, signed-in CLI instead of each session's original tool |
| `--parallel ` | Limit concurrent summarization; default is 3, minimum is 1 |
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
| What you see | What to do |
|--------------|------------|
| No eligible sessions | Check that you're in the original repository on the computer that holds the history. Review filters and skip reasons: sessions may already be imported, recorded live, or still in progress. |
| Recording is disabled | [Enable recording for this repository](#enable-recording-for-this-repository), then retry. |
| Needs summarizer | Install and sign in to the named CLI, or choose another installed, signed-in CLI with `--summarizer claude` or `--summarizer codex`. |
| Destination can't be verified | Check your connection and [SageOx status](/docs/cli/status), then retry. `--dry-run` still lets you preview without uploading. |
| Read-only Ledger | Ask a team admin for write access before importing. |
| Session changed during review | Rerun the review before confirming the upload. |
| Ledger needs repair | [Run diagnostics](/docs/cli/doctor) and follow the diagnosis before retrying. |
#### Enable recording for this repository
To enable `session_recording` for this repository:
ox config set session_recording auto --repo
This also affects future sessions here. If a user-level override still disables recording, inspect the setting:
ox config get session_recording
Check [configuration priorities](/docs/cli/config#priority-chain) before changing that override.
## List sessions
ox session list --limit 5
Shows recent sessions from the Ledger with their status, timestamps, and summaries.
## View a session
ox session view 2026-04-13-auth-refactor
Opens the session in your configured viewer format (HTML, text, or JSON). Set the format with:
ox config set view_format html
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.
ox session commit
### Upload
Upload a committed session to the cloud Ledger. Use when the upload was interrupted.
ox session upload
### Hydrate
Add metadata (model info, timestamps, summaries) to a session. Use when metadata generation was skipped.
ox session hydrate
### Regenerate summary
Re-run summary generation for a session. Useful when the initial summary was poor or truncated.
ox session regenerate
### Push summary
Push a regenerated summary to the cloud. Separate from upload because summaries can be updated after the session is uploaded.
ox session push-summary
### Contribution score
Report the SageOx contribution score for the current or specified session. Shows how much the AI coworker contributed.
ox session score
## 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 saved sessions and import native coding history into the Ledger.
Three import commands serve different purposes:
| Command | What it imports | Destination |
|---------|-----------------|-------------|
| `ox session import` | Past Claude Code and Codex history from this repository | Repository Ledger |
| `ox agent session import` | A planning conversation | Current session recording |
| `ox import ` | A document or recording | Team Context |
## Where sessions are stored
Sessions live in the Ledger at `sessions//`:
```
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)