Content
# Tool List
> A standalone, self-contained AI coding session productivity tracker that can be distributed via npm.
> A single npm package that integrates: stdio MCP server + HTTP daemon + browser dashboard + Cursor/Claude IDE Hook, without requiring any external platform or backend service.
[](./LICENSE)
## What it can do
- Within any business repository (Jira workflow), collect structured metrics on the conversation process between the IDE (Cursor / Claude Code, etc.) and AI models, dimensioned by Jira requirements:
- **Productivity multiplier (boost)** / associated Bug count / token cost / actual thinking time / numstat diff
- **One-sentence summary** / modification scope / discussion summary for each round of conversation
- **Cross-demand reuse** of retrospective experience (lessons-learned)
- All data is stored locally on the user's machine at `~/.ai-productivity-tracker/data/`, without uploading to the cloud or requiring an internet connection.
- The browser dashboard is available at `http://127.0.0.1:17350` by default, with 6 tabs (demand dashboard / retrospective experience / business configuration / MCP configuration / tool description / usage instructions).
- Compatible with Cursor `afterAgentResponse` + `stop` hook, Claude Code `Stop` + `UserPromptSubmit` hook.
## Get started in 30 seconds
```bash
# 1. Global installation
npm install -g @ai-productivity-tracker/cli
# 2. One-click installation of IDE configuration (MCP + hooks.json + skill)
aipt install
# 3. Open the dashboard
aipt ui open
# → Browser automatically opens http://127.0.0.1:17350
```
Complete. Start working normally in the IDE, and productivity data will be automatically tracked on the dashboard.
### IDE MCP configuration example
`aipt install` will automatically write `~/.cursor/mcp.json` (Cursor) and `~/.claude.json` (Claude Code), equivalent to:
```json
// ~/.cursor/mcp.json
{
"mcpServers": {
"ai-productivity-tracker": {
"command": "/abs/path/to/node",
"args": ["/abs/path/to/cli.mjs", "mcp"]
}
}
}
```
```json
// ~/.claude.json (top-level Claude Code fields are preserved)
{
"mcpServers": {
"ai-productivity-tracker": {
"type": "stdio",
"command": "/abs/path/to/node",
"args": ["/abs/path/to/cli.mjs", "mcp"]
}
}
}
```
No environment variables or tokens are required - generated automatically when the daemon starts, and MCP child processes retrieve them via lockfile.
> `aipt install --ide=cursor` / `aipt install --ide=claude` can be used to install only one side.
## Common commands
| Command | Effect |
| --- | --- |
| `aipt install` | One-click complete installation (write cursor + claude mcp configuration + inject hook + install skill) |
| `aipt install --ide=cursor` | Install only Cursor (~/.cursor/mcp.json + hooks.json + rule) |
| `aipt install --ide=claude` | Install only Claude Code (~/.claude.json + skill) |
| `aipt daemon` | Foreground start HTTP daemon (used when checking daemon logs) |
| `aipt ui open` | Open browser dashboard |
| `aipt doctor` | Health check: Node / daemon / mcp.json / hooks / skill / rule, etc., output with ✓⚠✗ |
| `aipt version` | Print version |
| `aipt --help` | Complete help |
> Short alias `aipt` is equivalent to full name `ai-productivity-tracker`.
## Working principle (a diagram)
```
┌──────────────────────────────────────────────────────────────────────┐
│ User machine │
│ │
│ IDE(Cursor/Claude Code) ──stdio──▶ npx aipt mcp │
│ │ │
│ ▼ │
│ ensureDaemon() ◄──singleton lock──┐ │
│ │ │ │
│ ▼ │ │
│ HTTP+Bearer ─────────────────────┘ │
│ │ │
│ ▼ │
│ Cursor hooks.json ──HTTP──▶ aipt daemon (127.0.0.1:17350) │
│ Claude settings.json hook ─────────────────────────│ │
│ ▼ │
│ Browser ──fetch http://127.0.0.1:17350──▶ daemon API + dashboard SPA │
│ │ │
│ ▼ │
│ ~/.ai-productivity-tracker/ │
│ ├── runtime.json (pid/port/token)│
│ ├── config.json (user preferences) │
│ └── data/ │
│ ├── <JIRA-KEY>/ │
│ │ ├── requirement.json │
│ │ └── iterations.jsonl │
│ ├── lessons/ │
│ ├── bindings.json │
│ └── ... │
└──────────────────────────────────────────────────────────────────────┘
```
Detailed architecture see [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md).
## Configuration / Environment variables
No configuration is required for the simplest deployment. For fine-tuning:
| Configuration | Default | Description |
| --- | --- | --- |
| `~/.ai-productivity-tracker/config.json` `port` | `17350` | Explicitly lock daemon port |
| `AIPT_PORT` env | — | Equivalent to config port, highest priority |
| `AIPT_DATA_ROOT` env | `~/.ai-productivity-tracker/data` | Data root directory |
| `AIPT_DAEMON_URL` env | — | (mcp/hook) explicitly specify daemon address |
| `AIPT_DAEMON_TOKEN` env | — | (mcp/hook) explicitly specify token |
Complete configuration see [`docs/PRD.md` §10](./docs/PRD.md).
## Troubleshooting
- **`aipt doctor`**: Output health check report with ✓⚠✗ (Node / daemon / mcp.json / hooks / skill / rule, etc.). First step for troubleshooting.
- **Dashboard not opening / Daemon unreachable**: Run `aipt daemon` in the foreground, check logs output
- **MCP / Hook reports 401**: `~/.ai-productivity-tracker/runtime.json` token changed, restart IDE after closing
- **Port occupied**: `AIPT_PORT=17888 aipt daemon` use another port
More see [`docs/PRD.md` §9](./docs/PRD.md).
## Project structure / Development
```
ai-productivity-tracker/
├── docs/ # Design documents (PRD/ARCHITECTURE/CHANGELOG/...)
├── packages/
│ ├── core/ # Data model / store / watcher / metrics
│ ├── hook-core/ # Cursor/Claude hook entry logic
│ ├── mcp/ # stdio MCP bridge(5 tools)
│ ├── server/ # HTTP daemon(30+ endpoint)+ skill-sync
│ ├── ui/ # Vue 3 dashboard SPA
│ └── cli/ # Single npm package release subject, argv-router + 11 subcommands
└── skills/ # Skill / Cursor Rule templates (released with cli package)
```
Development commands:
```bash
pnpm install # Install all workspace dependencies
pnpm typecheck # Full package tsc check
pnpm test # Full package vitest (currently 612 cases)
pnpm lint # ESLint 9 flat config
pnpm format # Prettier 3
pnpm --filter @ai-productivity-tracker/cli build # Chain ui build + esbuild bundle
pnpm --filter @ai-productivity-tracker/ui dev # Development SPA (automatically proxy /ai-productivity to daemon)
```
### Release to npm (maintainer)
```bash
# First-time setup dedicated release account (token falls in project-level .npmrc.publish, not polluting ~/.npmrc)
npm login --userconfig=./.npmrc.publish --auth-type=web --scope=@ai-productivity-tracker
# Dry run (no actual release, verify build + volume + login status)
pnpm release prerelease
# Actual release
pnpm release prerelease --publish # → x.y.z-rc.N+1
pnpm release patch --publish # → x.y.(z+1)
pnpm release 1.0.0 --publish # → Explicit version
```
`scripts/release.mjs` automatically: typecheck → test → lint → bump → build →
volume verification (< 3MB tarball) → npm whoami verification → publish → git commit + tag.
See [`docs/CHANGELOG.md`](./docs/CHANGELOG.md) for "Release Engineering Experience".
## License
[MIT](./LICENSE)
Design document full version: [`docs/PRD.md`](./docs/PRD.md)
