ExGraph v0

ExGraph turns a hand-written graph into an interactive view for long-running, open-ended work.

View = render(graph.yaml)

You (or an Agent on your behalf) edit one graph.yaml. The CLI validates it and serves a local viewer so you can recover context: what the mainline is, what the frontier is, what is blocked, and which branches were closed.

ExGraph does not define what your nodes and edges mean. It only defines a structure (nodes, edges, sets) and how to render it. The semantics are yours.

Install

npm intstall -g @frostime/exgraph

Development

pnpm install
pnpm dev check examples/basic.yaml
pnpm dev serve examples/basic.yaml

After building:

pnpm build
node dist/src/cli.js check examples/basic.yaml
node dist/src/cli.js serve examples/basic.yaml

Commands

exgraph init [file]              # create a minimal graph.yaml
exgraph check <file>             # validate and lint
exgraph serve <file> [--port 4317]   # open a local viewer
exgraph export <file> -o <dir>   # write a static HTML viewer

serve and check never write generated files into your workspace. They read graph.yaml on demand and serve the viewer from package resources. export writes static output only to the directory you name.

What goes in the YAML

The structure is small:

• nodes — things worth remembering (each has an id and a title).
• edges — directed relations between nodes (from → to).
• sets — named collections of node ids, used as filters and highlights.
• render — which views to offer.

Everything else is yours to decide. A node's kind and an edge's kind are free-form strings: the engine does not require any particular value. The state field is the one closed list (see below), because the viewer colors and the lint depend on it.

Minimal example

version: 0.1
title: Example Exploration Graph

nodes:
  - id: n1
    state: active
    title: 一个目标节点
    note: title 必填，其余字段可选。

  - id: n2
    state: active
    title: 一个想法节点
    tags: [frontier]

edges:
  - from: n1
    to: n2
    label: 关系说明

sets:
  mainline: [n1, n2]
  frontier: [n2]

render:
  default_view: frontier
  views: [flow, cluster, frontier]

The kind, tags, note, and edge label above are illustrative. Use whatever vocabulary fits your project.

Node states

state is the one field with a fixed set of values, because the viewer and lint reason about it:

seed · candidate · active · blocked · done · closed · archived

It is a project-management state, not a logical truth value. Express logic (support, conflict, replacement) with edges instead.

Views

Three layouts are available: flow, cluster, and frontier. The viewer supports filtering by kind / state / set, search, and clicking a node to see its incoming and outgoing relations. Closed branches stay visible but can be hidden.

Design documents

• spec/GRAPH_SCHEMA.md — YAML fields and validation rules
• spec/ENGINE_SPEC.md — CLI commands and check/serve/export behavior
• spec/VIEW_CONTRACT.md — implementation-agnostic viewer contract
• skills/write-exgraph/SKILL.md — how an Agent maintains the YAML
• spec/archive/ — superseded inception documents, kept for history

License

GPL-3.0. See LICENSE.