Getting Started

Codeusage is a CLI tool that automatically tracks your AI coding tool usage and sends telemetry to your team dashboard. It captures metadata only — no prompts, no code, no sensitive data.

Installation

Install the Codeusage CLI globally using bun:

$ bun add -g codeusage-cli

Or using other package managers:

Terminal

$bun add -g codeusage-cli

# bun

$npm install -g codeusage-cli

# npm

$yarn global add codeusage-cli

# yarn

$pnpm add -g codeusage-cli

# pnpm

Quick Start

After installation, initialize Codeusage to connect to your workspace:

$ codeusage init

The init command will guide you through the setup process:

Enter your workspace API key (get it from your dashboard)
Enter your developer name/alias
Choose hook scope (global or project-specific)

Once initialized, tracking is automatic. Every time you complete a task with Claude Code, Codeusage sends the metadata to your dashboard.

Verify Setup

Check your configuration status:

$ codeusage status

This shows:

Connection status and masked API key
Your developer alias
Hook registration status (global and project)
Current project mapping
Number of buffered tasks (if any)

Commands

Complete reference for all Codeusage CLI commands.

codeusage init

Initialize Codeusage and connect to your workspace. This registers hooks with your AI coding tool.

Terminal

$codeusage init

# Interactive setup wizard

$codeusage init --force

# Reinitialize even if already configured

codeusage status

Display current configuration and connection status.

$ codeusage status

codeusage project

Manage project mappings. By default, Codeusage detects projects from git remotes. Use these commands to override or customize.

Terminal

$codeusage project current

# Show project for current directory

$codeusage project set my-project

# Set project name for current directory

$codeusage project list

# List all project mappings

$codeusage project ignore

# Ignore current directory (stop tracking)

$codeusage project unignore

# Remove override for current directory

codeusage config

View and modify CLI configuration settings.

Terminal

$codeusage config

# Show current configuration

$codeusage config show

# Same as above

$codeusage config scope global

# Change hook scope to global

$codeusage config scope project

# Change hook scope to project-only

$codeusage config alias john

# Change developer alias

$codeusage config set-key cu-ws-xxx

# Update workspace API key

codeusage sync

Manually flush buffered tasks to the server. Tasks are automatically buffered when offline and synced when connection is restored.

$ codeusage sync

codeusage logout

Disconnect from Codeusage and remove all local configuration. This unregisters hooks and clears buffered tasks.

Terminal

$codeusage logout

# Disconnect (with confirmation)

$codeusage logout --force

# Disconnect without confirmation

Configuration

Config File Location

Codeusage stores configuration in ~/.codeusage/config.json. This file is managed by the CLI — you typically don't need to edit it manually.

Configuration Options

Option	Description	Command
workspace_key	Your workspace API key	config set-key
developer_alias	Your display name on the dashboard	config alias
hook_scope	"global" or "project" — where hooks are registered	config scope
project_overrides	Per-directory project name mappings	project set

Hook Scopes

Codeusage supports two hook scopes:

Global Scope

Hooks are registered in ~/.claude/settings.json. Tracks all projects on your machine.

codeusage config scope global

Project Scope

Hooks are registered in .claude/settings.json. Tracks only the current project.

codeusage config scope project

Project Detection

Codeusage detects projects in the following priority order:

Manual override — set via codeusage project set
Git remote — extracted from git remote get-url origin
Default project — fallback set during init
Directory name — last resort, path.basename(cwd)

Ignoring Directories

To exclude a directory from tracking (e.g., personal projects):

$ codeusage project ignore

This sets the project mapping to a special __ignored__ value. Tasks in ignored directories are silently skipped.

Troubleshooting

Tasks not appearing on dashboard

Run codeusage status to verify hooks are registered
Check if the directory is ignored: codeusage project current
Try manual sync: codeusage sync
Verify API key is valid: codeusage status shows connection status

Hooks not registered

If codeusage status shows hooks are not registered:

$ codeusage init --force

This re-runs the setup wizard and re-registers hooks.

Buffered tasks not syncing

Tasks are buffered when offline or when the API is unreachable. To manually flush:

$ codeusage sync

Buffer location: ~/.codeusage/buffer/

Wrong project name

If tasks are being attributed to the wrong project:

Terminal

$codeusage project current

# See current project

$codeusage project set correct-name

# Override with correct name

Reset everything

To completely reset Codeusage and start fresh:

Terminal

$codeusage logout --force

# Remove all config and hooks

$codeusage init

# Start fresh setup

File Locations Reference

File	Location
Config	~/.codeusage/config.json
Buffer	~/.codeusage/buffer/
Session State	~/.codeusage/session-state/
Claude Code Hooks (global)	~/.claude/settings.json
Claude Code Hooks (project)	.claude/settings.json

Need More Help?

If you're still experiencing issues, contact us at info@codeusage.dev