insight-flow

A workbench for AI-assisted task lifecycle management — CLI plus a bundled React dashboard.

insight-flow tracks AI-agent task work (specs, implementation, reviews, fixes, pushes, incidents) in sharded JSON files on disk, and serves a live React dashboard that visualizes the pipeline, lifecycle timeline, fix-loop hotspots, and per-task review history.

What's new in 0.5.0

• Reliable live updates — Socket.IO replaces the hand-rolled WebSocket; auto reconnect, long-polling fallback, works on Chrome and mobile Safari.
• Notifications — task transitions fire browser Notification API alerts and OS desktop notifications via insight-flow notify. Both opt-out in config.
• Multi-project overview — /overview aggregates all registered insight-flow servers in one page with live/reconnecting/down status badges.
• Richer activity feed — free hook enrichment (skill start/end, command classification) plus cheap phase markers via insight-flow log-activity. Both opt-out in config.

See CHANGELOG.md for the full entry.

Install

# One-off
npx insight-flow init
npx insight-flow

# Or globally
npm install -g insight-flow
insight-flow init
insight-flow

Quickstart

# 1. Initialize in your project (creates taskflow.config.json + workTasks/ + Claude Code skills)
insight-flow init

# 2. Create your first task
insight-flow create --title "Add auth to dashboard" --type feat --priority high --tags web,auth

# 3. Launch the dashboard
insight-flow            # opens http://localhost:6006 in your browser

How it works

your-project/
├── taskflow.config.json     # where workTasks live, server port, activity engine
├── workTasks/
│   ├── master.json          # meta + shard index
│   ├── tasks-N00-N09.json   # tasks 0–9
│   ├── tasks-N10-N19.json   # tasks 10–19
│   └── N00-add-auth/        # spec + review files for each task
│       ├── TASK.md
│       └── CHECKLIST.md
└── .claude/
    ├── commands/            # slash commands generated by `insight-flow init`
    └── hooks/               # activity engine hook (optional)

When you run insight-flow (or insight-flow ui):

