# codex-session-manager codex会话管理

**Repository Path**: a-summer-wind/codex-session-manager

## Basic Information

- **Project Name**: codex-session-manager codex会话管理
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-25
- **Last Updated**: 2026-06-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Codex Session Manager

[![CI](https://github.com/3131470985/codex-session-manager/actions/workflows/ci.yml/badge.svg)](https://github.com/3131470985/codex-session-manager/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

VS Code extension for managing local Codex session JSONL files.

## Features

- Lists active sessions from `sessions/YYYY/MM/DD/*.jsonl`.
- Lists archived sessions from `archived_sessions/*.jsonl`.
- Reads `state_5.sqlite` metadata when `sqlite3` is available.
- Imports exported JSONL sessions back into the Codex session tree.
- Exports one or many sessions as JSONL files.
- Archives active sessions.
- Unarchives archived sessions.
- Searches session metadata and JSONL content.
- Filters sessions by workspace, project directory, date range, model, CLI version, and token usage.
- Groups sessions by project, date, status, model, or a flat recent-first list.
- Shows an overview and workflow shortcuts directly in the tree view.
- Opens a readable session view with user, assistant, tool, context, and metadata blocks.
- Runs a health check for Codex home, session files, SQLite availability, schema, backups, and orphan records.
- Supports Simplified Chinese and English UI text.
- Supports batch archive, batch unarchive, and safe delete to a plugin trash folder.
- Supports favorites, pins, custom titles, tags, and notes in sidecar metadata.
- Supports resume command templates and terminal resume.
- Exports readable Markdown, HTML, JSON bundles, and ZIP bundles.
- Opens a statistics panel for project activity, model distribution, token ranking, failed commands, and archive suggestions.
- Opens raw JSONL, reveals files, and copies session file paths.

## Language

Command titles and menu labels use VS Code's native localization files:

- English fallback: `package.nls.json`
- Simplified Chinese: `package.nls.zh-cn.json`

Runtime UI text, including tree items, quick picks, dialogs, health reports, and readable session views, can be switched with:

```json
{
  "codexSessionManager.language": "auto"
}
```

Supported values:

- `auto`: follows VS Code display language
- `zh-cn`: Simplified Chinese
- `en`: English

The top toolbar buttons in the `Codex Sessions` view also follow this setting.

## Tree view layout

The `Codex Sessions` view is organized as a lightweight session workspace:

- `Overview`: total, active, archived, latest update, and current grouping.
- `Workflow`: search, workspace filter, grouping switcher, health check, and Codex home shortcuts.
- `Active filters`: visible only when filters are active; click it to clear filters.
- Session groups: grouped by the configured mode.

The default grouping is `project`, which is optimized for daily multi-repository usage.

Available grouping modes:

- `project`
- `date`
- `status`
- `model`
- `flat`

Use `Codex Sessions: Change Session Grouping` or click `Overview` / `Workflow > Grouping` to switch modes.

## Search and filters

Use `Codex Sessions: Search Sessions` to search across session titles, metadata, file paths, messages, tool calls, command output, and other JSONL string fields.

The search box also supports inline filters:

```text
error "fix login" cwd:my-project model:gpt from:2026-01-01 to:2026-06-25 tokens>=1000 tokens<=200000
```

Additional commands are available from the Command Palette:

- `Codex Sessions: Toggle Current Workspace Filter`
- `Codex Sessions: Filter Sessions by Project`
- `Codex Sessions: Filter Sessions by Date Range`
- `Codex Sessions: Filter Sessions by Model`
- `Codex Sessions: Advanced Session Filters`
- `Codex Sessions: Clear Session Filters`

## Readable session view

Clicking a session opens a readable Webview by default. The raw JSONL remains available through `Open Session JSONL`.

The readable view contains a sticky metadata header, a left sidebar with session statistics and a timeline, and the main conversation body. It groups common events:

- user messages
- assistant messages
- tool calls and tool results
- reasoning blocks
- session metadata
- turn context
- generic events

Large blocks are truncated in the view to keep VS Code responsive.

Readable sessions can also be exported from the context menu:

- `Export Readable Session as Markdown`
- `Export Readable Session as HTML`

## Health check

Run `Codex Sessions: Run Health Check` to write a diagnostic report to the `Codex Sessions` output channel.

The health check validates:

- configured Codex home
- active and archived session directories
- `state_5.sqlite`
- `sqlite3` executable availability
- required `threads` schema columns
- JSONL file counts
- SQLite backup presence
- DB rows pointing to missing JSONL files
- JSONL files missing from DB
- invalid JSONL lines in a bounded validation sample

## Statistics

Run `Codex Sessions: Open Statistics` to open a read-only statistics panel.

The panel includes:

- total, active, archived, token, file, and line counts
- session counts by project
- recently active projects
- model distribution
- token usage ranking
- longest sessions by JSONL lines
- most frequently failed commands inferred from session events
- inactive active sessions that are candidates for archive

## Local development

1. Open this folder in VS Code.
2. Press `F5` to launch an Extension Development Host.
3. Open the `Codex Sessions` activity bar view.

Run checks:

```bash
npm run check
```

Package a VSIX:

```bash
npm run package
```

## Release

Release notes for the current public release are in `RELEASE_NOTES.md`.

Maintainer release steps are documented in `docs/RELEASING.md`.

Generated `.vsix` files are release artifacts and should not be committed.

## Settings

| Setting | Default | Purpose |
| --- | --- | --- |
| `codexSessionManager.codexHome` | empty | Uses `CODEX_HOME` or `~/.codex` when empty. |
| `codexSessionManager.sqlite3Path` | `sqlite3` | Executable used to update `state_5.sqlite`. |
| `codexSessionManager.enableStateDatabaseWrites` | `true` | Updates Codex thread state on import/archive/unarchive. |
| `codexSessionManager.backupBeforeWrites` | `true` | Creates backups under `.codex-session-manager/backups`. |
| `codexSessionManager.groupBy` | `project` | Groups sessions by `project`, `date`, `status`, `model`, or `flat`. |
| `codexSessionManager.language` | `auto` | Uses `auto`, `zh-cn`, or `en` for runtime UI text. |
| `codexSessionManager.resumeCommandTemplate` | `codex resume {id}` | Template for resume commands. Supports `{id}`, `{file}`, and `{cwd}`. |

## Organization metadata

Custom organization data is stored outside Codex JSONL files:

```text
~/.codex/.codex-session-manager/metadata.json
```

Supported fields include custom title, favorite, pin, tags, and notes.

## Safe delete and exports

`Move Session to Trash` copies the JSONL and a manifest to:

```text
~/.codex/.codex-session-manager/trash/
```

The extension can export:

- raw JSONL
- readable Markdown
- readable HTML
- JSON bundle
- ZIP bundle with JSONL, Markdown, and manifest

## Resume

Use `codexSessionManager.resumeCommandTemplate` to control resume behavior:

```json
{
  "codexSessionManager.resumeCommandTemplate": "codex resume {id}"
}
```

Available placeholders:

- `{id}`
- `{file}`
- `{cwd}`

## Notes

The extension uses the observed Codex layout:

```text
~/.codex/
  sessions/YYYY/MM/DD/rollout-*.jsonl
  archived_sessions/rollout-*.jsonl
  state_5.sqlite
  session_index.jsonl
```

When database writes are enabled, every import/archive/unarchive operation first runs `VACUUM INTO` to create a backup of `state_5.sqlite`.

## License

MIT. See `LICENSE`.