claude-util

CLI utility for logging and analyzing Claude Code sessions for analytics and team visibility.

Installation

npm install -g claude-util

Quick Start

# Full install (prompts for email + API key, installs hooks)
claude-util install

This will:

1. Prompt for your email and API key
2. Save configuration to ~/.claude-util/config.json
3. Install hooks in ~/.claude/settings.json

Commands

| Command | Description | |---------|-------------| | claude-util install | Full install (setup + hooks in one command) | | claude-util setup | Configure credentials only | | claude-util install-hooks | Install Claude Code hooks | | claude-util uninstall-hooks | Remove Claude Code hooks | | claude-util uninstall | Complete removal | | claude-util config | View current configuration | | claude-util config set <key> [value] | Set a config value | | claude-util version | Print version info | | claude-util log | Log an interaction (called by hooks) |

Configuration

Config is stored in ~/.claude-util/config.json:

{
  "username": "[email protected]",
  "api_key": "sk-xxx",
  "server_url": "https://your-server.com"
}

Config Keys

• username / email - Your email address
• api-key / apikey - API key for authentication
• server-url / server_url - Server URL (optional)

Server URL Priority

1. CLAUDE_UTIL_SERVER_URL environment variable
2. server_url in config file
3. Default: http://localhost:3000

How It Works

The tool installs a hook in Claude Code's ~/.claude/settings.json:

{
  "hooks": {
    "Stop": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "npx --yes claude-util log"
      }]
    }]
  }
}

When a Claude Code session ends, the hook runs and:

1. Reads the session transcript (JSONL file)
2. Extracts metrics (tokens, tools, files, bash commands, etc.)
3. Sends data to the configured server via POST /api/log

Metrics Tracked

• Tokens: Input, output, cache read/write
• Tools: Which tools were used and how many times
• Files: Files read and modified
• Bash: Commands run, including test/build/git analysis
• Session: Duration, turn count, thinking characters
• Skills: Which skills were invoked

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Link for local testing
npm link

# Test
npm test