ai-usage

A CLI tool to forward Claude hooks payloads to a remote server.

Installation

This package can be used directly with bunx without installation:

bunx ai-usage http://example.com

Usage

The CLI reads JSON payloads from stdin and forwards them to the specified remote server. It will wait for input if you run it without providing data.

Basic usage with echo:

`echo '{"event":"preToolUse","sessionId":"test","workingDirectory":"/","timestamp":"2024-01-20T10:00:00Z","toolName":"Bash","toolInput":{}}' | bunx ai-usage http://example.com`

Using with a file:

bunx ai-usage http://example.com < payload.json

Testing with httpbin:

echo '{"event":"preToolUse","sessionId":"test","workingDirectory":"/","timestamp":"2024-01-20T10:00:00Z","toolName":"Bash","toolInput":{}}' | bunx ai-usage http://httpbin.org/post

With Claude Hooks

Configure Claude to use this tool in your hooks configuration:

{
  "hooks": {
    "preToolUse": {
      "command": "bunx ai-usage http://your-server.com/hooks"
    },
    "postToolUse": {
      "command": "bunx ai-usage http://your-server.com/hooks"
    },
    "userPromptSubmit": {
      "command": "bunx ai-usage http://your-server.com/hooks"
    }
  }
}

Features

• Automatic User Identification: The CLI automatically reads the user's email from ~/.claude.json and adds it to the payload as user_email field
• Non-blocking: Network errors and timeouts never prevent Claude from continuing
• Fast: 5-second timeout ensures quick response
• Type-safe: Written in TypeScript with full type definitions

Exit Codes

• 0: Success - payload forwarded successfully (or any network/server error to avoid blocking Claude)
• 1: Error - invalid command line arguments or invalid JSON input
• 2: Blocked - server explicitly indicated the action should be blocked

Note: Network errors, timeouts, and server errors will NOT block Claude Code from continuing. The tool only returns non-zero exit codes for explicit blocking responses or invalid usage.

Server Response

The remote server can return a JSON response with:

{
  "shouldBlock": boolean,     // If true, CLI exits with code 2
  "errorMessage": string       // Error message to display
}

Development

# Install dependencies
bun install

# Run CLI in development
bun run dev http://example.com

# Build standalone binary
bun run build