Sketchi

Typed, deterministic diagrams for people and AI agents.
Prompt to validated IR to editable Excalidraw and hosted PNG artifacts.

---

Sketchi is the canonical Nx and Cloudflare workspace for generating reliable, editable diagrams. Model output is never treated as a finished drawing: it is parsed into a typed intermediate representation, validated, laid out by code, converted to real Excalidraw elements, and persisted as an artifact with PNG and scene representations.

What Sketchi Does

• Creates hosted flowcharts and mindmaps from natural-language prompts.
• Produces validated, editable Excalidraw scenes instead of opaque images.
• Exposes Code Mode through MCP and versioned HTTP artifact endpoints.
• Keeps layout, bindings, wrapping, and scene conversion deterministic in code.
• Tests diagram contracts with fixtures, maintained scenarios, real-scene validation, component tests, and Storybook.
• Converts a curated SVG corpus into native Excalidraw elements and libraries.

CLI

Install Sketchi from npm, or use the noninteractive installer to install the same package and configure Zsh, Bash, or Fish completions:

npm install -g sketchi

# Or install and configure completions in one step:
curl -fsSL https://raw.githubusercontent.com/shpitdev/sketchi/main/install.sh | sh

Create a canonical document, inspect and revise it, list the local store, then export editable Excalidraw:

sketchi create --json '{"type":"flowchart","spec":{"id":"release-flow","title":"Release approval","nodes":[{"id":"start","label":"Change proposed","kind":"start"},{"id":"review","label":"Review evidence","kind":"process"},{"id":"end","label":"Release approved","kind":"end"}],"edges":[{"source":"start","target":"review"},{"source":"review","target":"end"}]}}'
sketchi show release-flow
sketchi edit release-flow --json '{"type":"flowchart","spec":{"id":"release-flow","title":"Release approval revised","nodes":[{"id":"start","label":"Change proposed","kind":"start"},{"id":"review","label":"Review complete evidence","kind":"process"},{"id":"end","label":"Release approved","kind":"end"}],"edges":[{"source":"start","target":"review"},{"source":"review","target":"end"}]}}'
sketchi patch release-flow --json '{"operations":[{"op":"setStyle","selector":{"nodeIds":["review"]},"style":{"fillColor":"#dbeafe","strokeColor":"#2563eb"}}]}'
sketchi list
sketchi export release-flow --format excalidraw --dest release-flow.excalidraw
sketchi export release-flow --format png --dest release-flow.png
sketchi restore release-flow --revision 1

Generate and persist a diagram through the public, unauthenticated Sketchi API:

sketchi generate --prompt "Map release approval with pass and revise branches"

create, patch, show, edit, list, export, and restore are deterministic, fully offline, and need no credentials. generate, share, and pull are explicit credential-free network commands, each making one HTTPS request. Share an immutable encrypted snapshot with sketchi share release-flow; after browser edits are exported to a new Excalidraw link, apply it with sketchi pull release-flow --link URL. All commands support --output json. PNG export renders on demand through Excalidraw plus bundled fonts and WASM when no PNG is stored, without modifying the record. PNG file exports include a generic inline-Markdown display hint for calling agents; export status uses stderr and --dest - keeps stdout byte-only. Generate completions directly with sketchi --completions zsh, sketchi --completions bash, or sketchi --completions fish. See the complete CLI guide for file/stdin input, completion setup, storage details, and agent-oriented usage.

See the CLI changelog for what changed, or browse published versions on GitHub Releases.

Shell completions

The installer configures Zsh, Bash, or Fish completions for the detected shell. Generated Bash completions require Bash 4 or newer; the installed source block silently skips them on the stock macOS Bash 3.2. Bash login shells may not read .bashrc, so .bash_profile may need to source .bashrc for completions to be available.

Code Mode

Codex, Claude Code, Agy, and OpenCode can create hosted diagrams through the public Code Mode MCP endpoint. The agent quickstart contains installation, verification, and first-diagram instructions for every supported harness. The public flow does not require a Sketchi login, API key, or local browser installation.

prompt or revision
        ↓
model candidate → typed diagram IR → deterministic scene → Excalidraw artifact
        ↓                                      ↓                  ↓
 maintained scenarios                    validation          hosted PNG

Architecture

Boundary	Responsibility
packages/diagram/core	Typed diagram contracts, semantic validation, fixtures
packages/diagram/generation	Provider messages, responses, and candidate parsing
packages/diagram/agent	Canonical build runtime, quality checks, artifact orchestration
packages/diagram/renderer	Deterministic layout and scene generation
packages/diagram/excalidraw	Persistable Excalidraw conversion and real-scene validation
packages/diagram/scenarios	Maintained prompts, assertions, and local/live evals
packages/diagram/ui	Shared React diagram, review, and eval UI states
packages/studio/projects	Studio project/diagram contracts and object-bucket persistence
packages/svg-excalidraw	Native SVG-to-Excalidraw conversion and library serialization

