DashGraph
README.md
# DashGraph
**Build live investigation-graph dashboards that Claude drives, from a YAML file.**
DashGraph is the engine behind PhishGraph and
AppaltiGraph, pulled out so any domain can have one. You describe the domain (node types, colours,
icons, relations and how strong they are as evidence, verdicts, groupings, noise rules) in a
`domain.yaml`; optionally add data sources as small Python collectors. DashGraph turns that into:
- an **MCP server** for Claude Code or Claude Desktop, with graph tools (`start_investigation`,
`get_frontier`, `mark_node`, `add_nodes`, ...) plus one tool per collector;
- a **live local dashboard**: the graph grows while Claude works, with replay, timeline, grouping
bubbles, folding of weak fans, Claude's investigation log and final assessment;
- **exports** (JSON, CSV, Markdown report) and a **no-LLM mode** (`dashgraph expand`).
No LLM API calls and no Anthropic key: the agent deciding the next step is the Claude you already
use. Data stays on your machine in `~/.dashgraph/<domain>/`.

## Make a dashboard with Claude
Copy the skill to Claude Code and ask for a dashboard:
```bash
git clone https://github.com/PierpaoloBene/dashgraph.git && cd dashgraph && uv sync
cp -r skills/dashgraph ~/.claude/skills/
```
> Build me a DashGraph dashboard that maps who funds which open-source projects, using the GitHub
> and Open Collective APIs.
Claude first settles the question with you, then **researches the data**: it looks for APIs,
open data and registries for every entity, reads their terms and limits, tries each one with a
real request and records the findings in the pack's `SOURCES.md`, with saved sample responses.
Only then does it build the dashboard on what the data can really support: it writes the pack,
validates it (validation refuses a pack whose data research is incomplete), runs it on a real seed,
shows you the demo dashboard and gives you the `claude mcp add` command. The skill's method is in
[skills/dashgraph/SKILL.md](skills/dashgraph/SKILL.md); the full format is in
[skills/dashgraph/REFERENCE.md](skills/dashgraph/REFERENCE.md).
## Or by hand
```bash
uv run dashgraph new ./birdgraph --title BirdGraph # scaffold: domain.yaml, SOURCES.md, collectors.py, prompt.md, demo.json
uv run dashgraph probe "https://api.example.org/..." -d ./birdgraph --save sample.json # try a source, keep a sample
uv run dashgraph validate ./birdgraph # check everything (SOURCES.md complete), replay the demo
uv run dashgraph demo -d ./birdgraph # see the dashboard with the scripted demo
uv run dashgraph install -d ./birdgraph # prints `claude mcp add birdgraph -- ...`
```
A minimal `domain.yaml`:
```yaml
name: birdgraph
title: BirdGraph
title_accent: Bird
node_types:
species: {label: Species, color: "#7fd18b", icon: leaf, label_from: [common_name]}
place: {label: Place, color: "#5fb3f9", icon: pin}
relations:
seen_in: medium
verdicts:
key: {label: Key, color: "#ff4d7d", role: positive}
noise: {label: Noise, color: "#6b7687", role: noise}
```
With a `SOURCES.md` describing where the data comes from, that alone is a working MCP server: Claude researches with its own tools (web search, documents,
other MCP servers) and records what it finds with `add_nodes` / `add_edges`. Add a collector when a
source deserves a repeatable tool:
```python
from dashgraph import Context, Node, Result, collector
@collector(applies_to=["species"], label="Sightings")
async def sightings(node: Node, ctx: Context, limit: int = 20) -> Result:
"""Recent public sightings of the species."""
data = await ctx.get_json("https://api.example.org/sightings", params={"q": node.value, "n": limit})
r = Result()
for s in data:
r.edge(node.id, r.node("place", s["place"], first_seen=s["date"]), "seen_in", seen=s["date"])
r.summary = f"{len(data)} sightings"
return r
```
## Built-in examples
| domain | collectors | what it shows |
|---|---|---|
| `researchgraph` | none | Claude researches a topic on the web and records people, organisations, money and sources; every link carries its source. Try `uv run dashgraph demo -d researchgraph`. |
| `wikigraph` | Wikidata (no key) | family, employers, owners, memberships and places around an entity, typed and dated. Try `uv run dashgraph expand "Douglas Adams" -d wikigraph`. |
Install one in Claude Code with `uv run dashgraph install -d researchgraph`.
## Using a dashboard in Claude
Use the `investigate_<name>` prompt (in Claude Code: `/mcp__<name>__investigate_<name>`) or just ask
"investigate X with BirdGraph". Claude starts an investigation and gives you the dashboard link
(`http://127.0.0.1:<port>`), expands the graph round by round from `get_frontier`, marks nodes with
a one-line reason, stops on the domain's limits, writes an assessment and exports a report.
CLI for the same database: `dashgraph list|export|expand|dashboard -d <domain>`.
## How it works
```
domain.yaml + collectors.py ──> Domain ──> Engine ──> Store (SQLite WAL, ~/.dashgraph/<name>/graph.db)
│ ▲ │ events table
▼ │ ▼
MCP server (stdio) ──┘ dashboard (FastAPI + WebSocket, 127.0.0.1)
```
- **Frontier**: priority = sum of the confidence of evidence edges from non-noise nodes, divided
by 1 + distance from the seed. Relation strengths come from `domain.yaml`.
- **Noise first**: value/attribute rules and cardinality (hubs) mark nodes noise before Claude sees
them; noise nodes are never expanded.
- **Live**: every write appends to an `events` table that the dashboard tails, so any process
(Claude Desktop, Claude Code, the CLI) updates any open dashboard.
- **Safe rendering**: collected values are shown as text only, with a strict CSP; the dashboard
binds to 127.0.0.1 and rejects foreign Host headers.
## Development
```bash
uv sync
uv run pytest # offline
uv run ruff check . && uv run ruff format --check . && uv run mypy src
```
MIT licence. Vendored: Cytoscape.js, cytoscape-fcose, cose-base, layout-base (MIT, see
`src/dashgraph/web/static/vendor/`).
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues