SessionReviewer

SessionReviewer turns local Codex session history into a concise, editable project review. It helps you recover a project's goal, current stage, next action, risks, key decisions, evolution timeline, model usage, and cost without copying raw session logs into your notes.

Read the Chinese documentation

What it does

• Scans every Codex session associated with the project, then deterministically reduces the per-session results into one project view without an Agent call or token usage.
• Keeps the SessionReviewer skill as an optional semantic refinement path; it is not required for the normal whole-project scan.
• Stores human-readable project context in docs/session-review/项目回顾.md and docs/session-review/项目历史.md.
• Synchronizes editable project notes with a configured vault using a deterministic three-way merge.
• Provides a desktop project browser with evolution, decisions, risks, usage, pricing sources, and safe editing controls.
• Keeps machine-owned evidence, accounting, revisions, and synchronization metadata out of the human recovery view.

Raw session files stay on your computer. SessionReviewer does not modify the original JSONL files and does not require a separate OpenAI API key.

Requirements

• macOS 13 or later on Intel or Apple Silicon
• Windows 10 22H2 or Windows 11 on x64
• Obsidian 1.8.7 or later for the desktop plugin
• Go 1.26 only when building the CLI from source

The desktop plugin is marked desktop-only because it invokes the local SessionReviewer CLI for validated status, synchronization, migration preview, and recovery actions.

Install the desktop plugin

0.4.6: five-page project workflow

The source candidate restores evolution, problem operations, decision candidates, Session search and exact Q/A, and explicit pricing in a responsive five-page view. Scanning and reading invoke no Agent; candidate extraction requires an explicit request. Codex image attachments retain bounded user text, while incomplete source coverage and unknown prices remain visible.

Final user acceptance is complete; publication is verified separately through the tag workflow. See 0.4.6 release notes for features, source limits, upgrade guidance, and the remaining client/publication gates. The latest public release download remains independent of this source version.

Download main.js, manifest.json, and styles.css from the latest GitHub Release. Place the three files in:

<Vault>/.obsidian/plugins/session-reviewer/

Enable SessionReviewer under Settings → Community plugins, then run SessionReviewer: Open project evolution from the command palette or select the history icon in the left ribbon.

No executable settings are required. On startup, the plugin discovers and verifies SessionReviewer from normal user installation locations and PATH; legacy saved paths are accepted once for migration and then removed. If discovery fails, install or run SessionReviewer once and reload the plugin. The plugin only executes fixed, allow-listed CLI actions; it does not read executable paths or arbitrary arguments from Markdown.

Initialize and synchronize a project

Create a stable project mapping and review files:

session-reviewer init --project /path/to/project --vault /path/to/vault
session-reviewer init --project /path/to/project --vault /path/to/vault --write

Preview synchronization without writing:

cd /path/to/project
session-reviewer sync --dry-run
session-reviewer sync status --json

Apply a real project-to-vault synchronization:

session-reviewer sync

The first command previews initialization. Adding --write creates the stable mapping and review files. Synchronization uses per-entity base snapshots so independent edits can merge while same-field conflicts remain explicit.

Update the whole project with zero tokens

Run a complete foreground scan from the initialized project:

session-reviewer scan --json

The command discovers all Codex sessions associated with the project, updates deterministic per-session memory, reduces it into a project-wide view, preserves accepted human edits and unknown Markdown sections, and synchronizes the concise projection to Obsidian. It never sends session content to an Agent and reports review_run_tokens: 0.

In supported legacy views, the Obsidian action 更新项目脉络 starts the same work as a durable background job. For the v4 Markdown view, use the CLI; its equivalent background controls are:

session-reviewer scan start --json
session-reviewer scan status --json

Terminal states distinguish a complete scan (completed), a complete scan with isolated source issues (completed_with_issues), and a failed scan (failed). Starting the same project again while its worker is queued or running returns the existing job instead of launching a duplicate.

OpenCode source (development candidate)

The read-only SQLite adapter is opt-in. Set SESSION_REVIEWER_OPENCODE_DB to an absolute path in the environment of the SessionReviewer CLI process. An unset value leaves OpenCode unavailable and does not inspect its default live database. In Obsidian, the CLI launched by the plugin must inherit this setting; changing a separate Terminal environment does not change an already running Obsidian process.

RAM snapshot payload defaults to 512 MiB. For a larger local database, set SESSION_REVIEWER_OPENCODE_SNAPSHOT_MIB to an integer from 1 to 4096 in the same CLI environment. This bounds the aggregate captured database/WAL plus any newly allocated expanded image, so WAL growth can require roughly twice the database size. Go/SQLite runtime overhead is additional. Keep the default unless the machine has enough free memory; exceeding the selected budget fails before publication. The database remains read-only at every budget.

The adapter discovers current-project root and child Sessions without the CLI listing's 100-item limit. It reads a bounded RAM snapshot of the database and committed WAL data; it does not start an Agent, write to the source, or save transcript sidecars. Currently supported: the pinned OpenCode 1.18.30 legacy session/message/part layout. Event-sourced Sessions, reverted history, incompatible schemas, source drift, and exceeded limits fail with an explicit error. An unfinished tail is deferred and marked incomplete. Session IDs retain native case. Missing or conflicting token totals show unavailable usage; a later correction can refresh accounting without rewriting conversation references. Native/live-store acceptance remains separate from synthetic fixture tests.

Optional Agent-assisted review

Prepare a bounded evidence packet:

session-reviewer prepare checkpoint \
  --sessions-root "$HOME/.codex/sessions" \
  --output ./evidence.json

The SessionReviewer skill converts the packet into a semantic proposal. Apply the validated proposal locally:

session-reviewer apply \
  --proposal /path/to/proposal.json \
  --evidence /path/to/evidence.json \
  --project /path/to/project

An accepted apply updates the machine ledger and the two human-readable project files before advancing the accepted cursor. Reapplying the same accepted proposal is idempotent.

The manual Skill workflow prepares bounded evidence and accepts a validated semantic proposal. It remains available when deterministic project context needs human-requested interpretation or enrichment, but the Obsidian plugin does not invoke an Agent for its normal update action.

The legacy Agent-orchestrated job remains covered by its compatibility suite:

go test ./test/reviewjob -count=1

The suite covers its multi-session happy path, failure and retry, cancellation, and kill-based restart recovery, and skips automatically on unsupported platforms.

Build and verify

go test ./...
go vet ./...

cd obsidian-plugin
npm ci
npm run check

Release assets are reproducible and accompanied by SHA256SUMS. The GitHub Actions release workflow publishes the three standalone plugin files required by the Community directory, the plugin ZIP, and CLI archives for macOS and Windows.

Privacy and safety

SessionReviewer keeps raw session logs local, stores bounded redacted observations instead of duplicating the raw transcripts, binds optional proposals to evidence digests and accepted revisions, and fails closed on modified machine ledgers or unresolved synchronization conflicts. Human-editable fields and unknown custom Markdown remain the highest presentation authority; machine-owned accounting, evidence, and generated sections remain separate.

License

Apache License 2.0. Copyright 2026 NeoMei and QUUKK.