Smartypants

The architecture diagram that draws itself while your coding agent works — and tells you when the code wanders.

Your agent forgets what you asked for. Smartypants doesn't. It hooks into Claude Code, Codex, Pi, Muse Code, and Grok Build, keeps one layered diagram of the system current on every turn, and flags the moment a diff leaves the design you described.

Live demo · Install · How it compares · Proof · What leaves your machine

• Live, not a snapshot. Prompts, edits, and the end of every agent turn update the diagram in the background. Your agent never waits.
• Drift against what you said. Decisions and constraints from the conversation are kept as IntentCode (~200 tokens per design). At turn end, one batched check reads what changed in git; code that breaks a decision, a constraint, or a boundary turns red.
• Catches up on existing repos. From code plus compose, Kubernetes, Helm, and Terraform: real service names, flows, and network boundaries, in about a minute (LiteLLM, 13k files: 72 s and about $1 with Claude Code's default model, $0.21–0.52 with Sonnet 5.5).
• Reads like a staff engineer drew it. Users on top, storage at the bottom, the journey left to right, boundaries as frames. Each box has a plain name and one line; click it for the why.

Install

npm install -D @logan-robbins/smartypants
npx smartypants init        # hooks for every host + config; catches up if code exists
npx smartypants serve       # open the printed URL

The model is Claude, signed in the way your Claude Code already is. Smartypants runs this machine's claude CLI headless (tool-less, settings-less, one answer per call), so whatever Claude Code uses works with no extra key: ANTHROPIC_API_KEY, Bedrock / Vertex / Foundry, a gateway on ANTHROPIC_BASE_URL, or your claude login. Two roles:

• Decisions: Claude Sonnet 5.5 at high effort answers the small per-turn questions (is this worth remembering, does this diff conform). ~3 s and ~$0.003–0.01 each, and the most accurate setting we measured (results).
• Writing: Claude Code's default model for your sign-in writes the diagram and drift notes, only when a decision says there is work. Pin it with "model".

On another harness without Claude Code, pick its builder with init --flavor codex|pi|grok|meta (Config).

Alternative: Typesafe Jev for the decisions. ~0.2 s per decision for a fraction of a cent; Claude still writes, and answers the decisions itself if Jev is unreachable:

1. Sign in at console.typesafe.ai/keys and create an API key.
2. export TYPESAFE_API_KEY=... in the shell that starts your agent (or put it in a dotenv file and set "envFile", or enter it in the Claude Code plugin's "Typesafe (Jev) API key" setting).
3. Set "decider": "jev" in smartypants.config.json and restart the agent session.

Or as a plugin: /plugin marketplace add logan-robbins/smartypants then /plugin install smartypants@smartypants (Claude Code) · codex plugin marketplace add logan-robbins/smartypants (Codex) · pi install git:github.com/logan-robbins/smartypants (Pi) · npx skills add logan-robbins/smartypants (any skills host).

No key? See it first: npx smartypants demo youtube-top-k && npx smartypants serve, or the live demo (source in site/).

Then just work. Say "design YouTube top-K" and the diagram appears; say "go deeper on the aggregator" (or double-click it) to expand a box; let the agent code and watch for red.

On a project with code, going deeper reads the code. Ask "go deeper on how the MCP credentials are managed" and Smartypants finds the matching files, lets Claude read them (read-only: Read, Grep, Glob), draws the real modules with each note citing its file, and corrects the diagram wherever it disagreed with the code. The corrections print and are saved to .smartypants/deeper.json. On LiteLLM this took 75–94 s and $0.43–0.53.

How it compares

	Smartypants	Archify	drawio-skill	Whiteboard	GitDiagram · DeepWiki	ArchUnit · dep-cruiser
Updates by itself as the agent works	every turn, via hooks	on request	on request	on request	on request	in CI
Knows what you asked for	yes (IntentCode)	chat context	no	decision log	no	rules you write
Flags drift	per turn, vs your intent	before/after diff	diagram diff	no	no	rule violations
Existing repo + Helm/k8s/compose/TF	yes, background	repo	code + IaC	repo	repo	code only
Output	layered interactive canvas, Mermaid export	animated HTML	draw.io	desktop canvas	web diagram / wiki	test failures

Archify draws a great poster; Smartypants keeps the map and sounds the alarm. Details and sources: docs/research/competitors.md.

Proof

Live runs, Claude Sonnet 5.5 deciding and Claude writing (results · Jev deciding · with Muse Spark writing · selector benchmarks):

	result
Stop-hook review of labeled agent changes × 2, end to end	22/22 drift flags right, 0 missed, 0 false alarms, 10.2 s per turn (Jev deciding: 22/22, 7.3 s)
Held-out triage, 34 turns + 10 edits	Sonnet 5.5 high: 32/34 exact, 34/34 keep-vs-skip, 9/10 drift verdicts, 0 missed (Jev: 29/34 per rep; local rules alone 18/34)
Per-turn decision	Sonnet 5.5 high ~3 s, ~$0.003–0.01; Jev ~0.2 s
Five design interviews (32 turns, 10 edits), Muse Spark writing	triage 32/32, all 33 expected parts drawn, drift 10/10, $0.015 total
Noise turns ("thanks", "run the tests")	$0, no model call
Catch-up of LiteLLM (12,996 files, 10 code units)	21 parts, 31 flows in 72 s; $1.02 with Opus 5.5 (Claude Code's default), $0.21–0.52 with "model": "claude-sonnet-5-5"
Catch-up on 10 open-source repos, Muse Spark writing	36–115 s, $0.001–0.011 each (crawler notes)

Caught up from code alone — GoogleCloudPlatform/microservices-demo (11 services, Istio gateway, AlloyDB, GCS), twenty, and immich:

The canvas

top to bottom
Users and clients	who starts the journey
Edge	CDN, WAF, load balancer, ingress, gateway
Frontend → API → Services	third parties at the right edge
Async	streams first, then the workers that consume them
Data	caches beside the databases they front
Storage	always the bottom row

Inside a row the journey runs left to right. Dashed frames are network and trust boundaries. Everything is clickable and draggable — boxes, subgraphs, arrows, frames, layer labels. A click leads with why the part exists (the requirement or trade-off that forces it), then what it does, deep-dive notes, flows, drift, and the intent recorded about it.

Keys: F fit · T tidy · L tiers/flow layout · I intent memory · / search · double-click to go deeper.

What leaves your machine

Nothing, in a project without smartypants.config.json. With the default claude builder: design turns, part names, changed-file diffs at turn end, and (for catch-up) key source files go to Claude through your own Claude Code, under the same account, provider, and data terms it already uses. Smartypants never reads or stores a Claude credential. With "decider": "jev", per-turn triage questions (turn text, part names) go to Typesafe (Jev). With the meta builder they go to api.meta.ai, whose default muse-spark-1.3-contributor tier may be used for training ("model": "muse-spark-1.3" opts out). Keys are never written to the diagram, memory, or logs; the plugin stores the ones you enter in your OS credential store.

Commands

smartypants catchup     build the diagram from existing code, in the background
smartypants review      review what the working tree changed, now
smartypants deeper X    system → components → modules → deep-dive notes, read from the code
smartypants intent      print the IntentCode memory
smartypants drift       list where code left the intent
smartypants mermaid     export Mermaid
smartypants stats       turns skipped, calls, tokens, cost
smartypants demo NAME   shop-monorepo · youtube-top-k · uber · news-feed · messenger · url-shortener
smartypants reset       clear the diagram and memory

Plugin commands mirror these: /smartypants, /smartypants:deeper, :catchup, :review, :intent, :drift, :diagram, :mermaid, :reset-graph.

Config

smartypants.config.json is the on switch. init writes:

{ "flavor": "claude", "depth": "auto", "seed": false, "decider": "auto", "deciderModel": "claude-sonnet-5-5", "deciderEffort": "high", "background": true, "review": "turn" }

key	meaning
flavor	builder: claude (default; this machine's Claude Code and its sign-in), codex (OPENAI_API_KEY), pi, grok (XAI_API_KEY), meta (Muse Spark, META_API_KEY), muse
model	builder model; unset = Claude Code's default for your sign-in (e.g. claude-opus-5-5, or an alias like sonnet)
depth	auto (start from what you said, go finer as you do) or system / component / module
decider	who answers the per-turn menus: auto (with the claude builder: Claude, then local rules), jev (Typesafe Jev with TYPESAFE_API_KEY; Claude if Jev is unreachable), claude, meta, heuristic
deciderModel	the Claude model for those menus; default claude-sonnet-5-5
deciderEffort	low · medium · high (default) · xhigh · max
review	turn (once per agent turn), edit (every edit), both
background	hooks return immediately; a project worker does the work
seed	existing codebase: catch up from code
autoDeepen	expand a box on its own when detail piles up (default 3; false to disable)
envFile	dotenv path for keys
watch	diagram another Claude Code / Codex instance (docs/WATCH.md)

Hosts

host	hooks	notes
Claude Code	prompt, edit, Stop	project settings or the plugin
Codex	prompt, apply_patch, Stop	approve the hooks once in Codex's hooks review
Pi	input, tool_result, agent_end	project extension or pi install; Pi itself can run on Muse Spark
Muse Code, Grok Build	prompt, edit	.muse/hooks.json, .grok/hooks/smartypants.json

How it works

Two jobs, the way WindTunnel pairs a selector (Jev) with a writer (Mercury): one model decides, Claude writes. A free local pass drops noise. The selector, Claude Sonnet 5.5 at high effort by default or Typesafe Jev as the alternative, then answers small closed menus: is this worth remembering, does it change the design, at what level, which part, does this diff conform. The writer runs only when the selector says there is work, and writes it: the diagram delta, the drift note, the IntentCode. An unsure pick leans toward doing the work, and the writer decides what actually lands, so a borderline file costs one write rather than a missed drift. Details: docs/ARCHITECTURE.md · docs/INTENTCODE.md · docs/PROMPTING.md · go-to-market: docs/GTM.md.

Develop

npm test                      # no network, no sign-in (a fake claude CLI stands in)
npm run eval                  # live interview transcripts on the Meta API (cents)
npm run eval:triage           # held-out triage benchmark
npm run eval:turnend          # turn-end review on labeled agent changes
node scripts/build-site.mjs   # website demo into site/demo

License

Apache-2.0. Use it, fork it, ship it; keep the NOTICE with any copy or derivative so the credit travels with it. Citing it: CITATION.cff.