Skip to content

Claude Code Observability

Gain complete visibility into every Claude Code session — token usage, costs, tool calls, subagent orchestration, and developer productivity metrics. The Anosys SDK integrates directly into Claude Code's native hook mechanism to capture rich session telemetry with a single install command.

Why Observe Claude Code

Claude Code sessions are powerful but opaque. A single coding session can consume thousands of tokens, spawn subagents, execute shell commands, and edit dozens of files — all with no built-in visibility into cost or behavior.

Challenge What Observability Gives You
Hidden costs Per-session and per-project cost attribution with accurate model pricing
Token sprawl Input/output/cache token breakdowns per turn, per model, and over time
Subagent sprawl Trace subagent spawns, handoffs, and nested tool calls
Debugging failures Structured error logs with API error classification and stack traces
Team accountability Session-level attribution by user, project, branch, and git context
Compliance Optional content redaction — track usage without storing prompts

Two Ways to Integrate

Anosys offers two methods for Claude Code observability. Choose the one that fits your needs:

Method What You Get Setup
AnoSys SDK Hook (recommended) Rich session data — 150+ fields, accurate cost estimates, subagent tracing, content redaction, incremental processing One install command
OTEL-Only Standard OpenTelemetry traces and metrics — lighter weight but fewer data points Manual JSON config

Use both together

The SDK installer can configure OTEL at the same time as the hook, giving you both rich session data and standard OTEL traces in a single setup.

AnoSys SDK Hook — Installation

The SDK integrates via Claude Code's native Stop hook mechanism. When a Claude Code session ends, the hook fires automatically, scans the session transcript, and ships the data to your Anosys workspace.

Prerequisites

  1. Claude Code CLI installed and working
  2. An Anosys account at console.anosys.ai
  3. An API key — In the Anosys Console, navigate to your ingestion channel and go to the API tab. Click Create New API Key to generate your key.

Python Installation (Primary)

Install the package and run the setup wizard:

1
2
pip install anosys-sdk-claude-code
anosys-claude-code install

The installer will prompt you for:

  1. AnoSys API key for logs — Your ingestion API key from the Anosys Console (API tab).
  2. AnoSys API key for OTEL (optional) — Your OpenTelemetry API key from the Anosys Console (OTEL tab). Enables standard OTEL traces alongside the hook data.
  3. Content redaction — When enabled, all conversation content (prompts, responses, thinking) is replaced with REDACTED before being sent. Only metadata and token counts are tracked.

Headless Installation

For CI/CD or automated setups, pass all options via flags:

1
2
3
4
5
anosys-claude-code install \
  --api-key "your_logs_api_key" \
  --otel-key "your_otel_api_key" \
  --redaction \
  --auto-update

JavaScript Installation

If you prefer Node.js, use npx to run the installer directly — no global install needed:

1
npx anosys-sdk-claude-code install

The same interactive prompts apply. For headless installation:

1
2
3
4
npx anosys-sdk-claude-code install \
  --api-key "your_logs_api_key" \
  --otel-key "your_otel_api_key" \
  --redaction

What the Installer Does

The installer safely patches ~/.claude/settings.json to register an AnoSys Stop hook with the {"owner": "anosys"} tag. It:

  • Creates an automatic backup (~/.claude/settings.json.{TIMESTAMP}.bak) before any changes
  • Registers the hook command: anosys-claude-code run
  • Sets environment variables for API keys and optional OTEL configuration
  • Validates your API keys against the Anosys Console before saving

No manual editing of settings.json is required.

CLI Reference

The anosys-claude-code CLI provides commands to manage the hook installation:

install

Install or update the AnoSys hook in your Claude Code settings:

1
2
3
4
5
# Python
anosys-claude-code install

# JavaScript
npx anosys-sdk-claude-code install

Flags:

Flag Description
--api-key KEY AnoSys API key for logs (skips prompt)
--otel-key KEY AnoSys OTEL API key (skips prompt)
--redaction Enable content redaction
--no-redaction Disable content redaction (skips prompt)
--auto-update Automatically update settings.json (skips prompt)
--no-auto-update Print config to stdout instead of writing

status

Check the current installation status and validate API keys:

1
anosys-claude-code status

uninstall

Safely remove the AnoSys hook and related environment variables:

1
anosys-claude-code uninstall

run

Executed automatically by Claude Code when a session ends. You generally do not need to run this manually:

1
anosys-claude-code run

How It Works

When installed, the AnoSys hook fires at the end of every Claude Code session:

