Causal lineage and observability for AI-assisted development.
Answer "why does this code exist?" in one command. HtmlGraph traces causal chains across work items, commits, sessions, and agent spawns — then stores everything as HTML files in your repo. No external infrastructure required.
- Not a hosted platform. Local-first. Your data stays on your machine — no cloud sync, no telemetry.
- Not a general-purpose dev tool yet. Today it's power-user and Claude-Code-centric. Other CLI integrations exist but are less mature.
- Not a behavioral agent coordinator. It observes and attributes what agents do — it does not dispatch, steer, or enforce behavior on agents at runtime.
| Layer | Role |
|---|---|
.htmlgraph/*.html |
Canonical CRUD store — single source of truth |
SQLite (.htmlgraph/htmlgraph.db) |
Rebuildable read cache for fast queries and the dashboard |
Go binary (htmlgraph) |
CLI + hook handler |
HTML is the source of truth; SQLite is derived. If they drift, htmlgraph reindex drops the database and rebuilds it from the HTML files. No external infrastructure — no Postgres, no Redis, no cloud sync.
# 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/For subsequent rebuilds after the binary is on your PATH, use htmlgraph build instead.
htmlgraph upgrade # latest release
htmlgraph upgrade --check # check without installing
htmlgraph update # alias for upgradehtmlgraph init # creates .htmlgraph/ in your repo
htmlgraph track create "Auth Overhaul"
htmlgraph feature create "Add OAuth" --track <trk-id> --description "Implement OAuth2 flow"
htmlgraph feature start <feat-id>
# ... do work ...
htmlgraph feature complete <feat-id>
htmlgraph serve # dashboard at localhost:4000Causal lineage — Trace the full causal chain for any work item, commit, session, or file. Three commands cover the common queries:
# Unified causal chain: forward edges (what this caused) + backward edges (what caused this)
htmlgraph lineage feat-abc1234
# Reverse direction: given a feature ID, list every commit and session it produced
htmlgraph trace feat-abc1234
# Temporal lineage: git log for a work item's HTML file — every edit, in order
htmlgraph history feat-abc1234Work 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.
Quality gates — Enforce software engineering discipline: build, lint, and test before every commit. Spec compliance scoring, code health metrics, and structured diff reviews.
Real-time dashboard — Activity feed, kanban board, session viewer, and work item detail — served locally by htmlgraph serve.
Multi-agent attribution and observation — Claude Code, Gemini CLI, Codex, and GitHub Copilot all read from and write to the same work items via the CLI. Every tool call, file edit, and session is attributed to a work item so you can see what each agent actually did. (Session transcript ingestion currently supports Claude Code JSONL format.)
Plans & specifications — CRISPI plans break initiatives into trackable steps. Feature specs define acceptance criteria. Agents execute against the plan and report progress.
| 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 |
The lineage command family covers work items, commits, sessions, and files within a single repo. Two natural follow-ups are explicitly out of scope for now:
- Spec-as-node — treating feature specs as first-class lineage nodes so acceptance criteria appear in the causal chain alongside the code that satisfies them.
- Cross-project lineage — tracing chains across multiple repos registered in
~/.local/share/htmlgraph/projects.json. Today each project's lineage is self-contained.
htmlgraph help --compact
See full CLI documentation at shakestzd.github.io/htmlgraph.
HtmlGraph is developed using HtmlGraph itself (dogfooding). .htmlgraph/ contains real work items — not demos.
git clone https://github.com/shakestzd/htmlgraph
cd htmlgraph
go build -o htmlgraph ./cmd/htmlgraph/
./htmlgraph initQuality gates: go build ./... && go vet ./... && go test ./...
MIT