visual-devflow

Visual DevFlow

A local, real-time project dashboard for Claude Code, Codex, and multi-agent development.

Quick Start · Install · How It Works · Agent Events

What It Is

Visual DevFlow turns live development activity into a browser dashboard:

• File changes appear as animated project-tree and graph updates.
• Agents can show what they are reading or editing.
• Builds, tests, deploys, Git work, and custom tasks appear as timeline events.
• Multiple projects can be tracked and switched from one UI.
• Recent activity persists locally across refreshes and restarts.

It is designed for local development. The server binds to 127.0.0.1 by default, stores project-local state under .visual-devflow/, and serves all browser assets from the repo without CDN dependencies.

Quick Start

From this repository:

bin/visual-devflow enable --project /path/to/project --open

Then use:

bin/visual-devflow status --project /path/to/project
bin/visual-devflow disable --project /path/to/project

The enable command is idempotent. If Visual DevFlow is already running for that project, it reuses the existing server and prints the dashboard URL.

Install As A Plugin

Codex

Codex supports local and GitHub marketplace sources. After this repo is available on GitHub:

codex plugin marketplace add MisterWonderful/visual-devflow
codex plugin marketplace upgrade

Then ask Codex:

Enable Visual DevFlow for this project.

The Codex plugin exposes the visual-devflow skill, which routes enable, disable, status, and event-emission requests to the shared bin/visual-devflow command.

Claude Code

This repo includes a .claude-plugin/ bundle. Add this repository as a Claude Code plugin source, then use:

/visualize
/visual-devflow-enable
/visual-devflow-status
/visual-devflow-disable

The Claude commands call the same shared project control command as Codex, so behavior is consistent across tools.

Direct Local Use

For development without either plugin host:

cd server
npm install
npm run build:client
npm run check
npm start

Open http://127.0.0.1:3456.

How It Works

Claude Code / Codex / shell
        |
        | enable, disable, emit-task, emit-agent
        v
bin/visual-devflow
        |
        | starts project-local server
        v
server/index.js  <---- watches files, Git, tasks, agents
        |
        | Socket.io + HTTP API
        v
client/index.html ---- React + D3 dashboard

When enabled for a project, Visual DevFlow:

1. Starts a loopback Node server.
2. Watches the project with Chokidar.
3. Builds a bounded project tree and dependency graph.
4. Streams events to the browser over Socket.io.
5. Persists recent history under .visual-devflow/.

One-Command Project Control

# Enable and open the dashboard
bin/visual-devflow enable --project "$PWD" --open

# Print machine-readable state
bin/visual-devflow status --project "$PWD" --json

# Print the dashboard URL
bin/visual-devflow url --project "$PWD"

# Stop the project-local server
bin/visual-devflow disable --project "$PWD"

Runtime state is project-local:

.visual-devflow/
  state.json
  server.log
  agent-env
  projects/*/events.json

Keep this directory out of Git. It is ignored by this repo's .gitignore.

Agent Events

Agents and scripts can publish high-level work:

bin/visual-devflow emit-task \
  --project "$PWD" \
  --kind test \
  --status started \
  --name "Run tests" \
  --command "npm test"

Agents can also publish their read/edit focus:

bin/visual-devflow emit-agent \
  --project "$PWD" \
  --name Codex \
  --action editing \
  --file server/index.js \
  --file client/index.html

These events draw live agent nodes and file links in the dashboard.

Multi-Project UI

You can track multiple projects in one dashboard:

VISUAL_DEVFLOW_PROJECTS="API=/path/to/api,Web=/path/to/web" npm start

Or use JSON for per-project watch folders:

VISUAL_DEVFLOW_PROJECTS='[
  {"id":"api","name":"API","projectDir":"/path/to/api","watchDirs":["src","tests"]},
  {"id":"web","name":"Web","projectDir":"/path/to/web","watchDirs":["app","components"]}
]' npm start

Projects can also be added, edited, and removed from the dashboard's Projects panel. Runtime projects are persisted locally.

API Overview