Core Concepts¶

HtmlGraph is built on a simple philosophy: HTML is All You Need. This guide explains the core concepts and how they work together.

The Web is a Graph¶

Every webpage is a node. Every hyperlink is an edge. HtmlGraph uses this fundamental web structure to create a lightweight graph database.

HTML File = Graph Node
<a href> = Graph Edge
data-* attributes = Node Properties
CSS selectors = Query Language

Key Components¶

Features¶

Features are the atomic units of work in HtmlGraph. Each feature is an HTML file with:

Status: todo, in-progress, blocked, done
Priority: low, medium, high, critical
Steps: Checklist of implementation tasks
Properties: Custom metadata (effort, completion, etc.)
Edges: Links to related features (blocks, blocked_by, related)

from htmlgraph import SDK

sdk = SDK(agent="claude")

feature = sdk.features.create(
    title="User Authentication",
    status="todo",
    priority="high",
    steps=["Create endpoint", "Add middleware", "Write tests"]
)

File location: .htmlgraph/features/feature-{timestamp}.html

Tracks¶

Tracks are multi-feature projects that bundle related work with specs and plans. Each track is a directory containing:

index.html: Track overview and dashboard
spec.html: Requirements and success criteria
plan.html: Phased implementation plan with time estimates

track = sdk.tracks.builder() \
    .title("OAuth Integration") \
    .with_spec(
        overview="Add OAuth 2.0 support",
        requirements=[("Google OAuth", "must-have")]
    ) \
    .with_plan_phases([
        ("Phase 1", ["Configure OAuth (2h)", "Setup endpoints (1h)"])
    ]) \
    .create()

File location: .htmlgraph/tracks/track-{timestamp}/

Sessions¶

Sessions track all activity during an agent's work session. Each session is an HTML file with:

Events: Log of all tool calls and interactions
Features worked on: Which features received attribution
Timestamps: Start and end times
Agent: Which agent did the work

Sessions are automatically created and managed by HtmlGraph hooks.

File location: .htmlgraph/sessions/session-{id}.html

Events¶

Events are the append-only log of all activity. Each event is a JSON line with:

Timestamp: When the event occurred
Event type: ToolUse, UserPrompt, SessionStart, etc.
Session ID: Which session generated the event
Feature ID: Which feature receives attribution
Data: Event-specific payload

File location: .htmlgraph/events/{session-id}.jsonl

Graph Structure¶

Nodes¶

Every HTML file in HtmlGraph is a graph node. Nodes have:

ID: Unique, collision-resistant identifier (e.g., feat-a1b2c3d4)
Type: feature, track, session, or custom
Properties: Stored in data-* attributes
Content: Human-readable description in HTML

Hash-Based IDs¶

HtmlGraph uses hash-based IDs for multi-agent collaboration:

Type	Prefix	Example
Feature	`feat-`	`feat-a1b2c3d4`
Bug	`bug-`	`bug-12345678`
Track	`trk-`	`trk-abcdef12`
Session	`sess-`	`sess-7890abcd`
Spike	`spk-`	`spk-87654321`
Event	`evt-`	`evt-11223344`

These IDs are collision-resistant, meaning multiple agents can create nodes simultaneously without conflicts. The 8-character hash is generated from SHA256 of (title + microsecond timestamp + random entropy), providing effectively zero collision probability even with thousands of concurrent agents.

Hierarchical sub-tasks are supported: feat-a1b2c3d4.1.2

Learn more: - ID Generation API - Usage examples and API reference - Hash-Based IDs Design - Architecture and implementation details

Example node structure:

<article id="feature-001"
         data-type="feature"
         data-status="in-progress"
         data-priority="high">
    <h1>User Authentication</h1>

    <nav data-graph-edges>
        <section data-edge-type="blocks">
            <h3>⚠️ Blocked By:</h3>
            <ul>
                <li><a href="feature-005.html">Database Schema</a></li>
            </ul>
        </section>
    </nav>
</article>

Edges¶

Edges are created using standard HTML hyperlinks. The relationship type is specified using data-relationship attributes:

<a href="feature-005.html"
   data-relationship="blocks">Database Schema</a>

Common relationship types:

blocks: This feature blocks another
blocked_by: This feature is blocked by another
related: General relationship
implements: Session implements a feature
part_of: Feature is part of a track

Queries¶

Query the graph using CSS selectors:

# All high-priority features
high = sdk.features.query('[data-priority="high"]')

# Blocked features
blocked = sdk.features.query('[data-status="blocked"]')

# Features assigned to claude
claude_features = sdk.features.query('[data-agent-assigned="claude"]')

Data Flow¶

┌─────────────────────────────────────────────────────────┐
│ 1. Agent creates/updates nodes via SDK                  │
└────────────────┬────────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────────────┐
│ 2. Pydantic models validate and convert to HTML        │
└────────────────┬────────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────────────┐
│ 3. HTML files written to .htmlgraph/ directory         │
└────────────────┬────────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────────────┐
│ 4. Hooks log events to JSONL file                      │
└────────────────┬────────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────────────┐
│ 5. SQLite index updated for fast queries               │
└────────────────┬────────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────────────┐
│ 6. Browser/Dashboard displays graph visually           │
└─────────────────────────────────────────────────────────┘

Why HTML?¶

Human Readable¶

Open any node in a browser and see it beautifully rendered with CSS styling. No special tools required.

Git Native¶

HTML is plain text. Git diffs show exactly what changed. Merge conflicts are readable.

Minimal Infrastructure¶

No Docker, no JVM, no external database servers. The SDK has minimal Python dependencies (pydantic, justhtml, watchdog) and uses SQLite for indexing and JSONL for event logs. HTML files work everywhere: browsers, Python, JavaScript, any language.

Standards-Based¶

CSS selectors are a W3C standard. Everyone knows them. No proprietary query language to learn.

Offline First¶

Everything works offline. No server required. Copy the .htmlgraph/ directory anywhere.

Presentation Layer Included¶

Styling, layout, and interactivity are built-in using CSS and JavaScript. No separate UI framework needed.

SDK vs CLI vs Dashboard¶

SDK (Python)¶

For programmatic access and agent integration:

from htmlgraph import SDK
sdk = SDK(agent="claude")
feature = sdk.features.create("Task")

CLI (Bash)¶

For command-line workflows:

htmlgraph feature create "Task"
htmlgraph feature start feature-001
htmlgraph serve

Dashboard (Browser)¶

For visual exploration:

Kanban board view
Graph visualization
Timeline view
Session history

Open index.html in any browser or run htmlgraph serve.

Next Steps¶

Features & Tracks Guide - Detailed feature and track workflows
TrackBuilder Guide - Master the TrackBuilder API
Sessions Guide - Understanding session tracking
API Reference - Complete SDK documentation