Skip to content

README.md

Latest commit

 

History

History
259 lines (177 loc) · 7.42 KB

README.md

File metadata and controls

259 lines (177 loc) · 7.42 KB

AgenTrace CLI

A CLI tool to send Claude Code sessions to the AgenTrace server.

Overview

AgenTrace is a self-hosted service that enables teams to review Claude Code conversations. Since Claude Code logs contain source code and environment information, AgenTrace is designed to run on your local machine or internal network rather than on the public internet.

This CLI uses Claude Code's hooks feature to automatically send session data to your AgenTrace server.

Setup

1. Start the Server

# Using Docker (recommended)
docker run -d --name agentrace -p 9080:9080 -v $(pwd)/data:/data satetsu888/agentrace:latest

Docker Hub: https://hub.docker.com/r/satetsu888/agentrace

2. Initialize the CLI

npx agentrace init --url http://localhost:9080

A browser window will open displaying the registration/login page. After registration, hooks are automatically configured.

That's it! When you use Claude Code, sessions will be automatically sent to AgenTrace.

Commands

Command Description
agentrace init --url <url> Initial setup + hooks installation
agentrace init --url <url> --proxy <proxy> Setup with proxy
agentrace init --url <url> --local Setup for current project only
agentrace login Open the web dashboard
agentrace send Send transcript diff (used by hooks)
agentrace on Enable hooks
agentrace on --local Enable hooks for current project
agentrace off Disable hooks
agentrace off --local Disable hooks for current project
agentrace uninstall Remove hooks and configuration
agentrace uninstall --local Remove project-local settings only
agentrace doctor Check configuration and server status

Command Details

init

Sets up the server connection and installs Claude Code hooks.

# Global setup (all projects)
npx agentrace init --url http://localhost:9080

# Project-local setup (current project only)
npx agentrace init --url http://localhost:9080 --local

# Project-local with separate config file
npx agentrace init --url http://localhost:9080 --local --separate-local-config

Process flow:

  1. Opens the server's registration/login page in browser
  2. After registration, API key is automatically retrieved
  3. Claude Code hooks are configured

Options:

Option Description
--url <url> Server URL (required)
--proxy <url> HTTP/HTTPS proxy URL
--local Install hooks/MCP for current project only
--separate-local-config Store config in project directory (requires --local)

login

Issues a login URL for the web dashboard and opens it in browser.

npx agentrace login

on / off

Toggle hooks enabled/disabled. Configuration is preserved.

# Temporarily stop sending (global)
npx agentrace off

# Resume sending (global)
npx agentrace on

# For project-local settings
npx agentrace off --local
npx agentrace on --local

uninstall

Completely removes hooks and configuration files.

# Remove global settings
npx agentrace uninstall

# Remove project-local settings only
npx agentrace uninstall --local

doctor

Displays configuration status and checks server connectivity.

npx agentrace doctor

Output example:

AgenTrace Doctor

================

CLI Version: 0.1.0

Configuration:
  Global config: /Users/you/.agentrace/config.json
    Status: ✓ Found

  Local config: /path/to/project/.agentrace/config.json
    Status: ✓ Found

  Active config: Local (/path/to/project/.agentrace/config.json)
  Server URL: http://localhost:9080
  API Key: agtr_xxx****xxxx

Server Status:
  Connection: ✓ Connected
  Server Version: v0.1.0

send

This command is automatically called by Claude Code's Stop hook. You normally don't need to run it manually.

Configuration Files

Config Loading Priority

The CLI loads configuration in the following order:

  1. Local config: Searches from the current directory up to parent directories for .agentrace/config.json
  2. Global config: ~/.agentrace/config.json

This means even when you're in a subdirectory of a project, the project's local config will be used.

Use agentrace doctor to see which config is currently active.

File Locations

Configuration is stored in the following locations:

File Location
AgenTrace config ~/.agentrace/config.json
Cursor data ~/.agentrace/cursors/
Claude Code hooks ~/.claude/settings.json
MCP servers ~/.claude.json

Project-Local Configuration

With the --local option, hooks and MCP are configured per-project:

File Location
Claude Code hooks {project}/.claude/settings.json
MCP servers ~/.claude.json (projects.{path}.mcpServers)
Config (optional) {project}/.agentrace/config.json

To also store the config locally, use --separate-local-config:

npx agentrace init --url http://localhost:9080 --local --separate-local-config

Note: Add .agentrace/ to your .gitignore when using --separate-local-config to avoid committing API keys.

How It Works

┌─────────────────┐
│   Claude Code   │
│  (Stop hook)    │
└────────┬────────┘
         │ npx agentrace send
         ↓
┌─────────────────┐
│  AgenTrace CLI  │
│  Extract & Send │
└────────┬────────┘
         │ POST /api/ingest
         ↓
┌─────────────────┐
│ AgenTrace Server│
│   Save to DB    │
└─────────────────┘
  • Only the transcript diff is sent to the server when a Claude Code conversation ends
  • Errors do not block Claude Code's operation by design

Proxy Configuration

If you need to connect through an HTTP proxy, you can configure it in several ways:

1. Using the --proxy Option

npx agentrace init --url http://localhost:9080 --proxy http://proxy.example.com:8080

For proxies requiring authentication:

npx agentrace init --url http://localhost:9080 --proxy http://user:pass@proxy.example.com:8080

2. Using Environment Variables

If proxy_url is not set in the config file, the CLI will check the following environment variables (in order):

  1. HTTPS_PROXY
  2. https_proxy
  3. HTTP_PROXY
  4. http_proxy
export HTTPS_PROXY=http://proxy.example.com:8080
npx agentrace send

Priority: Config file > Environment variables

Requirements

  • Node.js 18 or later
  • Claude Code installed

License

MIT