Quick start

Stand Alloy up on your repo in one sitting. Your interface is your agent (Claude Code or similar); the agent's interface is Alloy's skills and CLI. You talk; the agent runs the commands; you review and commit.

Want the reasoning behind each step? That is the full walkthrough.

Before you start - details and troubleshooting in Prerequisites:

• The @engineering11 registry scope in your global ~/.npmrc - Cloudsmith with your entitlement token (clients), or GitHub Packages with a read:packages token (E11 engineers). Check: npm view @engineering11/alloy-cli version.
• Node 22 or newer.
• A git clone of the repo to document, on your machine (see "Where you run this" below).
• An agent harness - Claude Code, Cursor, Codex, or OpenCode.

Where you run this

Everything on this page happens in a terminal, at the root of a git clone of your repo, with your agent opened in that same folder. A zip download from GitHub is not a clone - Alloy stamps every doc with the commit it came from, so it needs the .git/ history.

git clone <your-repo-url>
cd <your-repo>
claude   # or your harness's equivalent

A browser chat is not enough

The web version of Claude (claude.ai) cannot see your repo, cannot run the CLI, and does not have the /alloy skill. If your agent says /alloy is not an available tool, you are in the wrong place - open Claude Code (or your harness) from the repo root instead.

Give your agent the context, not the commands

Do not paste the commands on this page into the chat one at a time. Out of context, a private-registry token, a clone that 404s, and an unfamiliar slash command look like a credential problem, and the agent will refuse. Instead, paste one message that explains what you are doing:

I am following the Alloy quick start at https://docs.alloy.engineering11.com/00-getting-started/quick-start
from the root of my repo in Claude Code. Read that page and walk me through it, running the commands here.

Two rules that keep the session clean:

• Your registry token goes in your terminal only (the export in Prerequisites). Never paste it into the chat. The agent never needs to see it - npx reads it from your environment.
• If the agent declines something, start a fresh session with the message above rather than re-sending the same command. A refusal tends to harden with each retry.

0 - Get the skills into your agent

Running Foundry? Its installer already vendors the Alloy skills alongside the corpus wiring - skip to step 1. (If your Foundry install predates the skills, re-run its installer.)

Otherwise, one bootstrap command - the only command you type by hand, because it is the one that gives your agent its Alloy skills. From your repo root:

npx @engineering11/alloy-cli@latest init

The @latest keeps npx from reusing a stale cached CLI on a machine that ran an older Alloy before. alloy init creates this repo's knowledge base under .alloy/, vendors the four skills (alloy, alloy-survey, alloy-corpus, alloy-campaign) into .claude/skills/ (--ide cursor,codex,opencode for other harnesses), and registers the MCP server. That server is a second package, @engineering11/alloy-mcp, which your agent starts on its own from the same registry scope - nothing to install by hand.

Check it landed before going on. Quit your agent, start it again from the same folder, and type:

/alloy

The agent should recognise the Alloy skill and offer to set Alloy up or ask what you want to do. If it says /alloy is not an available tool, the skills did not land - confirm .claude/skills/alloy/SKILL.md exists in your repo, that you restarted the agent, and that you started it from the repo root rather than a parent or child folder. Nothing below works until this does.

1 - Survey

/alloy survey this repo

The agent reads your repo and drafts a source config - what gets documented, grouped how - into the gitignored .alloy-output/, iterating alloy survey . --check until it is green. It reports back: the units it found, the grain it chose, what it excluded and why, and its open questions.

How much the agent can enumerate for you depends on the repo. A JS/TS workspace or a .NET solution declares its own members, and the survey reads that declaration. A single-package JS repo has no such declaration yet: the agent lists its units by hand in units.yaml, so expect a smaller draft and more questions at step 2. Other ecosystems (Rust, Go, JVM, Python) get a path-glob config plus a scanner proposal in the draft's follow-ups.

2 - Review, in plain language

Read the report. Only you know your repo, so the question for you is: is it documenting the right things at the right grain? A unit (or a small set of units) per microservice is a reasonable rule of thumb. Ask the agent to explain anything - "what will you document and at what level of detail?" - and state changes as intent:

the two packages under tools/ are internal scripts, exclude them
split "frontend" - the SDKs and the infra packages are different things

The agent edits the draft and re-checks until green. When you would sign your name to it:

install the draft

The agent runs alloy install-draft, which weaves it into .alloy/; you commit it on a branch. That is your first commit.

3 - Campaign

/alloy-campaign

The agent documents every unit - context bundle, authored doc, quality gate, provenance stamp, per unit - and verifies the result mechanically, then reports what landed and any warnings. This fans out one agent run per unit, so on a large repo it can be slow and costly: run a sample (one unit per kind) as a cheap first pass, or one kind at a time, before documenting everything. Review the docs, commit them.

You now have a knowledge corpus for your repo - every unit documented, validated, and stamped with the commit it was derived from.

4 - See it

start the alloy console

The agent runs alloy console (read-only, local). Open it and click Graph in the sidebar - your whole corpus as a live relationship map. Browse a doc, check Coverage and Freshness while you are there.

From here

• Cross-cutting knowledge - patterns, conventions, architecture - is step 7 of the walkthrough: tell the agent what to canonicalize.
• Keep it honest as the code moves: ask the agent to scaffold the CI (alloy init --ci) - step 5.
• Wire agents to read it: Integrate with agents.