omni-flow

What it gives you

• 10 built-in node types + 18 edge semantics — theorem/lemma/proposition/definition/paper for math; person/department/task for orgs; R/A/C/I responsibility edges; follows/answers/merges for conversations. Custom types are one JSON block away.

• Everything is customizable — per node: fill / border / text color, shape (8 kinds), icon, size, status badge; per edge: a named label, color, width, line style, arrow direction. Nothing is locked.

• Analysis, not just drawing — cycle detection, degree-centrality bottleneck report (find the single point of failure in your RACI chart), upstream/downstream dependency closure, one-key layered layout (cycle-tolerant).

• Text-first, AI-friendly — import/export Mermaid, Graphviz DOT, Markdown outline and JSON. graph.json is the single source of truth and diffs cleanly in Git. Batch-build diagrams by pasting Mermaid.

• agent-flow bridge — of import-af <id> turns any AgentFlow workflow into a diagram (gates become Yes/No labeled edges). OmniFlow maps; AgentFlow executes.

• Groups, notes, search, legend — colored subgraph containers, per-node Markdown notes, instant search with highlight, auto legend from the type registry.

• Bilingual light/dark Studio — local-only canvas at 127.0.0.1:4319, zh/en UI.

Related MCP server: litopys

Recommended install: give this repository to your agent

The best way to install OmniFlow is to point your coding agent at this repository (or paste the URL into the chat) and ask it to run the installer itself:

https://github.com/kanghelyu/omni-flow

OmniFlow is harness-agnostic: the same repository works with ZCode, Claude Code, Codex CLI, Cursor, Windsurf, or any agent that can run a shell command — on macOS, Windows, or Linux. The agent will:

1. clone or fetch this repository;

2. run install.sh (macOS/Linux) or install.ps1 (Windows);

3. automatically drop the bundled omni-flow skill into ZCode (~/.zcode/skills/omni-flow), Claude Code (~/.claude/skills/omni-flow), and Codex ($CODEX_HOME/skills/omni-flow) — so the agent instantly knows all templates, conventions and batch-import tricks;

4. link the of CLI into ~/.local/bin;

5. verify with of --version and of doctor.

No plugin marketplace, no harness-specific packaging. Re-running the installer always upgrades both the runtime and the skill together.

Node Markdown: put domain substance inside the graph

Every node owns a Markdown file: ~/.omni-flow/graphs/<id>/notes/<nodeId>.md. The box on canvas is the index; the .md holds the actual domain content:

Three equivalent channels: the "Full note" button in Studio, MCP tools of_set_note / of_get_note, or editing the file directly. The first line shows as a summary on the card.

Convention: short but dense (≤30 lines), one-line summary first, always attach verifiable identifiers:

• Papers / books: include the DOI or arXiv id (e.g. arXiv:2203.04205, doi:10.1007/978-1-4612-0881-2); attach the absolute path or file:// link when a local copy exists

• Theorems: full statement + proof idea + list of prerequisite lemmas

• Persons: one-line identity + focus + local CV link

• Tasks: acceptance criteria + deliverable paths

• Sessions: summary + open questions + related sessions

Skeleton example (paper node):

Nilpotent Orbits in Semisimple Lie Algebras
- doi:10.1007/978-1-4612-0881-2 | local: ~/Books/nilpotent-orbits.pdf
- Key results: classification of nilpotent orbits, orbit closure order
- Role here: reference for Theorem 4.1

Bundled skill: install the plugin, get the skill; invoke the skill, use the plugin

skills/omni-flow/SKILL.md ships with the plugin and is auto-installed by both installers into ZCode / Claude Code / Codex skill directories (symlink/junction — single source). For any agent:

• Invoking the skill = already using OmniFlow (it contains all usage: template selection, batch import, node .md content conventions, analysis recipes) — no separate plugin call needed;

• Invoking the plugin (CLI/MCP/HTTP) means the skill is already in place, so agent context is aligned automatically.

Quick start

bash install.sh          # macOS / Linux → ~/.omni-flow + of on PATH + skills auto-installed
of doctor
of templates             # 7 scenario templates
of create "W-algebra paper deps" --template theorem-deps
of studio                # → http://127.0.0.1:4319

Windows PowerShell: Set-ExecutionPolicy -Scope Process Bypass then .\install.ps1.

Requirements: Node.js ≥ 18. Zero npm dependencies.

Bundled agent skill

skills/omni-flow/SKILL.md ships with the plugin and is installed automatically by both installers. It teaches any agent:

• how to pick a template for each scenario (theorem deps → theorem-deps, team split → task-raci, …);

• how to batch-build graphs as text (Mermaid/JSON first, refine in Studio);

• the full-customization surface (node triple colors / 8 shapes / status badges; edge labels, colors, styles, arrows);

• analysis recipes (RACI single-point-of-failure via centrality, proof-chain tracing, cycle audit).

For MCP-capable agents, register the server once and all 36 tools become native tools:

{ "mcpServers": { "omni-flow": { "command": "of", "args": ["mcp"] } } }

Standard interfaces for every agent

OmniFlow exposes three fully equivalent layers — pick whichever your agent speaks:

1. MCP (recommended) — 36 tools over the standard Model Context Protocol (stdio JSON-RPC 2.0). Works with Claude Code, Codex CLI, WorkBuddy, Cursor, and any MCP client:

{ "mcpServers": { "omni-flow": { "command": "of", "args": ["mcp"] } } }

2. HTTP JSON API — 21 endpoints + SSE on 127.0.0.1:4319 (start with of studio --no-open).

3. CLI — 12 subcommands for humans and shell-capable agents.

Full reference: docs/API.md.

Command reference

Scenarios

Data model

{
  "nodes": [
    { "id": "thm-1", "type": "theorem", "label": "Theorem 4.1",
      "fill": "#7C3AED", "border": "#6D28D9", "textColor": "#F5F3FF",
      "shape": "rect", "icon": "∎", "status": "doing" }
  ],
  "edges": [
    { "id": "e1", "source": "lem-1", "target": "thm-1",
      "type": "depends-on", "label": "核心引理",
      "color": "#2563EB", "style": "solid", "arrow": "one", "width": 2 }
  ],
  "groups": [ { "label": "技术线", "color": "#2563EB", "members": ["d-dev"] } ]
}

Long notes live at graphs/<id>/notes/<nodeId>.md (Markdown-first).

Relationship to AgentFlow

AgentFlow is a workflow executor: Markdown steps, deterministic Boolean gates, a runtime. OmniFlow is a relationship mapper: any domain, full visual freedom, graph analysis. Neither replaces the other — OmniFlow can import any AgentFlow workflow for visualization and review.

Design boundaries

• Local-first: storage under ~/.omni-flow, Studio binds 127.0.0.1 only, no telemetry.

• Zero dependencies: Node ≥ 18 standard library only.

• graph.json is the source of truth — edit it directly if you like; validation runs on every write.

License

CC BY-NC 4.0

License

CC BY-NC 4.0 (Attribution-NonCommercial 4.0 International) — free to use, modify and redistribute for non-commercial purposes with attribution; commercial use requires a separate license from the author. Non-viral: derivative works are not bound by this license and may choose their own terms.