The first high-reliability target is decision-heavy flowchart generation. flowchart and mindmap are explicit diagram families; unsupported families do not silently fall back to a generic template. See the full architecture guide and the MCP-first generation boundary.

Product Surfaces

Surface	Role	Local command
cli	Offline local authoring plus credential-free public generation	pnpm nx build sketchi-cli
web	sketchi.app home, docs, and setup	pnpm nx dev web
playground	Public Playground, Code Mode API/MCP, artifacts, Studio foundation	pnpm nx dev playground
icons	icons.sketchi.app curated icon browser	pnpm nx dev icons
eval-harness	Internal scenario and model-output eval harness	pnpm nx dev eval-harness
excalidraw	Internal real-canvas rendering and editing workspace	pnpm nx dev excalidraw

The internal harness is eval-harness. The public host is playground, while its durable Worker identity remains sketchi-studio and the extracted Studio persistence boundary remains packages/studio/projects. The completed repository migration and its historical before tree are recorded in the repository structure proposal.

Quick Start

Prerequisites: Node.js compatible with the pinned toolchain, Corepack, and pnpm 11.5.0.

pnpm install
pnpm dev

Run one surface with pnpm nx dev <project>. pnpm dev starts every Nx app with a dev target in parallel through Portless.

Development

Required workspace proof:

pnpm run test:deploy-scripts
pnpm run test:tools
pnpm nx run-many -t lint,typecheck,test,build
pnpm run test:wrangler-dry-runs
pnpm nx build-storybook diagram-ui
pnpm exec tsc -b --pretty false

For a CLI change that should ship, run pnpm changeset and commit the generated changeset with the change. Changesets maintains a Version Packages PR on main; merging that PR updates the CLI version and causes the existing release workflow to publish it.

Run the canonical deterministic scenario:

pnpm nx scenario diagram-scenarios -- \
  --scenario pharma-batch-disposition \
  --fixture \
  --out .memory/pharma-batch.excalidraw

Use a local model command by setting SKETCHI_GENERATOR_COMMAND; it receives the scenario prompt on stdin and writes candidate IR JSON to stdout.

Generate new owned surfaces through the workspace plugin:

pnpm nx g @sketchi/generators:ui-component StatusBadge
pnpm nx g @sketchi/generators:diagram-type mindmap --title "Sketchi mindmap fixture"

Deployment

Eligible same-repository pull requests build and deploy app-specific Cloudflare Workers when Cloudflare credentials are configured, then maintain one preview comment per app. Relevant merges to main deploy production Workers when those credentials are available; custom domain attachment remains an explicit operator action. Forks and unconfigured environments retain build proof without a Worker deploy. The eval harness and standalone Excalidraw workspace are internal surfaces.

Worker builds are isolated under dist/apps/<app> and resolved through an explicit Nx-project-to-Worker map, so parallel builds and later repository renames cannot overwrite or implicitly rename durable Worker deployments.

See preview deployments and the guarded production domain runbook.

pnpm deploy:eval-harness
pnpm deploy:playground
pnpm deploy:web
pnpm deploy:excalidraw
pnpm deploy:icons

Repository Map

apps/
├── cli/                          local authoring and generation CLI
├── eval-harness/                 internal scenarios and model-output evals
├── excalidraw/                   internal real-canvas workspace
├── icons/                        public icon browser
├── native-conversion-storybook/ explicit cross-app Storybook composition
├── playground/                   public Playground, API/MCP, Studio adapter
└── web/                          public home, docs, and setup
packages/
├── diagram/{agent,core,excalidraw,generation,renderer,scenarios,ui}/
├── studio/projects/              persistence contract and service
└── svg-excalidraw/               native SVG conversion
tools/sketchi-generators/         Nx generators and tests
scripts/                          deploy, cutover, and pipeline operations
plugins/                          Codex and Claude Code distribution payloads
docs/                             architecture, boundaries, and runbooks

pnpm, Nx, and the root TypeScript solution all cover the same package-backed projects. Nx tags plus lint enforce package/app, runtime/eval, persistence/UI, and explicit composition boundaries across source, config, and Storybook files. Required CI also dry-runs every mapped Worker from its generated build configuration; see the architecture guide.

Documentation

• Agent plugin quickstart
• Architecture
• Agentic generation
• MCP-first generation
• SVG conversion plan
• Repository replacement record

License

MIT. See LICENSE.