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.

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

SpanKindWhat it represents
TurnWORKFLOWOne root trace for each main-thread user prompt
Model phaseLLMModel input/output, timing, token usage, and available reasoning summaries
Tool callTOOLCommand or tool input, output, status, and duration
SubagentAGENTSubagent 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.


Configuration

The hooks read each setting from the environment first, then from ~/.config/neatlogs/config.json (written by setup):

VariableConfig file keyPurpose
NEATLOGS_API_KEYapi_keyYour Neatlogs project key
NEATLOGS_ENDPOINTendpointIngest base URL (default: https://ingest.neatlogs.com)
NEATLOGS_DEBUGdebugSet 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 --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

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

On this page

Ask Neatlogs AI

Answers from the docs

How can I help?

Ask anything about instrumenting, tracing, or the Neatlogs dashboard.