npm package: @geeknees/copilot-cli-wakatime
Description: WakaTime heartbeats for GitHub Copilot CLI hooks
Author: geeknees
Latest version: 0.1.0

# copilot-cli-wakatime

[![npm version](https://img.shields.io/npm/v/@geeknees/copilot-cli-wakatime)](https://www.npmjs.com/package/@geeknees/copilot-cli-wakatime)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

WakaTime integration for [GitHub Copilot CLI](https://githubnext.com/projects/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](https://wakatime.com) and API key
2. WakaTime API key configured in `~/.wakatime.cfg`:
   ```ini
   [settings]
   api_key = your-api-key-here
   ```
3. [GitHub Copilot CLI](https://githubnext.com/projects/copilot-cli) installed
4. `wakatime-cli` installed and available in PATH

## Installation

```bash
# 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`:

```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:

```bash
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

```bash
# 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

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

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

## License

MIT