{
  "markdown": "# Claude Code Activity Tracker\n\n![Python 3.8+](https://img.shields.io/badge/python-3.8%2B-blue?logo=python&logoColor=white)\n![License: MIT](https://img.shields.io/badge/license-MIT-green)\n![Claude Code](https://img.shields.io/badge/Claude%20Code-plugin-orange?logo=anthropic&logoColor=white)\n\nA lightweight, privacy-respecting plugin for [Claude Code](https://claude.ai/code) that automatically tracks your AI-assisted development activity — sessions, tool calls, files edited, and time spent. All data stays on your machine in a local SQLite database.\n\n![Dashboard](docs/images/dashboard.png)\n\n---\n\n## Quick Install\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/Sent1nelX/claude-activity-tracker/main/install.sh | bash\n```\n\n![Install](docs/images/install.png)\n\nThat's it. The installer will:\n- Download all plugin files to `~/.claude-activity/`\n- Register the MCP server with Claude Code\n- Configure hooks (SessionStart, PreToolUse, Stop)\n- Start the background service automatically\n- Add auto-start to your shell profile\n\nThen **restart Claude Code** and send a message like `show my activity` or `coding stats`.\n\n> **Requirements:** Python 3.8+, `curl`\n\n---\n\n## Features\n\n- **Automatic session tracking** — hooks into Claude Code start/stop events, no manual logging\n- **Tool usage analytics** — see which MCP tools and Claude Code built-ins you reach for most\n- **File edit heatmap** — discover which files you iterate on most across sessions\n- **Web dashboard** — dark-themed HTML dashboard with Chart.js charts at `http://127.0.0.1:8765/dashboard`\n- **GitHub correlation** — compare AI sessions against actual git commits (efficiency ratio)\n- **VSCode correlation** — see which projects are active in both Claude Code and VSCode simultaneously\n- **Plane integration** — fetch open issues from your Plane workspace alongside session data\n- **Peak hour analysis** — discover when you're most productive with hourly heatmap\n- **Daily & weekly reports** — instant summaries via the `/activity` skill command\n- **MCP-native** — exposes metrics through a local MCP server so Claude can reason about your data\n- **Zero cloud dependency** — SQLite on disk, nothing transmitted anywhere\n- **Privacy-first** — records file paths and tool names only; never captures prompts or code content\n\n---\n\n## Manual Installation\n\nIf you prefer to inspect before running:\n\n```bash\ngit clone https://github.com/Sent1nelX/claude-activity-tracker.git\ncd claude-activity-tracker\n./install.sh\n```\n\n> **Requirements:** Python 3.8+, Claude Code CLI (`claude`)\n\n---\n\n## Usage\n\n### Asking Claude for your stats\n\nSend a message to Claude in any Claude Code session. These all work:\n\n```\nshow my activity\nwhat did I work on today\ncoding stats\n/activity\n```\n\n> **Note:** `/activity` is not a built-in slash command — it won't appear in the autocomplete menu (like `/usage` or `/status`). It's a skill trigger word: type it as a regular message and Claude will invoke the skill.\n\nClaude will call the `activity_stats` MCP tool and display a formatted text report:\n\n```\n📊 Activity — last 1 day(s)\n\n🖥️  Sessions      : 3\n🔧 Tool calls    : 47\n💬 Requests      : 12\n⏱️  Active time   : 94 min\n\n🔝 Top tools:\n   Edit                           18x\n   Read                           14x\n   Bash                            9x\n\n📁 Top files:\n   /home/user/project/src/server.py    7x\n   /home/user/project/hooks/pre_tool.py 4x\n```\n\n![Stats](docs/images/stats.png)\n\nFor a weekly report, ask: `activity report for 7 days` or call `activity_report` directly.\n\n### Web Dashboard\n\nOpen your browser at `http://127.0.0.1:8765/dashboard` while the service is running. You'll see a dark-themed dashboard with:\n\n- **Stat cards** — sessions, tool calls, requests, active time (today)\n- **Daily activity chart** — 7-day bar chart (sessions / tools / requests)\n- **Top tools doughnut** — which tools you use most\n- **Hourly heatmap** — line chart showing your peak hours across 24h\n- **Task type tags** — inferred categories (editing, reading, testing, …)\n- **Recent files table** — most-edited files with edit counts\n\nNo extra setup needed — the `/dashboard` endpoint is served by the same daemon that receives hook events.\n\n### MCP Tools\n\nThe plugin registers an `activity-tracker` MCP server with tools you can call directly or reference in prompts:\n\n| Tool | Description |\n|------|-------------|\n| `activity_stats` | Today's session summary — duration, tool calls, files edited |\n| `activity_session` | Details for a specific session |\n| `activity_files` | Most-edited files ranked by edit count |\n| `activity_patterns` | Peak hours, day-of-week heatmap, task type breakdown |\n| `activity_github` | Correlate AI sessions with git commits (efficiency ratio) |\n| `activity_report` | Multi-day report with daily breakdown (default: 7 days). Accepts `{ \"days\": N }` |\n| `activity_export` | Export data as JSON or POST to a webhook |\n| `activity_vscode` | Correlate Claude Code sessions with VSCode activity — shared projects and overlap |\n| `activity_plane` | Fetch open issues from a Plane workspace, or show setup instructions |\n\n---\n\n## Architecture\n\n```\nClaude Code session\n       │\n       ├── SessionStart hook ─── hooks/session_start.sh ─┐\n       │                                                   │  HTTP POST /event\n       ├── PreToolUse hook ───── hooks/pre_tool_use.sh ───► 127.0.0.1:8765\n       │                                                   │  (service.py daemon)\n       └── Stop hook ─────────── hooks/session_end.sh  ───┘\n                                                           │\n                                                    SQLite (~/.claude-activity/activity.db)\n                                                        │          │\n                                           service.py --mcp    GET /dashboard\n                                           (stdio server)       (browser)\n                                                  │\n                                            Claude Code\n                                    (activity_stats, activity_github, …)\n```\n\nA single unified daemon (`service.py`) runs two servers in one process:\n- **HTTP :8765** — receives events from lightweight bash hooks via `curl`\n- **MCP stdio** — answers tool queries from Claude Code (started via `claude mcp add`)\n\n---\n\n## Data Collected\n\nThe tracker records only the minimum needed for productivity metrics:\n\n| What is recorded | Example |\n|-----------------|---------|\n| Session start/end timestamps | `2026-05-12 09:14:32` |\n| Tool name invoked | `Edit`, `Bash`, `Read` |\n| File path of edited files | `/home/user/project/src/app.py` |\n| Session duration | `47 minutes` |\n\n**What is never recorded:**\n- Prompt or message text\n- Code content or file contents\n- API keys or environment variables\n- Terminal output\n\nAll data lives in `~/.claude-activity/activity.db` and never leaves your machine.\n\n---\n\n## Service Management\n\n```bash\n# Check status\npython3 ~/.claude-activity/src/service.py --status\n\n# Stop daemon\npython3 ~/.claude-activity/src/service.py --stop\n\n# Restart\npython3 ~/.claude-activity/src/service.py --daemon\n```\n\n---\n\n## Plane Setup\n\nTo connect your Plane workspace:\n\n1. Get your API key from **Plane → Settings → API Tokens**\n2. Save your config:\n\n```python\nimport json\nfrom pathlib import Path\n\ncfg = {\n    \"plane_workspace_url\": \"https://app.plane.so/YOUR_WORKSPACE\",\n    \"plane_api_key\": \"YOUR_KEY\"\n}\n(Path.home() / \".claude-activity\" / \"config.json\").write_text(json.dumps(cfg))\n```\n\n3. Call `activity_plane` — it will fetch your open issues automatically.\n\n---\n\n## Roadmap\n\n- [x] **VSCode correlation** — detect shared projects across Claude Code and VSCode sessions\n- [x] **Plane integration** — link sessions to Plane issues and sprints\n- [x] **Web dashboard** — dark-themed HTML dashboard with Chart.js at `http://127.0.0.1:8765/dashboard`\n- [ ] **Team aggregation** — opt-in anonymized team stats\n- [ ] **Goal tracking** — daily coding time targets with progress bars\n\n---\n\n## Contributing\n\nContributions are welcome. For significant changes, please open an issue first to discuss what you'd like to change.\n\n```bash\n# Development setup\ngit clone https://github.com/Sent1nelX/claude-activity-tracker.git\ncd claude-activity-tracker\npip3 install -r requirements.txt\n\n# Run tests\npython3 -m pytest tests/\n\n# Run the server locally\npython3 src/server.py\n```\n\nPlease make sure your changes include tests where applicable and keep individual files under 500 lines.\n\n---\n\n## License\n\n[MIT](LICENSE) — free to use, modify, and distribute.\n",
  "bytes": 8543,
  "sha": "c87771920415d828d4ef4fcbdc9809d7d59c05871b452eef3721ad944dec62b0",
  "repo_slug": "sent1nelx/claude-activity-tracker",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_sent1nelx_claude_activity_tracker_claude_5792c47c/readme"
}