What is archik?

Your architecture lives in plain YAML. You edit it through a CLI, a validator rejects drift before it merges, and a live canvas renders it in the browser. AI agents — Claude Code, or anything that speaks MCP — read the same YAML as the map of your system, so they reason about structure instead of guessing from filenames.

One chain runs from a stakeholder request to a passing test, and every link is checked mechanically:

Actor → Use case → Slice → Tests → Sequence diagram → Nodes → Source

Nothing in that chain can quietly fall out of sync with the code.

Install

Requires Node.js ≥ 20.

npx archik@latest init

init scaffolds .archik/main.archik.yaml and installs the Claude Code skill and /archik:* slash commands. As a Claude Code plugin instead:

/plugin marketplace add bacharSalleh/archik
/plugin install archik@archik

Both paths install the same skill and commands and use the archik npm binary, so Node is required either way.

Quick start

npx archik init     # scaffold
npx archik start    # live canvas at http://localhost:5173

Then, in Claude Code, start every project with:

/archik:bootstrap   # detects project state, routes to the next step

Day to day:

| You type | You get | | --- | --- | | /archik:suggest <feature> | A staged diagram change, shown as a green/red diff on the canvas — accept or reject | | /archik:usecase <name> | A use case with flows, slices, and test paths | | /archik:trace | The coverage matrix — "are we done?" |

Already have docker-compose or Mermaid? Bootstrap from it instead of a blank canvas:

npx archik import compose --out .archik/main.archik.yaml
npx archik import mermaid docs/architecture.mmd --out .archik/main.archik.yaml

Compose services become nodes (postgres → database, kafka → stream, …), build contexts become sourcePaths, and depends_on becomes edges.

The model

version: "1.0"
name: Support Hub
nodes:
  - id: api
    kind: service
    name: Support API
    sourcePath: src/api          # must exist on disk — validator-enforced
    description: REST API serving the customer support frontend.
    owner: team-support          # optional — who to talk to
  - id: claude
    kind: llm
    name: Claude
    description: LLM backend for draft generation.
edges:
  - id: api-claude
    from: api
    to: claude
    relationship: invokes

There are no coordinates — layout is computed by ELK on every render, so diffs stay meaningful. Each concern is a separate file, cross-checked by the validator:

