horsegraph

Plan node graphs (NODE-GRAPH.json) read through Tiny Horse canonical storage and visualized as ClaySpace worlds.

• Tiny Horse is the source of truth. horsegraph reads the graph from a bound checkout (and can run tinyhorse doctor on it), or straight from the canonical bundle in storage (file: or gdrive://), or from a Drive project by name. When it reads from storage it fetches and verifies the bundle and reads the graph at canonical HEAD, so the view shows what was parked, not unparked local edits.
• ClaySpace draws it. Every node is a ClaySpace Cell, every dependency is a Cell with an arrowhead, and the whole graph is a valid clayspace.world.snapshot. The HTML is ClaySpace's own self-contained orbit preview, plus a label, hover-detail and legend overlay.

pip install horsegraph            # add [gdrive] for Drive storage / --project

Use

# from a Tiny Horse-bound checkout (default graph path docs/runner-gateway/NODE-GRAPH.json)
horsegraph render --checkout . --doctor --out plan.html --world plan.world.json

# straight from canonical storage, no checkout needed
horsegraph render --storage gdrive://FOLDER_ID/Demo.bundle
horsegraph render --project "Demo"            # resolved like `tinyhorse claim`

# plan views
horsegraph next  --checkout .                 # "Needs you now" / "Claude starts next"
horsegraph path  --checkout .                 # critical path to the goal node
horsegraph check --checkout .                 # validate; exit 1 on warnings (e.g. done before its deps)

# any JSON file, no Tiny Horse
horsegraph render --file examples/NODE-GRAPH.json

--graph changes the path inside the repo; --ref reads a tag or commit from storage instead of HEAD.

The ClaySpace world it writes with --world opens with the usual tools (clayspace world inspect, clayspace world preview).

Reading the 3D view

Columns run left to right by dependency depth, and rows group by track. Drag to orbit, scroll to zoom, and hover a label for the node's title, deps and the contract items it advances.

Graph format

{
  "title": "…", "goal": "G-RELEASE",
  "tracks": {"CLI": "Command Line Interface"},
  "nodes": [
    {"id": "CLI-2", "title": "…", "owner": "agent", "status": "open",
     "deps": ["CLI-1", "CORE-2"], "track": "CLI", "closes": ["C2"]}
  ]
}

owner is agent or owner. status is done, open, later, after-proof or available-verified. Extra fields are kept. Cycles, unknown deps and duplicate ids are rejected.

Python

from horsegraph import from_storage, render
graph, prov = from_storage("file:/srv/git/demo.bundle")
print(graph.critical_path(), [n.id for n in graph.ready("owner")])
render(graph, "plan.html", provenance=prov.to_dict(), subtitle=prov.summary())

Release

python -m build && twine upload dist/*