archik gives your project — and the AI editing it — one file that describes what the system actually looks like. Services, databases, queues, agents, LLMs, the edges between them. Plain YAML, schema- validated, no coordinates, no proprietary format.

Open it in your browser for a live canvas. Render it in CI for a self-contained SVG. The Claude Code skill and /archik:* slash commands install automatically with archik init, so the model edits the same file you do — the diagram and the codebase stop drifting because Claude treats the diagram as the spec.

If you've ever asked an AI agent "where would I add X?" and watched it guess from filenames, archik is the fix: the YAML answers the question, and Claude is required to read it before doing structural work.

Quickstart

Two terminal commands, then talk to Claude:

npx archik@latest init       # scaffolds .archik/main.archik.yaml +
                             # installs the Claude skill + /archik:* slash commands
npx archik@latest start      # opens the live canvas at http://localhost:5173

Then in Claude Code, type:

/archik:spawn               # mirror your real source tree as the first diagram
/archik:evolve              # propose a cleaner bounded-context refactor
/archik:suggest <feature>   # propose changes for a specific feature

Each /archik:* command stages a suggestion sidecar — Review in the canvas, then Accept or Reject. No manual YAML editing on either side: you click in the browser, Claude drives through the CLI.

Done with the canvas? npx archik stop.

What you write

version: "1.0"
name: Support Hub
nodes:
  - id: api
    kind: service
    name: Support API
    stack: Go + Postgres
  - id: agent
    kind: agent
    name: Support Agent
    description: Drafts replies, escalates risky ones.
  - id: claude
    kind: llm
    name: Claude
edges:
  - id: api-agent
    from: api
    to: agent
    relationship: invokes
  - id: agent-claude
    from: agent
    to: claude
    relationship: invokes
    label: draft reply

No x / y / width — layout is computed by ELK on every render. The schema rejects coordinates so diffs stay meaningful.

What it gives you

• Live canvas — archik dev (foreground) or archik start / stop (detached, multi-project).
• 27 node kinds across compute, data, messaging, networking, hexagonal, AI/ML, identity, observability, cloud, UI, and external.
• 12 relationships with distinct visual styling — http_call, invokes, reads, writes, publishes, subscribes, streams_to, routes_to, implements, depends_on, has_a, uses.
• Drag-to-connect, multi-select, undo/redo, compact view, themed (dark / light), notes per node, color overrides on edges.
• CI-ready CLI — validate, render (headless SVG), watch, check (drift between YAML and source dirs).
• AI skill + slash commands — archik init installs both automatically. Seven /archik:* commands (spawn, evolve, suggest, describe, dev, accept, reject) drive the diagram entirely through the CLI, so Claude never edits YAML by hand.

For Claude Code & other LLMs

The whole reason archik uses YAML instead of a binary format: the file is the shared map between you and the model. npx archik@latest init drops both the Claude skill and the seven slash commands into your project — no separate setup.

The skill enforces a hard rule: Claude talks to archik only through the npx archik CLI — never Read, Write, or Edit on a YAML directly. Queries go through npx archik q, suggestions through npx archik suggest set, lifecycle through npx archik suggest accept | reject. You own the file; the CLI is the contract.

The seven slash commands

| Command | What it does | | --------------------------- | ----------------------------------------------------------- | | /archik:spawn | Bootstrap a diagram by mirroring your real source tree | | /archik:evolve | Propose a cleaner bounded-context refactor | | /archik:suggest <feature> | Propose changes for a specific feature | | /archik:describe <id> | Explain a node and its connections | | /archik:dev | Open the live canvas | | /archik:accept | Apply the pending suggestion | | /archik:reject | Discard the pending suggestion |

A typical first-day flow:

/archik:spawn                     # mirror what's there now
                                  #   → review on the canvas, accept
/archik:evolve                    # propose a cleaner shape
                                  #   → discuss with Claude, accept (or iterate)
/archik:suggest add Stripe webhook handler
                                  #   → small, targeted change

Each command stages a sidecar via npx archik suggest set. The canvas shows a green/red/amber diff overlay; you click Accept or Reject — or /archik:accept / /archik:reject from the terminal. Same outcome either way.

Manual install (existing projects without archik init)

If you already have an archik file and just want to add the Claude integration:

npx archik@latest skill --user        # install skill into ~/.claude/skills (all projects)
npx archik@latest commands --user     # install /archik:* into ~/.claude/commands (all projects)

Drop the --user flag to scope to the current project only.

Commands

archik init [path]       Scaffold a starter .archik/main.archik.yaml
                         (also installs the Claude skill + /archik:* slash commands by default)
                         --no-skill       skip installing the Claude skill
                         --no-commands    skip installing the /archik:* slash commands

archik dev [path]        Open the canvas in your browser (foreground, Ctrl+C to stop)
archik start [path]      Same as dev, but detached — prompt returns immediately
archik stop [path]       Stop the background server started with `archik start`
archik status            List running archik instances across all projects
                         (dev / start share these flags)
                         --port <n>       dev server port (default 5173)
                         --host <addr>    bind address (default 127.0.0.1)
                         --no-open        don't auto-open the browser

archik validate [path]   Validate against the schema (CI-friendly, exit code 1 on error)
archik render [path]     Render to a self-contained SVG file
                         --out <file>     output path (default: diagram.svg)
                         --theme <name>   "dark" (default) or "light"
archik watch [path]      Re-render to SVG on every file change (Ctrl+C to stop)

archik suggest [sub]     Manage Claude's pending architecture suggestion
                         show             summarise the pending sidecar (default; --json supported)
                         set <draft>      validate a draft YAML and stage it as the sidecar
                                          --note '<text>'  set metadata.suggestion.note
                                          --main <path>    override main file detection
                                          --json           structured output
                                          -                read draft from stdin
                         accept           apply the sidecar over the main file
                         reject           discard the sidecar

archik skill             Install the Claude skill for AI editing
                         --user           install into ~/.claude/skills (all projects)
                         --force          overwrite an existing skill
archik commands          Install the /archik:* slash commands for Claude Code
                         --user           install into ~/.claude/commands (all projects)
                         --force          overwrite existing commands

Without a [path] argument, archik resolves the file in this order:

1. .archik/main.archik.yaml (preferred new convention — keeps the project root tidy)
2. architecture.archik.yaml (legacy root location — still fully supported)

If both exist the command errors out and asks you to pick one. New projects get the .archik/ layout from archik init; existing projects keep working without any migration.

Single instance per file is enforced via a lock file in $TMPDIR/archik-cli/, so parallel dev and start against the same YAML are rejected with a friendly error.

Use it in CI

# Fail the build on schema errors
archik validate

# Generate a committable SVG of your architecture for the docs site
archik render --theme light --out docs/architecture.svg

Schema

The full schema reference (every node kind, every relationship, common patterns, hard rules) lives in the AI skill. After installing it locally:

archik skill --user
$EDITOR ~/.claude/skills/archik/SKILL.md

Or read it directly in this repo: .claude/skills/archik/SKILL.md.

Design notes

• The YAML is the only persistent truth. The canvas is a stateless projection that reloads on every file change (live-reload via SSE).
• Layout is non-negotiable: ELK lays out every render. Putting an x / y / width field at any level fails schema validation. No more "the diagram drifted because someone dragged a box."
• The published npm package ships only the bundled binary — no source files, no build tooling. Zero runtime dependencies.

License

MIT © Bashar