mgrandau/ai-session-tracker-mcp

ai-session-tracker-mcp

MCP server for tracking AI coding sessions and measuring developer productivity.

Track your AI-assisted coding sessions, measure effectiveness, calculate ROI, and identify workflow friction points — all through the Model Context Protocol.

📖 Read the blog post: I Stopped Arguing About AI Productivity and Started Measuring It

✨ Features

• 📊 Session Tracking — Start, log interactions, and end coding sessions with full context
• 📈 ROI Metrics — Calculate time saved, cost savings, and productivity multipliers
• 🎯 Effectiveness Ratings — Rate AI responses 1-5 to track quality over time
• 🔍 Code Metrics — Analyze complexity and documentation quality of modified code
• 🌐 Web Dashboard — Real-time charts and analytics via FastAPI + htmx
• 🤖 Agent Files — Pre-configured chat modes and instruction files for VS Code

📦 Installation

From Git Repository

# Install directly from GitHub
pip install git+https://github.com/mgrandau/ai-session-tracker-mcp.git

# Or with pipx for isolated installation
pipx install git+https://github.com/mgrandau/ai-session-tracker-mcp.git

Configure for VS Code

After installing, run the install command in your project directory:

# Navigate to your project
cd /path/to/your/project

# Install MCP configuration and agent files
ai-session-tracker install

This creates:

• .vscode/mcp.json — MCP server configuration
• .github/instructions/ — AI instruction files
• .github/agents/ — VS Code custom agent definitions

Full MCP Configuration Template

For manual configuration or to enable all features, use this template in .vscode/mcp.json:

{
  "servers": {
    "ai-session-tracker": {
      "command": "ai-session-tracker",
      "args": [
        "server",
        "--dashboard-host", "127.0.0.1",
        "--dashboard-port", "8050"
      ]
    }
  }
}

Available server arguments:

Environment variables:

Configure via env in your mcp.json or system environment:

For backup and sync patterns (cloud sync, S3, rsync, git), see the .

Example with environment variables:

{
  "servers": {
    "ai-session-tracker": {
      "command": "ai-session-tracker",
      "args": ["server"],
      "env": {
        "AI_MAX_SESSION_DURATION_HOURS": "8.0",
        "AI_OUTPUT_DIR": "/home/jsmith/OneDrive/ai-metrics/my-project"
      }
    }
  }
}

💡 Tip: The --max-session-duration-hours setting prevents overnight sessions from skewing metrics. When a session exceeds this limit, its end_time is capped at start_time + max_duration instead of actual close time.

💡 Tip: Enable --dashboard-host and --dashboard-port to get a live web dashboard at http://127.0.0.1:8050 while the MCP server runs.

🚀 Quick Start

1. Start a Session

The MCP tools are available in VS Code Copilot Chat when using the "Session Tracked Agent" chat mode (see Enabling Agent Mode).

Once enabled, simply describe your task and the agent handles session tracking automatically:

Implement user authentication

2. Log Interactions

Interactions are logged automatically by the agent as you work. Each prompt/response pair is captured with context.

3. End Session

When you're done, the agent closes the session with the appropriate outcome. You can also explicitly request:

End the session as success

4. View Dashboard

# Open the web dashboard
ai-session-tracker dashboard

# Then visit http://localhost:8050

🤖 Enabling Agent Mode

After installation, enable the Session Tracked Agent to start automatic session tracking:

GitHub Copilot (VS Code & Visual Studio)

1. Open Copilot Chat
2. Click the agent dropdown (top of chat panel)
3. Select "Session Tracked Agent"

The agent mode persists for your chat session.

Codex Plugin (VS Code only)

Important: Codex does not auto-start the MCP server or load agent instructions like VS Code does via mcp.json. You need to tell Codex to adopt the Session Tracked Agent at the start of each conversation.

Step 1: Enable IDE context access:

1. In the Codex chat input, ensure "Include IDE context" is turned ON
2. Look for a blue icon — this confirms Codex can see your IDE context (files, selections, workspace structure)

Without IDE context enabled, the agent cannot access your workspace and session tracking may not function properly.

Step 2: At the start of your conversation, tell Codex to use the agent:

Use the Session Tracked Agent as the default for the rest of the conversation.

This makes Codex:

