Claude Code Tracing - Atatus Docs

Tracing for Claude Code records every prompt as a trace, with the tools it invoked nested beneath it. This page covers both install routes and the Claude Code specifics.

Before you start

Each route needs a different thing already on your machine:

Route	Needs
Installer	Python 3.9 or newer
Plugin	`jq` and `curl`

The plugin is written in shell, so jq builds every payload and curl sends it. Neither has a fallback. Install jq with sudo apt-get install -y jq on Debian or Ubuntu, sudo dnf install -y jq on Fedora or RHEL, or brew install jq on macOS.

The plugin setup checks for both commands and prints the right install command for your system before it changes anything, so you do not have to work this out from an error later.

Install with the installer

On macOS or Linux:

curl -sSL https://raw.githubusercontent.com/atatus/atatus-coding-harness-tracing/main/install.sh | bash -s -- claude

On Windows:

iwr -useb https://raw.githubusercontent.com/atatus/atatus-coding-harness-tracing/main/install.bat -OutFile $env:TEMP\install.bat
& $env:TEMP\install.bat claude

The installer prompts for your license key and project name, stores them in ~/.atatus/harness/config.json, and registers the hooks in ~/.claude/settings.json. Add --with-skills to also link the manage-claude-code-tracing skill into the current directory, so Claude can help you change the tracing configuration interactively.

Install from the plugin marketplace

Claude Code can also install tracing as a plugin. The marketplace lives in the same repository as the install script, so there is no second source to add:

claude plugin marketplace add atatus/atatus-coding-harness-tracing
claude plugin install atatus-claude-code-tracing@atatus-coding-harness-tracing

The marketplace flow registers the hooks but skips the setup wizard, so it does not know your license key. Set the values yourself in ~/.claude/settings.json under env, or no traces are sent.

Add an env block with your credentials:

{
  "env": {
    "ATATUS_PROJECT_NAME": "your-project-name",
    "ATATUS_API_KEY": "lic_xxxxxxxxxxxxxxxx",
    "ATATUS_LOG_PROMPTS": "true",
    "ATATUS_LOG_TOOL_DETAILS": "true",
    "ATATUS_LOG_TOOL_CONTENT": "false"
  }
}

ATATUS_OTLP_ENDPOINT is optional. Set it only if you are running Atatus on-premise. The three logging values above match the wizard’s defaults, so leaving a flag out gives you the same result as setting it to the value shown.

Do not install the plugin and the standalone package at the same time. Both register hooks, both fire on every event, and every span is recorded twice, which doubles your token and cost figures. Pick one.

What gets captured

Claude Code exposes the widest set of hook events of any supported tool, so its traces are the most detailed:

Span	Kind	What it represents
`Turn N`	`chat`	One prompt and its response. Carries the model name, prompt and completion tokens, cache read and write tokens, and cost.
`<tool>`	`tool`	One tool call such as `Read`, `Edit`, or `Bash`. A child of the turn that invoked it. Failed calls carry an error status.
`Session`	`chain`	Groups the turns in one coding session.

Where things live

Item	Path
Hook config file	`~/.claude/settings.json`
Credentials	`~/.atatus/harness/config.json`
State directory	`~/.atatus/harness/state/claude-code/`
Log file	`~/.atatus/harness/logs/claude-code.log`

Sixteen hook events are registered: SessionStart, SessionEnd, UserPromptSubmit, UserPromptExpansion, PreToolUse, PostToolUse, PostToolUseFailure, Stop, StopFailure, SubagentStart, SubagentStop, Notification, PermissionRequest, PermissionDenied, PreCompact, and PostCompact.

Notes

A turn that you cancel before it finishes has no token data, because Claude Code reports usage only when a response completes. The turn still appears in the trace, marked as closed by a fail-safe, so you can see that it happened. Cancelling prompts is normal, so expect some turns to carry no cost.

Uninstall

Remove the hooks from ~/.claude/settings.json and leave everything else in place:

curl -sSL https://raw.githubusercontent.com/atatus/atatus-coding-harness-tracing/main/install.sh | bash -s -- uninstall claude

If you installed the plugin instead:

claude plugin uninstall atatus-claude-code-tracing@atatus-coding-harness-tracing
claude plugin marketplace remove atatus-coding-harness-tracing

See Uninstall for the full-wipe option.

​Before you start

​Install with the installer

​Install from the plugin marketplace

​What gets captured

​Where things live

​Notes

​Uninstall

Before you start

Install with the installer

Install from the plugin marketplace

What gets captured

Where things live

Notes

Uninstall