Workflow Tracker MCP

Live workflow tracking for Claude Code with SSE dashboard, NTFY notifications, and 12-factor-agents integration.

Features

• MCP Server: Provides tools for logging workflow steps, agents, validations, and milestones
• Live Dashboard: Real-time SSE-powered web UI at http://localhost:9877
• NTFY Notifications: Push notifications for errors and milestones
• 12-Factor Agents: Genesis workflow support for resumable, checkpointed execution
• Auto-tracking Hooks: Claude Code hooks for automatic event logging

Installation

# Global install
npm install -g workflow-tracker-mcp

# Or use npx
npx workflow-tracker-mcp

Quick Start

1. Start the Dashboard

# Start dashboard server
workflow-dashboard

# Or with npm
npm run dashboard

Dashboard available at:

• Local: http://localhost:9877
• Tailscale: http://100.118.13.31:9877

2. Add to Claude Code MCP Config

Add to your .mcp.json:

{
  "mcpServers": {
    "workflow-tracker": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "workflow-tracker-mcp"],
      "env": {
        "SESSION_ID": "my-project-session",
        "NTFY_ENDPOINT": "http://localhost:8889",
        "NTFY_TOPIC": "my-topic"
      }
    }
  }
}

3. Use MCP Tools

Available tools in Claude Code:

• log_step - Log workflow step completion
• log_agent - Log agent spawn/completion
• log_validation - Log validation checks (Karen/Steve)
• log_milestone - Log major achievements
• get_workflow_summary - Get session summary

Genesis Workflow

For long-running, resumable workflows using 12-factor-agents:

# Initialize genesis
npx workflow-tracker-mcp genesis init

# Resume from checkpoint
npx workflow-tracker-mcp genesis resume

# Check status
npx workflow-tracker-mcp genesis status

Auto-Tracking Hooks

Add to ~/.claude/settings.json for automatic event logging:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/workflow-tracker.sh PreToolUse",
            "timeout": 300
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/workflow-tracker.sh PostToolUse",
            "timeout": 300
          }
        ]
      }
    ]
  }
}

Systemd Service

Auto-start dashboard on login:

# Create service
cat > ~/.config/systemd/user/workflow-dashboard.service << 'EOF'
[Unit]
Description=Workflow Tracker Dashboard
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/node /path/to/dist/dashboard-server.js
Restart=on-failure
Environment=DASHBOARD_PORT=9877

[Install]
WantedBy=default.target
EOF

# Enable and start
systemctl --user daemon-reload
systemctl --user enable --now workflow-dashboard

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | SESSION_ID | session-{timestamp} | Session identifier | | LOG_DIR | /tmp/workflow-tracker | Log file directory | | DASHBOARD_PORT | 9877 | Dashboard server port | | NTFY_ENDPOINT | http://localhost:8889 | NTFY server URL | | NTFY_TOPIC | anombyte-dev | NTFY topic |

Dashboard API

REST Endpoints

• GET /api/sessions - List all sessions
• GET /api/sessions/:sessionId - Get session events
• POST /api/events/:sessionId - Post new event

SSE Endpoint

• GET /api/events/:sessionId - SSE stream for real-time updates

Event Types

| Type | Description | |------|-------------| | step | Workflow step (success/error/in_progress) | | agent | Agent spawn/complete (Explore, Plan, etc.) | | validation | Validation check (karen/steve/pitch) | | milestone | Major achievement | | error | Error event |

License

MIT