Codex Compass

Codex Compass is a local terminal companion for Codex CLI. It turns one Codex session into a concise map of workstream intents, approaches, results, decisions, verification, and risks without mirroring tool calls or file diffs.

Repository
└── Codex session
    ├── Workstream A  ███··█  T06
    ├── Workstream B  ···██·  T05

The Go binary is named codex-compass.

Install

Requirements:

• An authenticated codex CLI on PATH
• A Git repository in which Codex project hooks can be trusted
• Go 1.24 or newer when building from source

Supported source-build targets:

• Linux and WSL on amd64 or arm64
• macOS on Intel or Apple Silicon
• Windows on amd64 or arm64

All six targets are compile-checked. The interactive workflow and PTY snapshots are validated on Linux/WSL; the development-only PTY helper requires a POSIX environment and is not intended to run in native Windows PowerShell.

On Linux, WSL, or macOS, build and install with:

make install

By default this installs codex-compass in ~/.local/bin. Add that directory to PATH if necessary, then verify the installation:

export PATH="$HOME/.local/bin:$PATH"
codex-compass --version

On Windows PowerShell, build the executable directly:

go build -trimpath -buildvcs=false -o bin/codex-compass.exe ./cmd/codex-compass
.\bin\codex-compass.exe --version

See docs/install.md for custom install locations, upgrades, and uninstalling.

Quickstart

The quickest complete setup uses Linux, macOS, or WSL and an authenticated Codex CLI.

1. Clone, validate, and install the project:

   git clone https://github.com/cloudant42/codex-compass.git
   cd codex-compass
   make check
   make install
   export PATH="$HOME/.local/bin:$PATH"

2. Create a disposable Git project and enable its hooks:

   demo="$(mktemp -d)"
   git -C "$demo" init
   cd "$demo"
   codex-compass enable

3. Start codex-compass watch in one terminal. In a second terminal, start Codex in the same directory, open /hooks, and trust the three project hooks.

4. Ask Codex to create a small file, revise it, and add a test. After each completed turn, confirm that Compass adds a step and exposes its intent, result, decisions, verification, and unresolved risks.

Connect it to Codex

See docs/codex-setup.md for hook setup, trusting hooks in Codex, running the watcher, model selection, and troubleshooting.

Development

git clone https://github.com/cloudant42/codex-compass.git
cd codex-compass
make build

make test   # unit tests
make check  # tests and Go vet

For terminal UI changes, use the codex-compass-terminal-check skill to exercise the real binary at narrow and wide sizes.

Data and privacy

Codex Compass is local and single-user. Captured prompts, responses, analyses, and summaries stay under .session-map/; keep that directory private and out of Git. A separate local catalog stores routing metadata only.

Analysis uses the authenticated Codex CLI through an isolated, read-only codex exec sidecar. The sidecar's own hooks are suppressed to prevent recursive capture. See docs/architecture.md for the data flow and docs/semantic-graph.md for the derived session graph.

License

Codex Compass is available under the MIT License.