%%{init: {"flowchart": {"curve": "linear"}}}%%
graph LR
    A["Claude Code Session Ends"] -->B["Stop Hook Fires"]
    B -->C["Scan ~/.claude/projects/ transcripts"]
    C -->D["Incremental mapping of new messages"]
    D -->E["Calculate pricing & token usage"]
    E -->F["Apply PII redaction (optional)"]
    F -->G["Batch POST to AnoSys"]

    style B stroke:#1e88e5,color:#fff
    style G stroke:#388e3c,color:#fff
  1. Transcript scanning — The hook reads Claude Code's local transcript files from ~/.claude/projects/, tracking which messages have already been processed.
  2. Incremental processing — Only new messages since the last run are mapped and sent, avoiding duplicate data.
  3. Rich extraction — Each message is transformed into a structured payload with 150+ fields covering session metadata, token usage, cost estimates, tool calls, subagent events, and more.
  4. Accurate pricing — Cost estimates use the actual model name and token counts (including cache read/creation tokens) for precise cost attribution.
  5. Optional redaction — When enabled, all user prompts, assistant responses, and thinking blocks are replaced with REDACTED before transmission. Metadata and token counts are preserved.
  6. Batched delivery — Records are batched and sent to your Anosys ingestion endpoint via HTTP POST.

Monitoring Claude Code Desktop App via SSH

The Claude Code Desktop App can be configured to execute the claude CLI over SSH on a remote machine (or even localhost). If the remote host has the AnoSys Claude Code SDK installed, all sessions initiated from the Desktop App are automatically observed.

How It Works

%%{init: {"flowchart": {"curve": "linear"}}}%%
graph LR
    A["Claude Code Desktop App"] -->|SSH| B["Remote Host (claude CLI)"]
    B -->C["AnoSys Stop Hook"]
    C -->D["AnoSys Platform"]

    style A stroke:#1e88e5,color:#fff
    style C stroke:#c62828,color:#fff
    style D stroke:#388e3c,color:#fff
  1. The Desktop App connects to the remote host via SSH and runs claude commands.
  2. Since the claude CLI on the remote host has the AnoSys hook installed in its ~/.claude/settings.json, the hook fires at the end of every session — regardless of whether the session was started from the terminal or the Desktop App.
  3. Session telemetry flows to AnoSys automatically.

Setup

  1. Install the AnoSys SDK on the remote host (the machine running claude CLI):

    1
2
3
    # On the remote host
pip install anosys-sdk-claude-code
anosys-claude-code install

  2. Configure Claude Code Desktop App to use SSH for its CLI backend. In the Desktop App settings, set the remote execution target to your SSH host.

  3. Verify — Run a session from the Desktop App, then check the AnoSys Console. You should see the session telemetry appear within seconds.

Local SSH works too

You can also use SSH to localhost if you want to observe Desktop App sessions on the same machine. The key requirement is that the claude CLI has the AnoSys hook installed.

OTEL-Only Method (Alternative)

If you prefer a lighter-weight integration without the SDK, you can configure Claude Code to export standard OpenTelemetry traces directly.

Setup

Edit or create ~/.claude/settings.json and add the following environment variables:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
    "env": {
        "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
        "OTEL_SERVICE_NAME": "claude-code",
        "OTEL_TRACES_EXPORTER": "otlp",
        "OTEL_METRICS_EXPORTER": "otlp",
        "OTEL_LOGS_EXPORTER": "otlp",
        "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
        "OTEL_EXPORTER_OTLP_ENDPOINT": "YOUR_ANOSYS_OTLP_ENDPOINT"
    }
}

