grafli¶

A keyboard-driven, plain-text diagram tool for people who think faster than they click.

PLACEHOLDER — hero shot: a real grafli session showing a system architecture diagram with semantic edge chips, a code-mode note, and the focus filter active.

Why grafli¶

Keyboard-first¶

Modal editing, vim muscle memory. Four primary modes — Select, Rect, Text, Connect — and you build entire diagrams without ever reaching for the mouse.

Less is more¶

A small, deliberate set of primitives — boxes, arrows, notes — composes into anything from a quick sketch to a layered architecture diagram. No menus to discover, no themes to fight.

Text for AI, git, humans¶

.grafli files are line-oriented plain text. Diffs make sense. LLMs can read and write them. You can edit them in your editor of choice. No binary blobs, no cloud lock-in.

30-second tour¶

PLACEHOLDER — animated GIF: launch grafli, press n to create a box, type a label, press Ctrl+L to spawn a connected box to the right, repeat. End with a four-box diagram in under 10 seconds.

Build by typing¶

Press n to drop a box. Press o to add one below the current selection. Ctrl+h / k / l create a connected box to the left, up, or right — arrow included. Most diagrams take fewer keystrokes than describing them in prose.

Modes for spatial intent: Select (v), Rect (n), Text (t), Connect (c).
Directional creation: spawn neighbors, connected by an arrow, with one chord.
Style and dimension sub-modes (s / d) for color, size, and resize without leaving the keyboard.
Smart arrow routing snaps edges to the nearest box boundary; bidirectional pairs merge automatically.

PLACEHOLDER — screencast: directional creation with Ctrl+l spawning connected boxes; show the arrow snapping cleanly between them.

A file format you can read¶

@ box frontend "Frontend" 100,100 160x60 %secondary
@ box backend  "Backend"  320,100 160x60 %primary
@ arrow frontend -> backend "REST API"
@ arrow backend  -> db      "data: queries" !dashed
@ note 100,240 "SPA with React"

One element per line. Stable IDs. Diffs that highlight what actually changed. The format is small enough to learn in a sitting and structured enough that an LLM can produce a valid diagram from a prompt.

PLACEHOLDER — split view: .grafli source on the left, rendered diagram on the right; a one-line edit highlighted in both panels.

Human-readable — nothing is encoded; you can hand-edit any element.
Git-native — line-oriented diffs reflect intent.
AI-ready — LLMs reliably emit and modify the format from natural language.
External edits welcomed — grafli watches the file and reloads automatically.

Annotate with intent¶

Notes aren't just sticky labels. Grafli recognizes lightweight conventions and renders them with visual weight that matches their meaning.

Tasks (T:) and questions (Q:) get distinct colors so review work is visible at a glance.
Discussions (AI: / Reviewer: …) format as threaded conversation bubbles inside a single note.
Code-mode notes (lines starting with code:) syntax-highlight pseudocode with keywords like fn:, if:, call:, verify:, risk:, @file:line references.
Semantic edge labels — prefixes like data:, call:, event:, verify:, risk: render as colored chips on the arrow itself.
Markdown resources — attach a markdown note to any element and edit it in a full-window zen editor.

PLACEHOLDER — collage: a code-mode note (fn:/call:/verify:), a T:/Q: pair, semantic edge chips on three arrows (call:, data:, risk:), and an inline discussion thread.

Navigate diagrams that grew¶

Real diagrams sprawl. Grafli has navigation built for that.

PLACEHOLDER — jump labels overlaid on every visible element via Ctrl+J; one keystroke selects the target.

Jump labels (Ctrl+J) — every visible item gets a one-or-two-key label; press it to select.
Search (/) by label, fuzzy-matched.
Graph navigation — hold Alt, see connector keys, follow edges chord by chord.
Hierarchy traversal — P parent, F first child, Tab cycle siblings, with a breadcrumb in the status bar.
Jumplist (Ctrl+O / Ctrl+I) — vim-style viewport history.
Sub-graflis — link any node to a deeper diagram in its own file. Click through, edit, return.

Read complex diagrams¶

Two view modes turn a busy diagram into a focused one.

Subgraph focus — B on a node fades everything that isn't reachable from it. Cycle through all / forward / backward directions; toggle 1-hop vs unlimited depth with Shift+B. Clear with the same key.

Complexity heatmap — color every node by how many connections, parents, and children it has. Hot nodes glow; cold nodes fade. Find the parts of a diagram that need refactoring without reading every label.

PLACEHOLDER — two stacked panels: top shows subgraph focus dimming unrelated boxes; bottom shows the complexity heatmap with a few hot nodes glowing red.

PLACEHOLDER — example: Y to copy diagram to clipboard, paste into a markdown file or chat; Ctrl+E exporting a clean SVG.

Yank as PNG (Y) — the whole diagram on your clipboard, ready to paste into a doc, chat, or PR.
SVG export (Ctrl+E) — vector output for documentation pipelines.
Auto-save — changes flush within 300 ms; no save buttons, no lost work.
External resources — drop in images and markdown files; grafli tracks paths and migrates them when you rename.

Where grafli fits¶

System architecture¶

Lay out services, data flows, and ownership lines with semantic edge labels that survive into the file format.

Code review notes¶

Attach T: / Q: annotations and code-mode pseudocode summaries to any element. Pair the diagram with the PR.

Brainstorming¶

Modal creation is fast enough to keep up with thinking. Refactor by selection, not redrawing.

Living design docs¶

Embed a .grafli next to your markdown. Diff it. Render it on demand. Treat diagrams like the code they describe.

Install¶

pip install grafli
grafli my-diagram.grafli

Requirements: Python 3.12+, PySide6 (Qt 6.7+).

Press F1 in-app for the full keybinding cheat sheet and text-annotation reference.

Project¶

Released under the MIT License.