| Layer | File | Captures | | --- | --- | --- | | Structure | .archik/main.archik.yaml | Services, databases, queues, agents, LLMs, edges | | Actors | *.archik.actors.yaml | Who initiates use cases | | Requirements | .archik/usecases/*.archik.uc.yaml | Flows and slices that name test paths | | Behaviour | *.archik.seq.yaml | UML-subset sequence diagrams | | Progress | *.archik.alphas.yaml | Essence/SEMAT alphas, machine-verified |

Full schema: npx archik schema (also schema seq | uc | actors).

Keeping the model honest

A set of commands prove the diagram still matches reality, at every altitude:

npx archik validate            # schema + cross-file integrity + governance constraints
npx archik drift               # nodes/tests vs the source tree
npx archik drift --edges       # edges vs the TS/JS import graph (shadow + phantom edges)
npx archik affected --since main --run   # changed files → nodes → slices → run their tests
npx archik trace --fail-on partial       # coverage matrix; gate CI on incomplete traceability
npx archik otel check --graph deps.json  # edges vs a production service-dependency graph

validate proves the model is internally consistent, drift that it matches the code, and otel check that it matches production traffic. Gate every commit locally:

npx archik hooks install       # pre-commit: archik validate

Large models stay readable: archik complexity flags over-large files, hub nodes, and deep nesting with a concrete fix for each, and archik q neighbors <id> / archik render --focus <id> show one node's neighbourhood instead of the whole map.

AI integration

Claude Code. archik init installs a skill that enforces one rule — Claude talks to archik only through the CLI, never by editing YAML directly. Reads go through archik q, writes through archik suggest set, and you approve every structural change on the canvas.

Everything else (MCP). archik mcp runs a stdio Model Context Protocol server exposing the same contract — tools for schema, queries, trace, validate, drift, and the suggestion lifecycle, plus resources (archik://schema, archik://stats, archik://trace) and prompts that encode the same loop:

// .cursor/mcp.json, claude_desktop_config.json, etc.
{
  "mcpServers": {
    "archik": { "command": "npx", "args": ["archik", "mcp"] }
  }
}

Teams and governance

• Semantic merges. Nodes and edges are id-keyed, so most YAML merges are mechanical instead of line-based conflicts: archik merge-driver --install.
• Ownership. owner: on a node answers "who do I talk to" (archik q list --owner team-billing), and archik owners sync writes one CODEOWNERS rule per owned node into a managed block.
• Governance constraints. Architecture fitness rules enforced by archik validate:

constraints:
  - id: billing-isolation
    description: Only billing-context nodes may write to billing-db.
    forbidEdge:
      relationship: writes
      from: { notParent: billing }
      to: { id: billing-db }
  - id: services-owned
    description: Every service and worker declares an owning team.
    requireOwner: { kinds: [service, worker] }

Intentional exceptions are grandfathered by id in an except list — visible in review, never silent.

CI

Run the commands directly, or use the GitHub Action, which validates, checks drift and traceability, and posts a sticky PR comment with the architecture diff against the base branch:

# .github/workflows/archik.yml
name: archik
on: [pull_request]
permissions:
  contents: read
  pull-requests: write
jobs:
  archik:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: bacharSalleh/archik@main
        with:
          trace-fail-on: partial   # optional gate; omit for report-only

Inputs: path, working-directory, validate, drift, trace-fail-on, compare-ref, comment, github-token, version.

Self-evolution

Opt-in, local-only, and human-gated: archik evolution observes how you use it (accepts, rejects, validate/drift runs), turns recurring friction into proposals you review, and records approved lessons in .archik/evolution/learned.md — which the Claude skill reads at session start, so the AI improves across sessions without anyone editing prompts. The same designs ship as a reusable library via archik patterns. See docs/advanced-topics.

CLI reference

Every command supports --help; agent-facing commands support --json.

| Command | What it does | | --- | --- | | archik init | Scaffold + install the Claude skill and slash commands | | archik dev / start / stop / status | Live canvas lifecycle (foreground / detached) | | archik validate [path] | Schema + cross-file + constraints (exit 1 on error) | | archik complexity [path] | Flag over-large files, hub nodes, deep nesting (--fail-on-warn to gate) | | archik render --out <svg> | Headless SVG render (--seq <path>, --focus <id>, --hide-structural) | | archik watch | Re-render SVG on every change | | archik q <sub> | Query: describe deps dependents neighbors impact list edges stats usecases describe-usecase actors sequences | | archik diff <a> [b] | Diff two files or git refs; one arg = that ref vs working tree | | archik affected | Changed files → nodes, slices, tests (--since <ref>, --files, --run) | | archik trace | Coverage matrix (--fail-on partial\|none for CI) | | archik drift | sourcePath / test-path gaps (--edges verifies edges vs the import graph) | | archik otel check --graph <f> | Verify edges against a production service-dependency graph | | archik suggest <sub> | Suggestion sidecar lifecycle: show set accept reject | | archik alpha <sub> | Essence alphas: show, promote, demote | | archik evolution <sub> | Self-evolution loop: enable reflect proposals approve reject report | | archik patterns <sub> | Pattern library: list show <id> apply <id> | | archik import compose\|mermaid [file] | Bootstrap from docker-compose or a Mermaid flowchart | | archik merge-driver --install | Semantic git merge for *.archik.yaml | | archik hooks install | Pre-commit hook running archik validate (--with-drift optional) | | archik owners sync\|check | Keep CODEOWNERS in step with node owners | | archik mcp | MCP server over stdio for non-Claude-Code agents | | archik schema [seq\|uc\|actors] | Print the document schemas | | archik upgrade | Upgrade + refresh installed skill/commands |

Default file resolution: .archik/main.archik.yaml, falling back to the legacy architecture.archik.yaml (both present is an error).

When to use it

Reach for archik when a project has more than a handful of components, ships with an AI agent you want reasoning about structure, needs "are we done?" to be mechanically answerable, or wants CI to fail on architectural drift. Skip it for one-file scripts, slide-deck diagrams (use Mermaid), or projects with no build or CI.

| | archik | Mermaid / PlantUML | Structurizr | | --- | --- | --- | --- | | Source format | Plain YAML | Custom DSL | Structurizr DSL | | AI-editor integration | Skill + MCP | None | None | | Use cases / test traceability | Mechanical | No | No | | Drift detection | Yes | No | No | | Governance constraints | Yes | No | No | | Validator | Schema + cross-file + ECB | Syntax only | Syntax only |

Contributing

See CONTRIBUTING.md.

npm install
npm run archik -- --help     # run the CLI from source
npm test                     # vitest
npm run typecheck

License

MIT © Bashar