grafli

A keyboard-driven, plain-text diagram tool for developers.

grafli lets you sketch architecture diagrams, code-review notes, and design sketches without leaving the keyboard. Files are line-oriented .grafli text that diffs cleanly in git and that LLMs can read and produce reliably.

Documentation and feature tour: https://grafli.mistergc.dev

Pair grafli with your AI

grafli isn't just a diagram editor — it's the canvas your coding agent uses to communicate complex systems back to you. The bundled grafli skill teaches the agent how to produce idiomatic .grafli files — proper layouts, semantic edge labels, code-mode notes for review-oriented diagrams, plus a "plan before you write" loop that keeps the output focused and readable.

Extract the skill from your installed copy and point your agent at it:

# Save to a file, or pipe straight into the right place for your tool.
grafli skill -o SKILL.md
grafli skill --where        # path of the bundled SKILL.md
grafli skill --help         # install URLs for Claude Code, OpenCode, Codex

Once installed, ask your agent to "draw a diagram of …", "visualize the data flow in this module", or "sketch the OAuth callback as a grafli" — the skill triggers and produces a .grafli you can open in the desktop app or render headless via grafli render.

Install

pip install grafli
grafli my-diagram.grafli
grafli                      # no file? opens your scratch board

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

Design philosophy

• Keyboard-first. Modal editing in the spirit of vim — Select, Rect, Text, Connect — composes a small set of keystrokes into rich diagrams.
• Less is more. Three primitives (boxes, arrows, notes) plus visible containment cover the cases that matter, without a menu maze.
• Text for AI, git, humans. .grafli files are line-oriented plain text; there are no binary blobs and no cloud dependency.

Capabilities at a glance

• Modal vim-style editing with directional creation (one keystroke spawns a connected neighbor box or note).
• Semantic edge labels — prefixes such as call:, data:, event:, verify:, risk: render as colored chips and tint their arrow.
• Connector routing — straight by default, !spline for a curve, !ortho for a right-angle stair that slides clear of boxes in its way. Anchors are derived from the layout rather than stored, so a board renders the same in the app and in grafli render.
• Code-mode notes — minimal pseudocode for review-oriented diagrams: a bold function signature on the first line, control/effect keywords (if, for, call, emit, …) in blue, contract keywords (pre, post, verify, risk, …) in red, and clickable @file:line refs.
• Sketchnote symbols — a curated 30-symbol vocabulary (20 semantic actors and concepts, 10 emphasis marks) drawn from one hand-editable SVG sheet: *lightbulb fills a node, *lead:lock sits beside the label, *badge:flame overlays a corner, and *badge:3 numbers a sequence (1–99). Picked visually via style mode → i.
• Tasks (T: / TODO:), questions (Q: / QUESTION:, both case-insensitive), and threaded discussions inside notes.
• Find and focus — combine these at will:
  • Subgraph focus (B) — fade everything not reachable from the selection; cycle direction (incoming / outgoing / both) and depth (1-hop / unlimited).
  • Complexity heatmap (A) — color nodes by connectivity to find hot spots.
  • Dim connectors (,) / dim notes (Shift+N) — fade arrows or text-notes to 8% opacity to read the rest.
  • Minimap (M) — corner overview with boxes, notes, and connector density.
• Jump labels and graph navigation — every visible element is one or two keys away; hold Alt to follow connectors edge by edge.
• Sub-graflis — link any node to a deeper diagram in its own file.
• Bookmarks & flows — save labeled viewpoints (semantic anchors, not pixel coords) and string them into guided tours: step through, auto-play, present fullscreen (F5), or export a slide PDF (grafli export … --flow). Plain text, so an AI can author an explanatory tour through a big graph.
• Markdown resources — attach a markdown note to any element and edit it in textli, grafli's full-window Markdown editor (its own project, bundled as a dependency).
• Images as first-class nodes — paste or drag in raster and .svg files (in-tree files are referenced in place, external ones copied into the board's vault), press i to place an SVG mockup that opens in your drawing app, and let the file watcher refresh every external edit live on the board. SVGs render vector-crisp at any zoom and in exports.
• Auto-save and external file watching — open a .grafli next to your editor; changes flow both ways.
• Scratch board — start grafli with no file and you land on a persistent ~/grafli-scratch.grafli, autosaved like any other board, so a quick sketch is still there next time.
• Light and dark themes — the same warm paper style in two grounds, switched live with the sun/moon button or ⌘+Shift+D and remembered across restarts. %color tokens are semantic, so a board reads correctly in either theme.
• Yank as PNG (Y), SVG export (Ctrl+E).

File format

@ box frontend "Frontend" 100,100 160x60 %secondary
@ box backend  "Backend"  320,100 160x60 %primary
@ box db       "Database" 320,240 160x60 %subtle

@ arrow frontend -> backend "REST API"
@ arrow backend  -> db      "data: queries" !dashed

@ note 100,240 "SPA with React"
@ note logic 100,320 """
code:
handleRequest(req) -> Response
pre req.id is set
call validate(req)
emit RequestAccepted(req.id)
return ok  @api/handler.py:42
"""

Arrow operators: -> right, <- left, <-> both, -- none.

Triple-quoted block notes are supported when a note contains quote characters or spans multiple lines.

Keybindings (selection)

The full set is in the in-app F1 dialog and on the documentation site.

Project

• Documentation: https://grafli.mistergc.dev
• Source: https://github.com/MisterGC/grafli
• Issues: https://github.com/MisterGC/grafli/issues

License

MIT