• Start the MCP server (creating .ai_sessions/ if it doesn't exist)
• Follow the session tracking instructions in .github/instructions/
• Track sessions automatically for all subsequent interactions

⚠️ Without this step, Codex won't know to start the MCP server and you'll get errors like "sessions.json doesn't exist". This is the most common setup issue with Codex.

🛠️ CLI Commands

# Start MCP server (for VS Code integration)
ai-session-tracker server

# Start MCP server with embedded dashboard
ai-session-tracker server --dashboard-host 0.0.0.0 --dashboard-port 8050

# Start MCP server with custom max session duration (8 hours)
ai-session-tracker server --max-session-duration-hours 8.0

# Start standalone web dashboard
ai-session-tracker dashboard [--host HOST] [--port PORT]

# Generate text report to stdout
ai-session-tracker report

# Install MCP config and agent files to current project
ai-session-tracker install

# Install as a system service (auto-start on login)
ai-session-tracker install --service

📝 Session Tracking CLI

Track sessions from the command line without needing an MCP server:

# Start a session - returns session_id
ai-session-tracker start \
  --name "Implement login feature" \
  --type code_generation \
  --model claude-opus-4-20250514 \
  --mins 60 \
  --source manual

# Log an interaction
ai-session-tracker log \
  --session-id "SESSION_ID" \
  --prompt "Create login form component" \
  --summary "Generated React component with validation" \
  --rating 5

# Flag an issue
ai-session-tracker flag \
  --session-id "SESSION_ID" \
  --type hallucination \
  --desc "AI referenced non-existent library" \
  --severity high

# List active sessions
ai-session-tracker active

# End a session
ai-session-tracker end \
  --session-id "SESSION_ID" \
  --outcome success \
  --notes "Feature completed successfully"

Command Reference

Task Types

code_generation, debugging, refactoring, testing, documentation, analysis, architecture_planning, human_review

Output Formats

All commands support --json flag for machine-readable output:

ai-session-tracker start --name "Test" --type testing --model gpt-4 --mins 30 --source manual --json
# Output: {"success": true, "message": "Session started", "data": {"session_id": "..."}}

Execution Context Isolation

Sessions track an execution context (foreground or background) to enable independent operation:

• MCP sessions run as foreground — interactive use via VS Code Copilot Chat
• CLI sessions run as background — batch scripts, CI pipelines, or background processes

Why this matters: When you start a new session, any previous active session with the same execution context is auto-closed with outcome partial. Sessions with different contexts are unaffected.

This allows you to:

• Run background batch processes via CLI while interactively using MCP
• Avoid accidentally closing automation sessions when starting interactive work
• Keep foreground and background metrics separate

🔄 Background Service

Install the MCP server as a system service to run automatically at login:

# Install as service (creates systemd user service on Linux, launchd agent on macOS, Task Scheduler on Windows)
ai-session-tracker install --service

# Manage the service
ai-session-tracker service start     # Start the service
ai-session-tracker service stop      # Stop the service
ai-session-tracker service status    # Check service status
ai-session-tracker service uninstall # Remove the service

Platform Support

🔧 MCP Tools

📁 Project Structure

ai-session-tracker-mcp/
├── src/ai_session_tracker_mcp/    # Main package
│   ├── server.py                  # MCP server implementation
│   ├── models.py                  # Domain models
│   ├── storage.py                 # JSON persistence
│   ├── statistics.py              # Analytics engine
│   ├── presenters.py              # Dashboard view models
│   ├── cli.py                     # Command-line interface
│   ├── web/                       # FastAPI dashboard
│   └── agent_files/               # VS Code integration files
├── tests/                         # Test suite (564 tests)
└── utils/                         # Development utilities

📚 Architecture Documentation

Detailed AI-readable architecture docs for each component:

🧪 Development

Setup

# Clone repository
git clone https://github.com/mgrandau/ai-session-tracker-mcp.git
cd ai-session-tracker-mcp

# Install with PDM
pdm install

# Run tests
pdm run test

# Run all checks (lint, typecheck, security, test-cov)
pdm run check-all

Available Scripts

📊 Data Storage

Session data is stored in .ai_sessions/ in your project root (or wherever AI_OUTPUT_DIR points):

.ai_sessions/
├── sessions.json      # Session metadata
├── interactions.json  # Logged interactions
├── issues.json        # Flagged issues
└── charts/            # Generated chart images

For backup, sync, and team aggregation patterns (cloud sync, NAS, git, S3, rsync) see the .

🔒 Stability

• MCP Tools — 🔒 ABI-frozen, breaking changes require major version bump
• CLI Commands — 🔒 ABI-frozen
• Core Classes — 🔒 ABI-frozen (Session, Interaction, Issue, etc.)
• Internal APIs — ⚠️ Subject to change (Presenters, ViewModels)

📄 License

MIT License — see for details.

💬 Community

💬 Join the Discord community

🤝 Contributing

Contributions welcome! Please ensure:

• All tests pass (pdm run test)
• Code is formatted (pdm run format)
• No lint errors (pdm run lint)
• Type checks pass (pdm run typecheck)