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 tracking 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
Tracking status (global or 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.

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

Track all projects on your machine

$codeusage config scope project

Track only the current project

$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 provider

Manage AI coding tool providers. Codeusage supports multiple providers simultaneously.

Terminal

$codeusage provider list

List all available providers

$codeusage provider current

Show the currently active provider

$codeusage provider add codex

Add hooks for an additional provider

$codeusage provider switch codex

Switch to a different provider

codeusage logs

View CLI error and diagnostic logs. Useful for debugging when tasks aren't syncing or hooks aren't firing.

Terminal

$codeusage logs

Show recent error logs

$codeusage logs --all

Show all log levels (error, warn, info, debug)

$codeusage logs --level warn

Filter by log level

$codeusage logs -n 100

Show last 100 log entries

$codeusage logs --path

Print log file location

$codeusage logs --clear

Clear all logs

codeusage logout

Disconnect from Codeusage and remove all local configuration.

Terminal

$codeusage logout

Disconnect (with confirmation)

$codeusage logout --force

Disconnect without confirmation

Prompt Guard

Prompt Guard is a security feature that scans your prompts locally before they're sent to the AI model, detecting and blocking potential credential leaks like API keys, database passwords, and private keys.

How It Works

When enabled, Prompt Guard scans your prompts locally before they're sent to the AI. It checks for 44 built-in patterns covering common credential types:

AWS access keys and secret keys
Database URLs (PostgreSQL, MySQL, MongoDB, Redis)
Private keys (RSA, EC, generic PEM blocks)
API tokens (GitHub, Slack, Stripe, OpenAI, Anthropic, etc.)
Environment variables with sensitive key names

If a credential is detected, the prompt is blocked and you'll see a warning message explaining what was found.

Setup

Prompt Guard requires linking your CLI to your Codeusage workspace. After running codeusage init, enable Prompt Guard:

Terminal

$codeusage guard enable

Enable Prompt Guard and sync patterns

$codeusage guard status

Check Prompt Guard status and cache info

Patterns are cached locally at ~/.codeusage/patterns.json and refreshed every 7 days. You can also manage patterns from the Guard settings page in your dashboard.

Managing Patterns

You can enable or disable individual patterns or entire categories from the Guard settings page in your Codeusage dashboard. Changes sync automatically to all connected CLI instances.

Pattern Categories

• AWS Credentials
• Database Connection Strings
• Private Keys
• API Keys & Tokens
• Environment Variables

Granular Control

Enable/disable entire categories at once, or toggle individual patterns. For example, block Stripe keys but allow MongoDB URLs.

CLI Commands

Terminal

$codeusage guard enable

Enable Prompt Guard protection

$codeusage guard disable

Disable Prompt Guard

$codeusage guard status

Show current status and pattern count

$codeusage guard sync

Force refresh patterns from server

$codeusage guard list

List all active patterns by category

$codeusage guard test "sk-live-abc123"

Test a string against patterns (dry run)

Privacy

Prompt Guard runs entirely on your local machine. Your prompts are never sent to Codeusage servers — only pattern configuration is synced. When a credential is detected, we log the pattern match (e.g., "AWS Access Key detected") but never the actual credential value.

Bypassing for Specific Prompts

If you need to intentionally include a credential (e.g., discussing credential formats), you can temporarily disable Prompt Guard:

$ codeusage guard disable

Remember to re-enable it afterward with codeusage guard enable.

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
tracking_scope	"global" or "project" — what gets tracked	config scope
project_overrides	Per-directory project name mappings	project set

Tracking Scope

Codeusage supports two tracking scopes:

Global Scope

Tracks all AI coding activity across all projects on your machine.

codeusage config scope global

Project Scope

Tracks only the current project. Useful when you want selective tracking.

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 you're connected
Check error logs: codeusage logs to see what went wrong
Check if the directory is ignored: codeusage project current
Try manual sync: codeusage sync
Verify API key is valid: codeusage status shows connection status

Tracking not active

If codeusage status shows tracking is not active:

$ codeusage init --force

This re-runs the setup wizard and re-enables tracking.

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 disconnect

$codeusage init

Start fresh setup

File Locations Reference

File	Location
Config	~/.codeusage/config.json
Buffer	~/.codeusage/buffer/
Session State	~/.codeusage/session-state/
Patterns Cache	~/.codeusage/patterns.json
Guard State	~/.codeusage/guard.json
Logs	~/.codeusage/logs/error.log

Need More Help?

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