{"id":46554472,"url":"https://github.com/shakestzd/htmlgraph","last_synced_at":"2026-05-03T04:02:43.714Z","repository":{"id":328952768,"uuid":"1117484217","full_name":"shakestzd/htmlgraph","owner":"shakestzd","description":"Local-first observability and coordination platform for AI-assisted development","archived":false,"fork":false,"pushed_at":"2026-04-02T07:29:52.000Z","size":160641,"stargazers_count":3,"open_issues_count":4,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-02T07:39:12.634Z","etag":null,"topics":["ai-agents","claude-code","developer-tools","fastapi","htmx","local-first","multi-agent","observability","python","sqlite"],"latest_commit_sha":null,"homepage":"https://shakestzd.github.io/htmlgraph/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shakestzd.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-12-16T11:30:29.000Z","updated_at":"2026-04-02T07:29:56.000Z","dependencies_parsed_at":"2026-02-02T02:03:16.349Z","dependency_job_id":null,"html_url":"https://github.com/shakestzd/htmlgraph","commit_stats":null,"previous_names":["shakes-tzd/htmlgraph","shakestzd/htmlgraph"],"tags_count":294,"template":false,"template_full_name":null,"purl":"pkg:github/shakestzd/htmlgraph","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shakestzd%2Fhtmlgraph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shakestzd%2Fhtmlgraph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shakestzd%2Fhtmlgraph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shakestzd%2Fhtmlgraph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shakestzd","download_url":"https://codeload.github.com/shakestzd/htmlgraph/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shakestzd%2Fhtmlgraph/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31584847,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"online","status_checked_at":"2026-04-09T02:00:06.848Z","response_time":112,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","claude-code","developer-tools","fastapi","htmx","local-first","multi-agent","observability","python","sqlite"],"created_at":"2026-03-07T04:10:22.030Z","updated_at":"2026-04-09T04:05:38.515Z","avatar_url":"https://github.com/shakestzd.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HtmlGraph\n\n**\"HTML is All You Need\"**\n\nA lightweight graph database framework built entirely on web standards. Use HTML files as nodes, hyperlinks as edges, and CSS selectors as the query language.\n\n## Why HtmlGraph?\n\nModern AI agent systems are drowning in complexity:\n- Neo4j/Memgraph → Docker, JVM, learn Cypher\n- Redis/PostgreSQL → More infrastructure\n- Custom protocols → More learning curves\n\n**HtmlGraph uses what you already know:**\n- ✅ HTML files = Graph nodes\n- ✅ `\u003ca href\u003e` = Graph edges\n- ✅ CSS selectors = Query language\n- ✅ Any browser = Visual interface\n- ✅ Git = Version control (diffs work!)\n\n## Installation\n\n```bash\npip install htmlgraph\n```\n\n## Quick Start\n\n### CLI (recommended for new projects)\n\n```bash\nhtmlgraph init --install-hooks\nhtmlgraph serve\n```\n\nThis bootstraps:\n- `index.html` dashboard at the project root\n- `.htmlgraph/events/` append-only JSONL event stream (Git-friendly)\n- `.htmlgraph/index.sqlite` analytics cache (rebuildable; gitignored via `.gitignore`)\n- versioned hook scripts under `.htmlgraph/hooks/` (installed into `.git/hooks/` with `--install-hooks`)\n\n### Python (SDK - Recommended)\n\n```python\nfrom htmlgraph import SDK\n\n# Initialize (auto-discovers .htmlgraph directory)\nsdk = SDK(agent=\"claude\")\n\n# Create and configure a feature with fluent API\nfeature = sdk.features.create(\"User Authentication\") \\\n    .set_priority(\"high\") \\\n    .set_description(\"Implement OAuth 2.0 login\") \\\n    .add_steps([\n        \"Create login endpoint\",\n        \"Add JWT middleware\",\n        \"Write integration tests\"\n    ]) \\\n    .save()\n\nprint(f\"Created: {feature.id}\")\n\n# Work on features\nwith sdk.features.edit(feature.id) as f:\n    f.status = \"in-progress\"\n    f.agent_assigned = \"claude\"\n    f.steps[0].completed = True\n\n# Query features\nhigh_priority_todos = sdk.features.where(status=\"todo\", priority=\"high\")\nfor feat in high_priority_todos:\n    print(f\"- {feat.id}: {feat.title}\")\n\n# Create and configure a track with TrackBuilder\ntrack = sdk.tracks.builder() \\\n    .title(\"Q1 Security Initiative\") \\\n    .priority(\"high\") \\\n    .add_feature(\"feature-001\") \\\n    .add_feature(\"feature-002\") \\\n    .create()\n\nprint(f\"Created track: {track.id}\")\n```\n\n### HTML File Format\n\nHtmlGraph nodes are standard HTML files:\n\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml lang=\"en\"\u003e\n\u003chead\u003e\n    \u003cmeta charset=\"UTF-8\"\u003e\n    \u003ctitle\u003eUser Authentication\u003c/title\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n    \u003carticle id=\"feature-001\"\n             data-type=\"feature\"\n             data-status=\"in-progress\"\n             data-priority=\"high\"\u003e\n\n        \u003cheader\u003e\n            \u003ch1\u003eUser Authentication\u003c/h1\u003e\n        \u003c/header\u003e\n\n        \u003cnav data-graph-edges\u003e\n            \u003csection data-edge-type=\"blocked_by\"\u003e\n                \u003ch3\u003eBlocked By:\u003c/h3\u003e\n                \u003cul\u003e\n                    \u003cli\u003e\u003ca href=\"feature-002.html\"\u003eDatabase Schema\u003c/a\u003e\u003c/li\u003e\n                \u003c/ul\u003e\n            \u003c/section\u003e\n        \u003c/nav\u003e\n\n        \u003csection data-steps\u003e\n            \u003ch3\u003eSteps\u003c/h3\u003e\n            \u003col\u003e\n                \u003cli data-completed=\"true\"\u003e✅ Create auth routes\u003c/li\u003e\n                \u003cli data-completed=\"false\"\u003e⏳ Add middleware\u003c/li\u003e\n            \u003c/ol\u003e\n        \u003c/section\u003e\n    \u003c/article\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\n## Features\n\n- **Zero dependencies** beyond `justhtml` and `pydantic`\n- **CSS selector queries** - no new query language to learn\n- **Version control friendly** - git diff works perfectly\n- **Human readable** - open in any browser\n- **AI agent optimized** - lightweight context generation\n- **Graph algorithms** - BFS, shortest path, cycle detection, topological sort\n- **Agent Handoff** - Context-preserving task transfers between agents\n- **Capability Routing** - Automatic task assignment based on agent skills\n- **Deployment Automation** - One-command releases with version management\n- **Unified Backend** - Operations layer shared by CLI and SDK for consistency\n\n## Orchestrator Architecture: Flexible Multi-Agent Coordination\n\nHtmlGraph 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.\n\n**Key Principles:**\n- ✅ **Flexible model selection** - Any model can do any work; choose based on task fit and cost\n- ✅ **Dynamic spawner composition** - Mix and match spawner types (Gemini, Copilot, Codex, Claude) within the same workflow\n- ✅ **Cost optimization** - Use cheaper models for exploratory work, expensive models only for reasoning\n- ✅ **Parallel execution** - Independent tasks run simultaneously, reducing total time\n\n**Example: Parallel Exploration with Multiple Spawners**\n\n```python\n# All run in parallel - each uses the best tool for the job\nTask(subagent_type=\"gemini-spawner\",    # FREE exploration\n     prompt=\"Find all authentication patterns in src/auth/\")\n\nTask(subagent_type=\"copilot-spawner\",   # GitHub integration\n     prompt=\"Check GitHub issues related to auth\",\n     allow_tools=[\"github(*)\"])\n\nTask(subagent_type=\"claude-spawner\",    # Deep reasoning\n     prompt=\"Analyze auth patterns for security issues\")\n\n# Orchestrator coordinates, subagents work in parallel\n# Total time = slowest task (not sum of all)\n# Cost = optimized (cheap exploration + expensive reasoning only)\n```\n\n**Spawner Types:**\n- **Gemini Spawner** - FREE exploratory research, batch analysis (2M tokens/min)\n- **Copilot Spawner** - GitHub-integrated workflows, git operations\n- **Codex Spawner** - Code generation, coding completions\n- **Claude Spawner** - Deep reasoning, analysis, strategic planning (any Claude model)\n\n→ [Complete Orchestrator Architecture Guide](docs/orchestrator-architecture.md) - Detailed patterns, cost optimization, decision framework, and advanced examples\n\n## Comparison\n\n| Feature | Neo4j | JSON | HtmlGraph |\n|---------|-------|------|-----------|\n| Setup | Docker + JVM | None | None |\n| Query Language | Cypher | jq | CSS selectors |\n| Human Readable | ❌ Browser needed | 🟡 Text editor | ✅ Any browser |\n| Version Control | ❌ Binary | ✅ JSON diff | ✅ HTML diff |\n| Visual UI | ❌ Separate tool | ❌ Build it | ✅ Built-in |\n| Graph Native | ✅ | ❌ | ✅ |\n\n## Use Cases\n\n1. **AI Agent Coordination** - Task tracking, dependencies, progress\n2. **Knowledge Bases** - Linked notes with visual navigation\n3. **Documentation** - Interconnected docs with search\n4. **Task Management** - Todo lists with dependencies\n\n## Contributing\n\nHtmlGraph is developed using HtmlGraph itself (dogfooding). This means:\n\n- ✅ Every development action is replicable by users through the package\n- ✅ We use the SDK, CLI, and plugins - not custom scripts\n- ✅ Our development workflow IS the documentation\n\n**See [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md) for:**\n- Dogfooding principles\n- Replicable workflows\n- Environment setup (PyPI tokens, etc.)\n- Development best practices\n\n**Quick start for contributors:**\n```bash\n# Clone and setup\ngit clone https://github.com/Shakes-tzd/htmlgraph\ncd htmlgraph\nuv sync\n\n# Start tracking your work (dogfooding!)\nuv run htmlgraph init --install-hooks\nuv run htmlgraph serve  # View dashboard\n\n# Use SDK for development\nuv run python\n\u003e\u003e\u003e from htmlgraph import SDK\n\u003e\u003e\u003e sdk = SDK(agent=\"your-name\")\n\u003e\u003e\u003e sdk.features.where(status=\"todo\")\n```\n\n## License\n\nMIT\n\n## System Prompt \u0026 Delegation Documentation\n\nFor Claude Code users and teams using HtmlGraph for AI agent coordination:\n\n- **[System Prompt Quick Start](docs/SYSTEM_PROMPT_QUICK_START.md)** - Setup your system prompt in 5 minutes (start here!)\n- **[System Prompt Architecture](docs/SYSTEM_PROMPT_ARCHITECTURE.md)** - Technical deep dive + troubleshooting\n- **[Delegation Enforcement Admin Guide](docs/DELEGATION_ENFORCEMENT_ADMIN_GUIDE.md)** - Setup cost-optimal delegation for your team\n- **[System Prompt Developer Guide](docs/SYSTEM_PROMPT_DEVELOPER_GUIDE.md)** - Extend with custom layers, hooks, and skills\n\n## Links\n\n- [GitHub](https://github.com/Shakes-tzd/htmlgraph)\n- [API Reference](docs/API_REFERENCE.md) - Complete SDK API documentation\n- [Documentation](docs/) - SDK guide, workflows, development principles\n- [Examples](examples/) - Real-world usage examples\n- [PyPI](https://pypi.org/project/htmlgraph/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshakestzd%2Fhtmlgraph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshakestzd%2Fhtmlgraph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshakestzd%2Fhtmlgraph/lists"}