kimi-wakatime

WakaTime integration for Kimi Code CLI. Track AI coding activity and time spent.

Inspired by codex-wakatime.

Features

• Automatic time tracking for Kimi Code CLI sessions
• File-level write heartbeats when Kimi edits or creates files (Edit/Write tools)
• Project-level heartbeats on prompts and completed turns
• Heartbeats categorized as AI coding in your WakaTime dashboard
• 60-second heartbeat rate limiting
• Automatic wakatime-cli installation if missing
• Zero dependencies, plain Node.js (>= 18)

Prerequisites

1. A WakaTime account and API key

2. API key configured in ~/.wakatime.cfg:

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

3. Kimi Code CLI installed

Installation

# Install the package
npm install -g kimi-wakatime

# Register the Kimi Code hooks
kimi-wakatime --install

This appends [[hooks]] entries to ~/.kimi-code/config.toml. Start a new Kimi Code session to activate them.

How It Works

┌─────────────────────────────────────────────────────────────┐
│                    Kimi Code CLI Session                     │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│   Hooks (configured in ~/.kimi-code/config.toml)            │
│   - UserPromptSubmit  → project-level heartbeat             │
│   - PostToolUse (Edit|Write) → file-level write heartbeat   │
│   - Stop              → project-level heartbeat             │
│   Payload arrives as JSON on stdin:                         │
│   { hook_event_name, session_id, cwd, tool_input, ... }     │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                     kimi-wakatime                           │
│   1. Parse hook JSON from stdin                             │
│   2. Extract file path from Edit/Write tool input           │
│   3. Check 60-second rate limit                             │
│   4. Spawn wakatime-cli detached (never blocks the session) │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                    WakaTime Dashboard                       │
│   Time appears under category "AI coding",                  │
│   editor "kimi-wakatime"                                    │
└─────────────────────────────────────────────────────────────┘

Installed hook configuration

kimi-wakatime --install appends this to ~/.kimi-code/config.toml:

# >>> kimi-wakatime >>>
[[hooks]]
event = "PostToolUse"
matcher = "^(Edit|Write)$"
command = "kimi-wakatime --hook"
timeout = 15

[[hooks]]
event = "Stop"
command = "kimi-wakatime --hook"
timeout = 15

[[hooks]]
event = "UserPromptSubmit"
command = "kimi-wakatime --hook"
timeout = 15
# <<< kimi-wakatime <<<

The marker comments make --uninstall and re-installs safe and idempotent.

Commands

| Command | Description | | --- | --- | | kimi-wakatime --install | Add hooks to ~/.kimi-code/config.toml | | kimi-wakatime --uninstall | Remove hooks from ~/.kimi-code/config.toml | | kimi-wakatime --hook | Process a hook payload from stdin (called by Kimi Code) | | kimi-wakatime --version | Print version | | kimi-wakatime --help | Show help |

Files & Locations

| File | Purpose | | --- | --- | | ~/.wakatime/kimi.json | Rate limiting state | | ~/.wakatime/kimi.log | Debug logs | | ~/.kimi-code/config.toml | Kimi Code configuration | | ~/.wakatime.cfg | WakaTime API key and settings | | ~/.wakatime/wakatime-cli-* | Auto-downloaded wakatime-cli (if not already in PATH) |

Debug Mode

Enable debug logging by adding to ~/.wakatime.cfg:

[settings]
debug = true

Logs are written to ~/.wakatime/kimi.log. wakatime-cli's own log is at ~/.wakatime/wakatime.log (pass --verbose there for more detail).

Troubleshooting

No heartbeats being sent

1. Check that your API key is configured in ~/.wakatime.cfg
2. Verify the hooks are present in ~/.kimi-code/config.toml and you started a new session after installing
3. Enable debug mode and check ~/.wakatime/kimi.log
4. Confirm heartbeats arrive on the plugin status page

Rate limiting

Heartbeats for the same entity are limited to one per 60 seconds (write events always go through). If you're testing, wait at least 60 seconds between turns.

wakatime-cli not found

The plugin automatically downloads wakatime-cli from GitHub releases if it's not in your PATH or ~/.wakatime/. If that fails, install it manually.

Uninstall

kimi-wakatime --uninstall
npm uninstall -g kimi-wakatime

Development

npm test    # run tests (node:test, no dependencies)

License

MIT