codexsm

codexsm is a safety-first local Codex session manager written in Go.

Quick Links

Topic	Link
Architecture	docs/ARCHITECTURE.md
Command Guide	docs/COMMANDS.md
Release Checklist	docs/RELEASE.md
Changelog	CHANGELOG.md

Compatibility

• Go: 1.26+
• Required experiment: GOEXPERIMENT=jsonv2
• JSON packages: encoding/json/v2, encoding/json/jsontext

Important

GOEXPERIMENT=jsonv2 is required for build, install, and test.

export GOEXPERIMENT=jsonv2

Install

GOEXPERIMENT=jsonv2 go install github.com/MysticalDevil/codexsm@v0.3.9

Or with mise:

GOEXPERIMENT=jsonv2 mise install go:github.com/MysticalDevil/codexsm@v0.3.9

Quick Start

# List sessions
codexsm list

# Open TUI
codexsm tui

# Grouped TUI
codexsm tui --group-by host

# Run health checks
codexsm doctor

# Explain AGENTS.md rule sources and effective rules
codexsm agents explain

# Lint AGENTS.md layering for shadowed/duplicate rules
codexsm agents lint --strict

# Dry-run single session migration to a new cwd
codexsm session migrate --from /old/path --to /new/path

# Dry-run batch migration from TOML mappings
codexsm session migrate --file ./migrate.toml

# Dry-run delete
codexsm delete --id-prefix 019ca9

# Dry-run restore from trash
codexsm restore --id-prefix 019ca9

Tip

For complete examples and command flags, use docs/COMMANDS.md.

At A Glance

Area	Summary
Browse	list, group, and tui for session discovery
Safety	dry-run by default, explicit --confirm for real actions
Recovery	batch_id-based rollback with restore --batch-id
Migration	session migrate for Resume-compatible cwd/path moves
Diagnostics	doctor and config validation tooling
Rules Visibility	agents explain / agents lint for AGENTS.md traceability and policy checks

Core Features

• Session listing and grouping (list, group)
• Interactive browser (tui) with theme support
• Safe delete/restore workflow (dry-run by default)
• TUI group delete from a selected group header with triple confirm for real execution
• Resume-compatible session migration (session migrate)
• TUI pending-action confirmation shown in bottom keybar (Y/N) with stronger visibility
• TUI delete keeps navigation continuity by advancing selection to the next session
• Batch rollback via restore --batch-id
• Diagnostics and configuration (doctor, config)
• AGENTS.md instruction visibility and lint checks (agents explain, agents lint)

Safety Model

• Destructive actions default to simulation (--dry-run=true).
• Real execution requires explicit opt-in (--dry-run=false --confirm).
• Multi-target real execution requires additional approval (--yes or interactive confirmation).
• TUI real delete from a group header requires three explicit confirms before execution.
• Soft-delete is default; hard delete is explicit (--hard).
• Operation logs include batch_id for audit and rollback.

Note

Recommended flow: preview first, then real execution with explicit confirmation.

Configuration

Config path resolution:

• $CSM_CONFIG when set
• otherwise ~/.config/codexsm/config.json

Example:

{
  "sessions_root": "~/.codex/sessions",
  "trash_root": "~/.codex/trash",
  "log_file": "~/.codex/codexsm/logs/actions.log",
  "tui": {
    "group_by": "host",
    "source": "sessions",
    "theme": "catppuccin",
    "colors": {
      "keys_label": "#ffffff",
      "keys_key": "#89dceb",
      "border_focus": "#f38ba8"
    }
  }
}

TUI note:

• main panes follow the terminal's default background
• theme colors still control borders, titles, selection, keybar, and preview roles
• bg remains available for local emphasis, such as highlighted action prompts
• semantic state tokens are available for status UI: status_ok, status_warn, status_risk, status_info, accent_group
• group tree supports folding with z (toggle selected session group) and Z (expand all groups)
• pressing d on a group header targets the whole group; real execution uses a dedicated 3/3 confirm flow
• layout is adaptive by width tier: full (>=118), medium (96-117), compact (80-95), ultra (65-79)
• ultra mode switches to a single active pane (tree/preview) with Tab or 1/2, while keeping shared selection state
• minimum supported runtime size is 65x24

Build And Dev

mise install
just build
just check
just bench-session
just bench-cli
just bench-gate
just bench-tui
just stress-cli
codexsm doctor risk --sessions-root ./testdata/fixtures/risky-static/sessions --format json --sample-limit 5
just gen-sessions-extreme
just gen-sessions-large
just check-release 0.3.9

Fixture note:

• testdata/fixtures/rich/ keeps the general regression corpus.
• testdata/fixtures/risky-static/ keeps deterministic risk-oriented samples for doctor risk.
• testdata/fixtures/extreme-static/ keeps a small extreme corpus for oversized meta lines, long single messages, no-final-newline files, mixed corruption, and Unicode-heavy previews.
• Larger stress files are intentionally generated on demand via just gen-sessions-extreme or just gen-sessions-large instead of being committed as multi-megabyte fixtures.
• Lightweight benchmark suites are available through just bench-session, just bench-cli, and just bench-tui; just stress-cli is the heavier local-only smoke path for generated large datasets.

Release build example:

GOEXPERIMENT=jsonv2 go build -ldflags="-X main.version=0.3.9" -o codexsm .

License

BSD 3-Clause. See LICENSE.