Replace YOUR_ANOSYS_OTLP_ENDPOINT with the OTEL endpoint from your Anosys Console. In your ingestion channel, go to the OTEL tab and copy the endpoint URL (e.g. https://api.anosys.ai/{workspace_id}/cc/{pixel_id}).

OTEL vs. SDK Hook

The OTEL-only method captures standard OpenTelemetry traces and metrics — useful for lightweight monitoring. The SDK hook captures significantly more data (150+ fields vs. standard OTEL attributes), including accurate cost estimates, subagent tracing, and content redaction. For most use cases, we recommend the SDK hook, optionally combined with OTEL.

What Data Gets Captured

The SDK hook captures rich, structured data for every Claude Code session:

Session Metadata

  • Session ID, project name, git branch, working directory
  • Claude Code version, permission mode, session slug
  • OS user, entrypoint, agent type and settings

Token Usage & Cost

  • Input/output/total tokens per turn
  • Cache read and cache creation tokens
  • Incremental token deltas between turns
  • Estimated cost per turn and per session
  • Model name and service tier

Conversation Content

  • User prompts and assistant responses (redactable)
  • Thinking blocks (redactable)
  • Stop reasons and finish reasons
  • Tool use results and tool call metadata

Agent & Tool Tracking

  • Agent ID, name, description, and type
  • Tool use IDs and parent-child relationships
  • Subagent spawn events and hierarchies
  • MCP metadata and hook events

Performance Metrics

  • Time-to-first-token (TTFT) in milliseconds
  • Output tokens per second
  • Turn duration, tool duration, hook duration
  • Classifier duration and counts

Developer Context

  • Custom and AI-generated session titles
  • PR URLs, PR numbers, and repository info
  • File states, written paths, and commands executed
  • Web search and fetch request counts
  • Session tags and attribution surface

What You'll See in Anosys

Once the hook is active, the Anosys Platform automatically processes your Claude Code data and surfaces:

  • Session traces — End-to-end visibility into every Claude Code session, including tool calls, file reads/writes, and command executions.
  • Token usage metrics — Input, output, and cache token counts per session, per project, and over time.
  • Cost dashboards — Per-session and per-project cost estimates with model-level breakdowns. Track spending trends across your team.
  • Subagent visibility — Trace subagent spawns, handoffs, and nested tool hierarchies within complex sessions.
  • Latency analysis — Time-to-first-token, output tokens per second, and turn-level latency breakdowns.
  • Error tracking — API errors, permission issues, and session failures with automatic classification.
  • Developer productivity — Session lengths, prompt counts, tool usage patterns, and code output volume.
  • Anomaly detection — ML-powered baselines that alert on unusual session costs, token spikes, and error patterns.
  • Root cause analysis — Trace failures back through tool calls, model decisions, and configuration changes.
  • Alerts — Context-aware notifications via Slack, email, or webhooks for cost overruns, errors, and performance regressions.
  • Custom dashboards — Build your own views or start with auto-generated dashboards for session health and cost trends.
  • AI Copilot — Ask questions about your Claude Code usage in plain English and get answers backed by your telemetry.

Configuration Reference

Environment Variables (set by the installer)

Variable Description
ANOSYS_HOOK_APIKEY Your AnoSys API key for log ingestion
ANOSYS_HOOK_DRY_RUN Set to true to test without sending data
REDACTION Set to true to redact all conversation content
CLAUDE_CODE_ENABLE_TELEMETRY Set to 1 to enable OTEL export (optional)
OTEL_SERVICE_NAME Service name in OTEL traces (default: claude-code)
OTEL_TRACES_EXPORTER Exporter type for traces (use otlp)
OTEL_METRICS_EXPORTER Exporter type for metrics (use otlp)
OTEL_LOGS_EXPORTER Exporter type for logs (use otlp)
OTEL_EXPORTER_OTLP_PROTOCOL Transport protocol (use http/protobuf)
OTEL_EXPORTER_OTLP_ENDPOINT OTEL ingestion endpoint URL
OTEL_EXPORTER_OTLP_HEADERS OTEL headers including API key

Troubleshooting

I don't see any data in the Anosys Console
  • Run anosys-claude-code status to verify the hook is installed and API keys are valid.
  • Make sure you completed at least one Claude Code session after installing the hook — the hook fires on session end.
  • Confirm that outbound HTTPS traffic to api.anosys.ai is not blocked by a firewall or proxy.
  • Check that ~/.claude/settings.json is valid JSON (no trailing commas or syntax errors).
How do I enable content redaction after installation?

Run the installer again with the --redaction flag: 

1
anosys-claude-code install --redaction --auto-update
The installer is idempotent — it will update the existing configuration without duplicating hooks.

Does the hook slow down my Claude Code sessions?

No. The hook runs after the session ends (on the Stop event), so it does not affect session performance. Processing typically completes in under a second.

Can I use this with Claude Code on remote servers or containers?

Yes — as long as the anosys-sdk-claude-code package is installed and ~/.claude/settings.json contains the hook configuration, telemetry will be exported regardless of environment.

Does this work with the Claude Code Desktop App?

Yes — if you configure the Desktop App to run the claude CLI over SSH (or locally), and the CLI host has the AnoSys hook installed, all Desktop App sessions are automatically observed. See the SSH integration section above.

Can I use the SDK hook and OTEL at the same time?

Yes. The installer offers an optional OTEL API key during setup. When configured, both the rich hook data and standard OTEL traces/metrics are sent to Anosys simultaneously.

What happens to my existing settings.json?

The installer creates an automatic backup (~/.claude/settings.json.{TIMESTAMP}.bak) before every change. Your existing hooks and settings are preserved — only the AnoSys-owned entries are added or updated.

Next Steps