Claude Code Plugin

@neatlogs/claude-code captures your Claude Code sessions as traces. Every prompt, tool call, thinking block, and model response is recorded and sent to Neatlogs through Claude Code's hook system — so you can review what your agent did, how long each step took, and what it cost, the same way you review your application's traces.

Install

npm install -g @neatlogs/claude-code

Set up

neatlogs-claude-code setup --global --api-key YOUR_PROJECT_KEY

This does two things:

Saves your API key to ~/.config/neatlogs/config.json
Registers hooks in ~/.claude/settings.json for all Claude Code lifecycle events

Restart Claude Code afterward. From then on, every session is traced automatically — no per-project configuration needed.

YOUR_PROJECT_KEY is the same Neatlogs project API key you use for the SDK. Sessions land in that project alongside your application traces.

What gets captured

Each Claude Code session becomes one trace with a clear span tree:

Span	Kind	What it represents
Session	`WORKFLOW`	The root span for the whole session
Turn	`CHAIN`	One per user prompt, named with the truncated prompt text
Tool call	`TOOL`	Each Read, Edit, Bash, etc. — with inputs, outputs, and duration
LLM	`LLM`	Model responses, with token counts and thinking content
Subagent	`AGENT`	Work done by any spawned subagent

Because it's a normal Neatlogs trace, everything the dashboard offers — the span tree, the timeline, cost and latency breakdowns, comments, and the per-trace AI assistant — works on your coding sessions too.

Commands

neatlogs-claude-code setup [--global|--project] [--api-key KEY]  # Register hooks
neatlogs-claude-code uninstall [--global|--project]              # Remove hooks
neatlogs-claude-code --version                                    # Print version

Use --global to trace all sessions on your machine, or --project to enable it only for the current project (writes to the project's .claude/settings.json).

Configuration

The plugin reads its API key from, in order of precedence:

The NEATLOGS_API_KEY environment variable
~/.config/neatlogs/config.json (written by setup)

It also respects NEATLOGS_ENDPOINT and NEATLOGS_DEBUG=true.

Troubleshooting

Hooks not firing. Restart Claude Code after running setup — hooks are loaded at startup.

EACCES permission error on install. Either use a Node version manager like nvm (which handles permissions for you), or point npm at a user-writable global directory:

npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Uninstall

neatlogs-claude-code uninstall --global
npm uninstall -g @neatlogs/claude-code