HtmlGraph¶

Local-first observability and coordination platform for AI-assisted development.

Work items, session tracking, custom agents, hooks, slash commands, quality gates, and a real-time dashboard — managed by a single Go binary, stored as HTML files in your repo. No external infrastructure required.

Install CLI Reference Blog

What it does¶

Work item tracking

Features, bugs, spikes, and tracks as HTML files in .htmlgraph/. Every change is a git diff. Every item has a lifecycle: create, start, complete.

Session observability

Hooks capture every tool call, every prompt, and attribute them to the active work item. See exactly what happened in any session via the dashboard.

Custom agents

Define specialized agents with specific models, tools, and system prompts. A researcher agent for investigation, a coder for implementation, a test runner for quality — each scoped to its job.

Hooks & automation

Event-driven hooks on SessionStart, PreToolUse, PostToolUse, and Stop. Enforce safety rules, capture telemetry, block dangerous operations, or trigger custom workflows automatically.

Skills & slash commands

Reusable workflows as slash commands: /deploy, /diagnose, /plan, /code-quality. Package complex multi-step procedures into single invocations that agents and humans can both use.

Quality gates

Enforce software engineering discipline: build, lint, and test before every commit. Spec compliance scoring, code health metrics, and structured diff reviews built into the CLI.

Real-time dashboard

Activity feed, kanban board, session viewer, and work item detail — served locally by htmlgraph serve. See what every agent is doing right now.

Multi-agent coordination

Claude Code, Gemini CLI, Codex, and GitHub Copilot all read from and write to the same work items. Orchestration patterns control which agent handles which task.

Plans & specifications

CRISPI plans break initiatives into trackable steps. Feature specs define acceptance criteria. Agents execute against the plan and report progress.

Everything is a file in your repo¶

.htmlgraph/*.html

HTML files — Work items are the source of truth. Human-readable. Git-diffable. No proprietary format.

.htmlgraph/htmlgraph.db

SQLite index — A derived read index for fast queries and dashboard rendering. Gitignored. Rebuilt from HTML anytime.

htmlgraph

Go binary — One CLI that does everything: create work items, manage sessions, serve the dashboard, run hooks.

Quick start¶

# Initialize in your repo
htmlgraph init

# Create a track and feature
htmlgraph track create "Auth Overhaul"
htmlgraph feature create "Add OAuth support" --track trk-abc123 --description "Implement OAuth2 flow"
htmlgraph feature start feat-def456

# Work with any AI agent — context is shared
# ... Claude Code, Gemini, Codex all see the active work item ...

htmlgraph feature complete feat-def456
htmlgraph serve    # see everything at localhost:4000

Install¶

# Install (universal)
curl -fsSL https://raw.githubusercontent.com/shakestzd/htmlgraph/main/install.sh | sh

# Or as a Claude Code plugin
claude plugin install htmlgraph

# Or build from source
git clone https://github.com/shakestzd/htmlgraph.git
cd htmlgraph && go build -o htmlgraph ./cmd/htmlgraph/

Upgrading¶

htmlgraph upgrade            # latest release
htmlgraph upgrade --check    # check without installing
htmlgraph update             # alias for upgrade

Work item types¶

Type	Prefix	Purpose
Feature	`feat-`	Units of deliverable work
Bug	`bug-`	Defects to fix
Spike	`spk-`	Time-boxed investigations
Track	`trk-`	Initiatives grouping related work
Plan	`plan-`	CRISPI implementation plans