Codex Hooks

@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.

Note

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 --global

Global 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 --project

The 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 --version

neatlogs-codex hook is the runtime entry point used by Codex hooks; you do not run it manually.

Troubleshooting

Restart Codex after installing or updating the package.
Run neatlogs-codex doctor --global and fix any missing key or hook reported.
Open /hooks in 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/codex