Local-first observability and coordination platform for AI-assisted development. Document-backed work items with SQLite-indexed runtime state, and multi-agent session tracking.
Verified details
These details have been verified by PyPIProject links
GitHub Statistics
Maintainers
Project description
HtmlGraph
Local-first observability and coordination platform for AI-assisted development.
Local-first core — HTML files as nodes, hyperlinks as edges, SQLite for fast local queries. No Postgres, no Redis, no cloud sync required. An optional Phoenix LiveView dashboard provides real-time observability.
Design philosophy: "HTML is All You Need" — work items are standard HTML files readable in any browser, diffable in git, and editable without tooling.
Why HtmlGraph?
Modern AI agent systems are drowning in complexity:
- Neo4j/Memgraph → Docker, JVM, learn Cypher
- Redis/PostgreSQL → More infrastructure
- Custom protocols → More learning curves
HtmlGraph uses what you already know:
- ✅ HTML files = Graph nodes
- ✅
<a href>= Graph edges - ✅ CSS selectors = Query language
- ✅ Any browser = Visual interface
- ✅ Git = Version control (diffs work!)
Installation
pip install htmlgraph
Quick Start
CLI (recommended for new projects)
htmlgraph init --install-hooks
htmlgraph serve
This bootstraps:
index.htmldashboard at the project root.htmlgraph/events/append-only JSONL event stream (Git-friendly).htmlgraph/index.sqliteanalytics cache (rebuildable; gitignored via.gitignore)- versioned hook scripts under
.htmlgraph/hooks/(installed into.git/hooks/with--install-hooks)
Python (SDK - Recommended)
from htmlgraph import SDK
# Initialize (auto-discovers .htmlgraph directory)
sdk = SDK(agent="claude")
# Create and configure a feature with fluent API
feature = sdk.features.create("User Authentication") \
.set_priority("high") \
.set_description("Implement OAuth 2.0 login") \
.add_steps([
"Create login endpoint",
"Add JWT middleware",
"Write integration tests"
]) \
.save()
print(f"Created: {feature.id}")
# Work on features
with sdk.features.edit(feature.id) as f:
f.status = "in-progress"
f.agent_assigned = "claude"
f.steps[0].completed = True
# Query features
high_priority_todos = sdk.features.where(status="todo", priority="high")
for feat in high_priority_todos:
print(f"- {feat.id}: {feat.title}")
# Create and configure a track with TrackBuilder
track = sdk.tracks.builder() \
.title("Q1 Security Initiative") \
.priority("high") \
.add_feature("feature-001") \
.add_feature("feature-002") \
.create()
print(f"Created track: {track.id}")
HTML File Format
HtmlGraph nodes are standard HTML files:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>User Authentication</title>
</head>
<body>
<article id="feature-001"
data-type="feature"
data-status="in-progress"
data-priority="high">
<header>
<h1>User Authentication</h1>
</header>
<nav data-graph-edges>
<section data-edge-type="blocked_by">
<h3>Blocked By:</h3>
<ul>
<li><a href="feature-002.html">Database Schema</a></li>
</ul>
</section>
</nav>
<section data-steps>
<h3>Steps</h3>
<ol>
<li data-completed="true">✅ Create auth routes</li>
<li data-completed="false">⏳ Add middleware</li>
</ol>
</section>
</article>
</body>
</html>
Features
- Purpose-built for Claude Code — Purpose-built observability for AI-assisted development. Natively understands Claude Code sessions, hooks, features, spikes, and agent attribution — not a generic monitoring tool adapted for AI.
- No external infrastructure — 10 runtime deps (justhtml, pydantic, jinja2, rich, watchdog, pyyaml, tenacity, networkx, pydantic-settings, typing_extensions), no Postgres/Redis/cloud required
- HTML canonical store - work items are standard HTML files, git-diffable and browser-readable
- SQLite operational layer - fast local queries, dashboard analytics, rebuild from HTML source
- Phoenix LiveView dashboard - real-time activity feed and agent activity monitoring (optional, requires Elixir/Erlang)
- Multi-AI agent support - Claude, Gemini, Codex, Copilot coordination out of the box
- Event-driven hook system - Claude Code hooks record all tool calls and session events
- SDK for programmatic access - features, bugs, spikes, tracks with fluent API
- Version control friendly - git diff works perfectly on all artifacts
- Graph algorithms - BFS, shortest path, cycle detection, topological sort
- Agent Handoff - Context-preserving task transfers between agents
- Deployment Automation - One-command releases with version management
Orchestrator Architecture: Flexible Multi-Agent Coordination
HtmlGraph implements an orchestrator pattern that coordinates multiple AI agents in parallel, preserving context efficiency while maintaining complete flexibility in model selection. Instead of rigid rules, the pattern uses capability-first thinking to choose the right tool (and model) for each task.
Key Principles:
- ✅ Flexible model selection - Any model can do any work; choose based on task fit and cost
- ✅ Dynamic spawner composition - Mix and match spawner types (Gemini, Copilot, Codex, Claude) within the same workflow
- ✅ Cost optimization - Use cheaper models for exploratory work, expensive models only for reasoning
- ✅ Parallel execution - Independent tasks run simultaneously, reducing total time
Example: Parallel Exploration with Multiple Spawners
# All run in parallel - each uses the best tool for the job
Task(subagent_type="gemini-spawner", # FREE exploration
prompt="Find all authentication patterns in src/auth/")
Task(subagent_type="copilot-spawner", # GitHub integration
prompt="Check GitHub issues related to auth",
allow_tools=["github(*)"])
Task(subagent_type="claude-spawner", # Deep reasoning
prompt="Analyze auth patterns for security issues")
# Orchestrator coordinates, subagents work in parallel
# Total time = slowest task (not sum of all)
# Cost = optimized (cheap exploration + expensive reasoning only)
Spawner Types:
- Gemini Spawner - FREE exploratory research, batch analysis (2M tokens/min)
- Copilot Spawner - GitHub-integrated workflows, git operations
- Codex Spawner - Code generation, coding completions
- Claude Spawner - Deep reasoning, analysis, strategic planning (any Claude model)
→ Complete Orchestrator Architecture Guide - Detailed patterns, cost optimization, decision framework, and advanced examples
Comparison
| Feature | Neo4j | JSON | HtmlGraph |
|---|---|---|---|
| Setup | Docker + JVM | None | None |
| Query Language | Cypher | jq | CSS selectors |
| Human Readable | ❌ Browser needed | 🟡 Text editor | ✅ Any browser |
| Version Control | ❌ Binary | ✅ JSON diff | ✅ HTML diff |
| Visual UI | ❌ Separate tool | ❌ Build it | ✅ Built-in |
| Graph Native | ✅ | ❌ | ✅ |
Use Cases
- AI Agent Coordination - Task tracking, dependencies, progress
- Knowledge Bases - Linked notes with visual navigation
- Documentation - Interconnected docs with search
- Task Management - Todo lists with dependencies
Contributing
HtmlGraph is developed using HtmlGraph itself (dogfooding). This means:
- ✅ Every development action is replicable by users through the package
- ✅ We use the SDK, CLI, and plugins - not custom scripts
- ✅ Our development workflow IS the documentation
See docs/archive/DEVELOPMENT.md for:
- Dogfooding principles
- Replicable workflows
- Environment setup (PyPI tokens, etc.)
- Development best practices
Quick start for contributors:
# Clone and setup
git clone https://github.com/shakestzd/htmlgraph
cd htmlgraph
uv sync
# Start tracking your work (dogfooding!)
uv run htmlgraph init --install-hooks
uv run htmlgraph serve # View dashboard
# Use SDK for development
uv run python
>>> from htmlgraph import SDK
>>> sdk = SDK(agent="your-name")
>>> sdk.features.where(status="todo")
License
MIT
System Prompt & Delegation Documentation
For Claude Code users and teams using HtmlGraph for AI agent coordination:
- System Prompt Quick Start - Setup your system prompt in 5 minutes (start here!)
- System Prompt Architecture - Technical deep dive + troubleshooting
- Delegation Enforcement Admin Guide - Setup cost-optimal delegation for your team
- System Prompt Developer Guide - Extend with custom layers, hooks, and skills
Links
- GitHub
- API Reference - Complete SDK API documentation
- Documentation - SDK guide, workflows, development principles
- Examples - Real-world usage examples
- PyPI
Project details
Verified details
These details have been verified by PyPIProject links
GitHub Statistics
Maintainers
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
htmlgraph-0.35.0.tar.gz
(2.1 MB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file htmlgraph-0.35.0.tar.gz.
File metadata
- Download URL: htmlgraph-0.35.0.tar.gz
- Upload date:
- Size: 2.1 MB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
3c260c2e6db181694b8181f5eaec5fd6106e46b36d7d3d4ceee17b194127d12f
|
|
| MD5 |
62e197ea3174f0bedd0ecb918b6ae173
|
|
| BLAKE2b-256 |
1c069de6af9a1d2de6b18e068abc50c02e0075503568d26a38d2d6efebf5cbd6
|
File details
Details for the file htmlgraph-0.35.0-py3-none-any.whl.
File metadata
- Download URL: htmlgraph-0.35.0-py3-none-any.whl
- Upload date:
- Size: 1.8 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
54371337dfce7c3cd081b753c5f105af5d892f5d4da31bdb1760b5418ba8c776
|
|
| MD5 |
fa5780ea90882e2220f9c0226d8b458c
|
|
| BLAKE2b-256 |
dd6efba6108dd912b9c2b6690307f2a440e3003e8c05bec0976ce80b4a4f601c
|
