WakaTime integration for OpenAI Codex CLI. Track AI coding activity and time spent.
Tip
Also check out opencode-wakatime for OpenCode!
- Automatic time tracking for Codex CLI sessions
- File-level activity detection via message parsing
- 60-second heartbeat rate limiting
- Automatic WakaTime CLI installation and updates
- Cross-platform support (macOS, Linux, Windows)
- WakaTime account and API key
- WakaTime API key configured in
~/.wakatime.cfg:[settings] api_key = your-api-key-here
- Codex CLI installed
# Install the package
npm install -g codex-wakatime
# Configure the notification hook
codex-wakatime --installThis adds notify = ["codex-wakatime"] to your ~/.codex/config.toml.
┌─────────────────────────────────────────────────────────────┐
│ Codex CLI Session │
└─────────────────────────┬───────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ agent-turn-complete event │
│ Codex sends notification with: │
│ - thread-id, turn-id │
│ - cwd (working directory) │
│ - last-assistant-message │
└─────────────────────────┬───────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ codex-wakatime │
│ 1. Parse notification JSON from CLI argument │
│ 2. Extract file paths from assistant message │
│ 3. Check 60-second rate limit │
│ 4. Send heartbeat(s) to WakaTime │
└─────────────────────────┬───────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ WakaTime Dashboard │
│ View your AI coding metrics at wakatime.com │
└─────────────────────────────────────────────────────────────┘
| Event | Purpose |
|---|---|
agent-turn-complete |
Triggered after each Codex turn completes |
The plugin extracts file paths from the assistant's response using these patterns:
- Code block headers:
```typescript:src/index.ts - Backtick paths:
`src/file.ts` - Action patterns:
Created src/file.ts,Modified package.json - Quoted paths:
"src/file.ts"or'src/file.ts'
If no files are detected, a project-level heartbeat is sent using the working directory.
The plugin auto-configures ~/.codex/config.toml on installation:
notify = ["codex-wakatime"]Enable debug logging by adding to ~/.wakatime.cfg:
[settings]
debug = trueLogs are written to ~/.wakatime/codex.log.
| File | Purpose |
|---|---|
~/.wakatime/codex.json |
Rate limiting state |
~/.wakatime/codex.log |
Debug logs |
~/.wakatime/codex-cli-state.json |
CLI version tracking |
~/.codex/config.toml |
Codex configuration |
~/.wakatime.cfg |
WakaTime API key and settings |
# Clone the repository
git clone https://github.com/angristan/codex-wakatime
cd codex-wakatime
# Install dependencies
npm install
# Build
npm run build
# Run tests
npm test
# Type check
npm run typecheck
# Lint
npm run checkcodex-wakatime/
├── src/
│ ├── index.ts # Main entry point
│ ├── install.ts # Hook installation
│ ├── extractor.ts # File path extraction
│ ├── wakatime.ts # CLI invocation
│ ├── dependencies.ts # CLI management
│ ├── state.ts # Rate limiting
│ ├── logger.ts # Logging
│ ├── options.ts # Config parsing
│ ├── types.ts # TypeScript interfaces
│ └── __tests__/ # Test files
├── package.json
├── tsconfig.json
└── biome.json
# Remove the notification hook
codex-wakatime --uninstall
# Uninstall the package
npm uninstall -g codex-wakatime| Command | Description |
|---|---|
codex-wakatime --install |
Add notification hook to Codex config |
codex-wakatime --uninstall |
Remove notification hook from Codex config |
codex-wakatime '{"type":"agent-turn-complete",...}' |
Process a notification (called by Codex) |
- Check that your API key is configured in
~/.wakatime.cfg - Verify the notify hook is set in
~/.codex/config.toml - Enable debug mode and check
~/.wakatime/codex.log
Heartbeats are rate-limited to once per 60 seconds. If you're testing, wait at least 60 seconds between Codex turns.
The plugin automatically downloads wakatime-cli if not found. If this fails:
- Check your internet connection
- Manually install: https://github.com/wakatime/wakatime-cli/releases
- Ensure
wakatime-cliis in your PATH
MIT