Skip to content

codex-setup.md

Latest commit

 

History

History
117 lines (81 loc) · 3.31 KB

codex-setup.md

File metadata and controls

117 lines (81 loc) · 3.31 KB
Raw

Set up Codex Compass for Codex CLI

This is the shortest reliable setup path.

1. Install the binary

From the repository checkout, build and install with Go 1.24 or newer:

make install

Verify the installed binary:

codex-compass --version

The install target writes ~/.local/bin/codex-compass by default. Use a stable, owner-controlled location because Codex hooks store the executable's absolute path. If the binary is moved, run codex-compass enable again in every observed repository. Installation alternatives are documented in install.md.

2. Enable one repository

cd /path/to/your/repository
codex-compass enable

Expected output identifies both the repository and .codex/hooks.json. enable is safe to rerun: it updates Codex Compass handlers and preserves unrelated hooks.

It creates or updates:

.codex/hooks.json     machine-specific hook commands
.session-map/         local events, configuration, and session state
.gitignore            adds .session-map/

The generated hook file includes an absolute local binary path. Review it before committing it; personal installations should normally keep it local.

3. Trust the hooks in Codex

Open Codex in the enabled repository, then:

  1. Run /hooks.
  2. Review SessionStart, UserPromptSubmit, and Stop.
  3. Trust the new project hook definitions.
  4. Start a new Codex session or resume one after trust is granted.

If Codex was running before enable, restart it so the new project hook configuration is loaded.

4. Open the dashboard

In a second terminal, from the same repository:

codex-compass watch

Use Codex normally in the first terminal. Codex Compass refreshes after a turn's final response. The first analysis may take longer because it launches an ephemeral codex exec process.

Verify capture

After completing one Codex turn:

codex-compass status

For a one-shot worker run without the TUI:

codex-compass watch --once

If the dashboard says there are no captured sessions:

  1. Confirm codex-compass enable was run in this repository.
  2. Confirm the three hooks are trusted in /hooks.
  3. Confirm the absolute binary path in .codex/hooks.json still exists.
  4. Restart Codex, then start or resume the session from this repository.
  5. Complete a full prompt/response turn and run codex-compass watch --once.

Model selection

Codex Compass uses the models visible to the authenticated Codex installation:

New projects default to gpt-5.6-luna with medium reasoning. You can change or clear that selection with the commands below.

codex-compass models
codex-compass config --model MODEL
codex-compass config --reasoning EFFORT

Inside the TUI, type /model; choose the model and then its reasoning level. No separate /reasoning command is needed.

Local security checklist

  • Install the binary in a directory only your user can modify.
  • Review the generated absolute hook command before trusting it.
  • Keep .session-map/ private; it contains captured prompts and responses.
  • Do not run an untrusted replacement binary from the path stored in the hook.
  • Rerun codex-compass enable after intentionally moving the executable.

The hook process only writes small local event files. LLM analysis runs later in the watcher, not inside the hook.