copilot-cli-wakatime

WakaTime integration for GitHub Copilot CLI. Track AI coding activity and time spent.

Features

• Automatic time tracking for Copilot CLI sessions
• Hooks into session lifecycle events (start, tool use, end)
• 60-second heartbeat rate limiting per project
• Cross-platform support (macOS, Linux, Windows)
• Zero-config after setup

Prerequisites

1. WakaTime account and API key
2. WakaTime API key configured in ~/.wakatime.cfg:

   [settings]
   api_key = your-api-key-here

3. GitHub Copilot CLI installed
4. wakatime-cli installed and available in PATH

Installation

# Install the package globally
npm install -g @geeknees/copilot-cli-wakatime

# Navigate to your project directory
cd /path/to/your/project

# Initialize hooks configuration
copilot-cli-wakatime init

This creates .github/hooks/wakatime.json in your project with the necessary hook configuration.

How It Works

┌─────────────────────────────────────────────────────────────┐
│                  Copilot CLI Session                         │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                    Hook Events                               │
│   • sessionStart  - When session begins                      │
│   • postToolUse   - After each tool execution                │
│   • sessionEnd    - When session ends                        │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│              copilot-cli-wakatime hook                       │
│   1. Receive event with payload (stdin)                      │
│   2. Skip if toolName starts with "wakatime-"                │
│   3. Detect Git repository root                              │
│   4. Check 60-second rate limit (per project)                │
│   5. Send heartbeat to WakaTime                              │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                   WakaTime Dashboard                         │
│   View your AI coding metrics at wakatime.com                │
└─────────────────────────────────────────────────────────────┘

Hook Events

| Event | Purpose | |-------|---------| | sessionStart | Triggered when a Copilot CLI session starts | | postToolUse | Triggered after each tool execution | | sessionEnd | Triggered when a Copilot CLI session ends |

Entity Tracking

The plugin sends heartbeats with:

• Entity: .copilot-cli.ts (virtual file in repository root)
• Project: Repository name (from Git root)
• Plugin: copilot-cli-wakatime/0.1.0

Configuration

Project Setup

Run copilot-cli-wakatime init in your project to create .github/hooks/wakatime.json:

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "command",
        "bash": "copilot-cli-wakatime hook sessionStart",
        "timeoutSec": 10
      }
    ],
    "postToolUse": [
      {
        "type": "command",
        "bash": "copilot-cli-wakatime hook postToolUse",
        "timeoutSec": 10
      }
    ],
    "sessionEnd": [
      {
        "type": "command",
        "bash": "copilot-cli-wakatime hook sessionEnd",
        "timeoutSec": 10
      }
    ]
  }
}

Debug Mode

Enable debug output:

copilot-cli-wakatime hook sessionStart --debug

Debug information includes:

• Event type
• Tool name
• Working directory
• Repository root
• Project name
• WakaTime CLI exit status

Files & Locations

| File | Purpose | |------|---------| | .github/hooks/wakatime.json | Hook configuration (per project) | | ~/.wakatime.cfg | WakaTime API key and settings | | ~/.local/state/copilot-wakatime/* | Rate limiting state files | | .copilot-cli.ts | Virtual entity file (auto-created in repo root) |

The state directory follows XDG Base Directory specification and can be customized via XDG_STATE_HOME.

Development

# Clone the repository
git clone https://github.com/geeknees/copilot-cli-wakatime
cd copilot-cli-wakatime

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

Project Structure

copilot-cli-wakatime/
├── src/
│   ├── cli.ts            # Main entry point
│   ├── hook.ts           # Hook event handler
│   ├── init.ts           # Hook configuration setup
│   └── util.ts           # Utilities (rate limiting, Git detection)
├── test/
│   ├── hook.test.ts      # Hook tests
│   ├── init.test.ts      # Init tests
│   └── util.test.ts      # Utility tests
├── package.json
├── tsconfig.json
└── README.md

Commands

| Command | Description | |---------|-------------| | copilot-cli-wakatime init | Create hooks configuration in current project | | copilot-cli-wakatime init --force | Overwrite existing hooks configuration | | copilot-cli-wakatime hook <event> | Process a hook event (called by Copilot CLI) | | copilot-cli-wakatime hook <event> --debug | Process with debug output |

Troubleshooting

No heartbeats being sent

1. Check that your API key is configured in ~/.wakatime.cfg
2. Verify .github/hooks/wakatime.json exists in your project
3. Ensure wakatime-cli is installed and in your PATH
4. Run with --debug flag to see detailed output

Rate limiting

Heartbeats are rate-limited to once per 60 seconds per project. This prevents excessive API calls while still capturing meaningful activity.

wakatime-cli not found

Install WakaTime CLI:

• macOS: brew install wakatime-cli
• Linux/Windows: https://github.com/wakatime/wakatime-cli/releases

Hooks not triggering

1. Verify you're running Copilot CLI from the project directory
2. Check that .github/hooks/wakatime.json is present
3. Ensure the hooks file has correct JSON structure (run init again if needed)

Self-recursion prevention

The plugin automatically skips processing if toolName starts with wakatime-. This prevents infinite loops if WakaTime itself is instrumented.

Uninstall

# Remove hooks configuration from project
rm .github/hooks/wakatime.json

# Uninstall the package
npm uninstall -g @geeknees/copilot-cli-wakatime

License

MIT