https://github.com/mysticaldevil/codexsm
Safety-first local Codex session manager in Go with CLI and TUI
https://github.com/mysticaldevil/codexsm
Last synced: 3 months ago
JSON representation
Safety-first local Codex session manager in Go with CLI and TUI
- Host: GitHub
- URL: https://github.com/mysticaldevil/codexsm
- Owner: MysticalDevil
- License: bsd-3-clause
- Created: 2026-03-02T10:40:36.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-03-20T02:28:38.000Z (4 months ago)
- Last Synced: 2026-03-20T16:14:49.476Z (4 months ago)
- Language: Go
- Size: 748 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Audit: audit/logger.go
- Agents: AGENTS.md
Awesome Lists containing this project
README
# codexsm
`codexsm` is a safety-first local Codex session manager written in Go.
## Quick Links
| Topic | Link |
| --- | --- |
| Architecture | [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) |
| Command Guide | [docs/COMMANDS.md](./docs/COMMANDS.md) |
| Release Checklist | [docs/RELEASE.md](./docs/RELEASE.md) |
| Changelog | [CHANGELOG.md](./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.
```bash
export GOEXPERIMENT=jsonv2
```
## Install
```bash
GOEXPERIMENT=jsonv2 go install github.com/MysticalDevil/codexsm@v0.3.9
```
Or with `mise`:
```bash
GOEXPERIMENT=jsonv2 mise install go:github.com/MysticalDevil/codexsm@v0.3.9
```
## Quick Start
```bash
# 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](./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:
```json
{
"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
```bash
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:
```bash
GOEXPERIMENT=jsonv2 go build -ldflags="-X main.version=0.3.9" -o codexsm .
```
## License
BSD 3-Clause. See [LICENSE](./LICENSE).