Codex Hooks
Capture Codex coding sessions as traces in Neatlogs.
@neatlogs/codex captures Codex sessions through lifecycle hooks. Each main-thread
user prompt becomes a Neatlogs trace containing its model phases, tool calls, and
subagent work, so you can inspect the coding agent separately from the application
code it edits.
This package traces Codex itself. To teach Codex how to add Neatlogs to your application, install the separate Agent Skills.
Install and set up
Requires Node.js 18 or newer.
npm install -g @neatlogs/codex@latest
neatlogs-codex setup --global --api-key YOUR_PROJECT_KEY
neatlogs-codex status --global
neatlogs-codex doctor --globalGlobal setup stores the project API key in ~/.config/neatlogs/config.json with
user-only permissions and registers the supported lifecycle hooks in
~/.codex/hooks.json. Restart Codex, open /hooks, and review and trust the
Neatlogs hook definitions.
For only the current repository, run this from its root instead:
neatlogs-codex setup --project --api-key YOUR_PROJECT_KEY
neatlogs-codex doctor --projectThe project setup writes .codex/hooks.json; the API key remains in the shared
Neatlogs config file.
What gets captured
| Span | Kind | What it represents |
|---|---|---|
| Turn | WORKFLOW | One root trace for each main-thread user prompt |
| Model phase | LLM | Model input/output, timing, token usage, and available reasoning summaries |
| Tool call | TOOL | Command or tool input, output, status, and duration |
| Subagent | AGENT | Subagent model and tool work nested under its parent turn |
Session, permission, compaction, stop, and failure lifecycle events enrich the same trace. The package redacts common secret-bearing fields and does not export encrypted reasoning content, transcript paths, repository URLs, or account data.
Commands
neatlogs-codex setup [--global|--project] [--api-key KEY]
neatlogs-codex status [--global|--project]
neatlogs-codex doctor [--global|--project]
neatlogs-codex uninstall [--global|--project]
neatlogs-codex --versionneatlogs-codex hook is the runtime entry point used by Codex hooks; you do not
run it manually.
Configuration
The hooks read each setting from the environment first, then from
~/.config/neatlogs/config.json (written by setup):
| Variable | Config file key | Purpose |
|---|---|---|
NEATLOGS_API_KEY | api_key | Your Neatlogs project key |
NEATLOGS_ENDPOINT | endpoint | Ingest base URL (default: https://ingest.neatlogs.com) |
NEATLOGS_DEBUG | debug | Set to true for debug diagnostics |
For an EU project, set the endpoint to https://eu.ingest.neatlogs.com. Adding
"endpoint": "https://eu.ingest.neatlogs.com" to the config file applies it to
every Codex session without changing your shell environment.
Troubleshooting
- Restart Codex after installing or updating the package.
- Run
neatlogs-codex doctor --globaland fix any missing key or hook reported. - Open
/hooksin Codex and confirm the Neatlogs hooks are trusted. - Confirm you used the API key for the Neatlogs project where you expect the session traces to appear.
See the package repository for the full verification workflow and implementation details.
Uninstall
neatlogs-codex uninstall --global
npm uninstall -g @neatlogs/codexUse --project instead of --global when the hooks were registered only in the
current repository. Uninstalling hooks does not delete the shared
~/.config/neatlogs/config.json file.
