Skip to content

HtmlGraph

Local-first observability and coordination platform for AI-assisted development
HtmlGraph - AI-assisted development observability
## Install HtmlGraph 
pip install htmlgraph
## Start Tracking Your Work 
from htmlgraph import SDK

# Initialize SDK (auto-discovers .htmlgraph directory)
sdk = SDK(agent="claude")

# Create a feature with fluent API
feature = sdk.features.create("User Authentication") \
    .set_priority("high") \
    .add_steps([
        "Create login endpoint",
        "Add JWT middleware",
        "Write tests"
    ]) \
    .save()

# Query with filters
high_priority = sdk.features.where(status="todo", priority="high")

# Create tracks with specs and plans
track = sdk.tracks.builder() \
    .title("OAuth Integration") \
    .with_spec(overview="Add OAuth 2.0 support") \
    .with_plan_phases([
        ("Phase 1", ["Setup OAuth (2h)", "Add JWT (3h)"])
    ]) \
    .create()
📄
HTML Work Items
Features, bugs, spikes, and tracks stored as HTML files. Git-diffable, browser-readable, and human-inspectable without any tooling.
👁
Live Dashboard
Phoenix LiveView dashboard with real-time event feed, session tracking, and agent activity monitoring — all local, no external services.
⚡
Local-First Core
HTML files and SQLite require no external servers. Git-diffable, browser-readable, and fully offline. The optional Phoenix dashboard adds real-time observability.
📢
Multi-AI Coordination
Works with Claude Code, Gemini CLI, Codex, and Copilot. Event-driven hook system captures every agent action automatically.
📈
Git Native
Text-based storage means perfect version control. Diffs show what changed. Merge conflicts are human-readable.
🚀
SDK for Programmatic Access
Fluent Python SDK with Pydantic validation. TrackBuilder for deterministic workflows. Full type safety throughout.

Why HtmlGraph?

AI-assisted development creates an observability gap: multiple agents running across sessions, no unified view of what was done, why, or by whom.

  • ✅ Purpose-built for Claude Code: Understands Claude Code concepts natively — sessions, hooks, features, spikes, agent attribution. Not a generic APM tool adapted for AI; built from the ground up for how developers actually work with AI coding agents.
  • ✅ Local-first: HTML files and SQLite require no servers or cloud services to configure or maintain
  • ✅ Observable: every AI agent action is tracked and browsable in the dashboard
  • ✅ Multi-AI: works with Claude Code, Gemini CLI, Codex, Copilot — not locked to one tool
  • ✅ Human-readable: HTML files you can open in any browser, inspect with DevTools, and diff in git
  • ✅ Git-native: all work items are diffable, versionable, and mergeable

Core Philosophy

Local-first observability

Track, coordinate, and observe AI-assisted development workflows. HTML files as canonical work items, SQLite for operational queries, and an optional Phoenix LiveView dashboard for real-time observability — local-first, no external infrastructure required for the core.

Quick Comparisons

vs External Tracking Tools

Feature External Tools HtmlGraph
Setup Accounts, APIs, cloud config pip install htmlgraph
Offline ❌ Requires internet ✅ Fully offline
Human readable 🟡 Web UI only ✅ Any browser or text editor
Version control ❌ Not git-native ✅ Git diff works perfectly
Multi-AI support ❌ Usually one tool ✅ Claude, Gemini, Codex, Copilot

vs JSON/YAML Files

Feature JSON HtmlGraph
Human readable 🟡 Text editor ✅ Browser with styling
Query ❌ jq or custom ✅ SQLite + CSS selectors
Live dashboard ❌ Needs UI ✅ Optional Phoenix LiveView
Agent hooks ❌ Manual ✅ Automatic event capture

Next Steps

📚 Get Started
Installation guide, first project, and core concepts →
🔌 SDK Reference
Complete SDK documentation with examples →
📖 User Guide
Learn tracks, features, and session management →
⚡ Examples
Real-world use cases and code samples →

Built with web standards. Designed for AI-assisted development.

Local-first. Observable. Multi-AI.