1. A local HTTP server starts on the configured port.
2. The server serves the bundled React dashboard at /.
3. The dashboard reads workTasks/*.json from your configured workDir via /api/work-tasks*.
4. A WebSocket on /ws pushes file-change events so the UI updates live as you (or AI agents) edit tasks.

CLI

The insight-flow binary is the single canonical entry point for all task tracking. Run it from any project root that has a workTasks/ directory (or run insight-flow init first).

insight-flow                                    # Launch dashboard
insight-flow ui [--port N]                      # Same, with optional port override
insight-flow init                               # Initialize project

# Discovery
insight-flow current                            # Show active task
insight-flow next                               # Pick next actionable task by priority
insight-flow next-review                        # Pick next task needing review
insight-flow next-fix                           # Pick next fix-needed task
insight-flow next-change                        # Pick next changes-requested task
insight-flow list [--status ready]              # List tasks (optionally filtered)
insight-flow stats                              # Aggregate stats

# Task lifecycle
insight-flow create --title "..." --type feat|fix|rework [--priority high] [--tags a,b]
insight-flow status --id N00 --status <status> [--by agent-name]

insight-flow implement-start --id N00
insight-flow implement-end --id N00 --files "a.ts,b.ts"

insight-flow review-start --id N00 [--type ai|human]
insight-flow review-end --id N00 --verdict approved|fix-needed [--type ai|human] [--comment "..."]

insight-flow fix-start --id N00
insight-flow fix-end --id N00 --files "..." [--comment "..."]

# Post-implementation change requests
insight-flow change-request --id N00 --description "..."
insight-flow change-start --id N00
insight-flow change-end --id N00 --files "..." [--comment "..."]

# Git lifecycle
insight-flow push --id N00 --commit abc123 --message "..." [--branch name]
insight-flow mr-update --id N00 --url "https://..."
insight-flow merge --id N00
insight-flow done --id N00

# Incidents
insight-flow incident-create --id N03 --title "..." --severity critical|high|medium|low
insight-flow incident-status --id N03 --incident INC-001 --status investigating|production-fix|verified|closed
insight-flow incident-resolve --id N03 --incident INC-001 --rootCause "..." --fix "..."
insight-flow incident-list [--id N03]

# Migration / utility
insight-flow migrate                            # Migrate from legacy tracker.json
insight-flow help
insight-flow version

Run insight-flow help for the full list.

Configuration

taskflow.config.json (created by insight-flow init):

{
  "workDir": "workTasks",
  "shardSize": 10,
  "projectName": "my-project",
  "rolesDir": ".claude/roles",
  "server": {
    "port": 6006
  },
  "activityEngine": {
    "enabled": true,
    "logFile": ".taskflow-activity.jsonl",
    "maxEvents": 200
  }
}

| Key | Default | Purpose | | -------------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | workDir | "workTasks" | Directory (relative to your project root) where task JSON shards live. Move/rename this to put task data anywhere you want. | | shardSize | 10 | Tasks per shard file. Affects new shard rollovers, not existing files. | | projectName | inferred from package.json | Shown in the dashboard header. | | rolesDir | ".claude/roles" | Where role spec markdown templates are copied on init. | | server.port | 6006 | HTTP/WebSocket port the dashboard listens on. | | activityEngine.enabled | true | Stream Claude Code tool activity into the dashboard's activity panel. | | activityEngine.logFile | ".taskflow-activity.jsonl" | Ephemeral JSONL log file written by the activity hook. Gitignored. | | activityEngine.maxEvents | 200 | Ring-buffer size for the activity feed. | | notifications.browser | true | Enable browser desktop notifications for task-status transitions (Notification API). | | notifications.cli | true | Enable insight-flow notify calls from agent role files. Set to false to silence all CLI notifications. |

Notifications

insight-flow fires OS-level notifications from two places:

Browser (dashboard tab open) — when a watched task's status changes, the dashboard fires a Notification via the Web Notification API. A gear icon in the top bar opens a settings popover where you can:

• Toggle per-status notifications (implemented, approved, fix-needed, merged, changes-requested)
• Enable/disable sound
• Mute notifications when the tab is focused

Settings are persisted to localStorage. The browser prompts for permission on first load; if denied, no notifications fire and no console errors appear.

CLI (independent of browser tab) — insight-flow init installs a Claude Code Stop hook (.claude/hooks/taskflow-notify.sh) that fires automatically when Claude finishes a turn and the current task is in a notable status (implemented, approved, fix-needed, fixed, merged, changes-implemented). The hook calls insight-flow notify, which auto-detects the platform (osascript on macOS, notify-send on Linux, PowerShell on Windows) and exits in <100 ms — errors are silently swallowed. No agent prompt needs to call notify explicitly.

Disable either half via config:

{
  "notifications": {
    "browser": false,
    "cli": false
  }
}

When notifications.cli is false:

• insight-flow notify exits 0 silently without invoking any OS handler.
• insight-flow init skips the Stop hook installer and clears AGENT_NOTIFY.md in the project's roles directory.

CLI usage:

insight-flow notify "N19 implemented"
insight-flow notify "N19 approved" --title "Review done" --project my-app

Enabling the activity panel

The activity panel needs a Claude Code PostToolUse hook to emit events. Three states:

1. Automatic — running insight-flow init installs .claude/hooks/taskflow-activity.sh and registers it in .claude/settings.local.json.
2. Retrofit existing project — if you globally installed insight-flow or skipped init, run insight-flow install-activity-hook from the project root. The command is idempotent (re-running on a fully installed project is a no-op) and never overwrites unrelated PostToolUse hooks.
3. Disabled by config — setting activityEngine.enabled to false hides the panel entirely. The top-bar shows an Engine: off (config) chip so the state is explicit.

When the panel is enabled but the hook is missing, the dashboard renders a clear empty-state with the retrofit command instead of staying silently idle.

Slash commands (Claude Code)

insight-flow init writes nine slash commands to .claude/commands/:

| Command | Purpose | | ----------------------- | ----------------------------------- | | /taskmaster | Create a new task spec | | /task-implement | Implement a task | | /task-review | AI code review | | /task-human-review | Record human review feedback | | /task-review-fix | Fix issues from review | | /task-git | Branch, commit, push, PR, merge | | /task-incident | Track production incidents | | /task-request-changes | Post-implementation change requests | | /taskmaster-change | Edit an existing task spec |

Customizing agents

Add an agents key to your taskflow.config.json to inject project-specific rules into built-in agents and register entirely new custom agents.

Extending built-in agents

agents.extend is a map of built-in agent names to arrays of extra rule strings. Each rule is appended to the corresponding role file under a ## Project Extensions section. Re-running insight-flow init replaces (not duplicates) the section.

Valid agent names: taskmaster, task-implement, task-review, task-review-fix, task-human-review, task-git, task-incident, task-request-changes, taskmaster-change.

{
  "agents": {
    "extend": {
      "task-implement": [
        "Only use pnpm, never npm or yarn",
        "All new files must have a corresponding test"
      ],
      "task-review": ["Reject any PR that introduces console.log statements"]
    }
  }
}

Registering custom agents

agents.custom is an array of agent definitions. Each entry generates a Claude Code skill file at .claude/commands/<name>.md and adds a row for /<name> to the skills table in CLAUDE.md.

{
  "agents": {
    "custom": [
      {
        "name": "deploy-check",
        "role": "Deploy Readiness Checker",
        "description": "Verify the project is ready for deployment.",
        "outputContract": "1. Run pnpm build\n2. Check env vars\n3. Run smoke tests\n4. Report READY or BLOCKED"
      }
    ]
  }
}

| Field | Required | Description | | ---------------- | -------- | ----------------------------------------------------- | | name | yes | Skill command name — used as /<name> in Claude Code | | role | yes | One-line role header inside the skill file | | description | yes | Short description shown in CLAUDE.md | | outputContract | no | Workflow steps / output contract for the skill |

After editing taskflow.config.json, re-run insight-flow init to apply changes.

Programmatic API

import { startServer, resolveConfig, loadAllTasks } from "insight-flow";

const config = resolveConfig();
startServer(config); // or startServer(config, 7000) to override port

const tasks = loadAllTasks(config); // read every shard

Multi-project overview

When you run multiple insight-flow ui instances (one per project), the insight-flow-master package provides a live overview page that aggregates all of them into a single card grid.

How it works

Project servers (push model):

1. On startup, insight-flow ui auto-starts insight-flow-master locally (if not already running) and registers with it.
2. On every file-change, the project server pushes its current state (current task, status counts, activity) to the master via HTTP POST.
3. If the master restarts and loses its registry, the next push returns 401 — the project server silently re-registers and retries.

The master:

• Holds an in-memory registry of all registered projects.
• Serves GET /overview — a live card grid, one card per project.
• Broadcasts project-update events via Socket.IO to the browser.

Local setup

# Build the master package (once)
pnpm --dir packages/insight-flow-master run build

# Start your projects — master auto-starts on the first one
insight-flow ui                          # project A on :6006, master on :6100
# (in another terminal, different project dir)
insight-flow ui                          # project B on :6006, registers with existing master

# Open the overview
open http://localhost:6100/overview
# Or via any project server's /overview (renders as an iframe)
open http://localhost:6006/overview

Remote master

Set startMasterLocally: false in taskflow.config.json to point at a master running on another machine:

{
  "master": {
    "url": "http://my-server:6100",
    "startMasterLocally": false
  }
}

Standalone mode

To disable master integration entirely for a project:

{
  "master": { "standalone": true }
}

GET /overview returns 404 and no master process is started.

Master standalone mode

The master itself can run in standalone mode (no new registrations accepted, overview shows existing cards only):

// ~/.insight-flow/master.json
{ "port": 6100, "standalone": true }

License

MIT