Start with Archlore

You are a person? Give this page to your AI assistant — Claude Code, Cursor, Codex or any other — in the folder that holds your repositories. It does the rest; you only confirm a sign-in in the browser once.

Set up Archlore for this workspace by following https://app.archlore.dev/start

Instructions for the AI assistant

You are setting up Archlore for the person you work with. Archlore keeps a map of their system's architecture (services, endpoints, the tables and external APIs each one reaches) and the decisions behind it (ADRs), shared by their whole team and by every AI that works on the code. Archlore's server runs no AI: you do the thinking, on this person's tokens. Source code never leaves this machine — only the map does.

Do everything below yourself. Do not ask the person to configure anything. The only thing they do is open one link and confirm a code. Every command takes --json and never waits for input; when something fails, its JSON has a fix — do what it says.

1. Check the machine

npx -y archlore@latest doctor --json

Needs Node.js 18 or newer. ok: true means signed in and the server is reachable — skip to step 3.

2. Sign in (the only step that needs the person)

npx -y archlore@latest login --start --json

It opens a page in their browser and returns url and userCode. Tell the person, in their language: “Open this link, sign in or create an account, and confirm the code <userCode>.” Show the url. Then:

npx -y archlore@latest login --wait --json

Exit code 2 (status: "pending") means they have not confirmed yet — run it again. status: "signed_in" means you are done.

3. Map the code

One product = one organization; each git repository = one project in it (a repository's own services and containers stay inside its project).

The current folder holds several repositories of one product:
```
npx -y archlore@latest workspace . --org "<product name>" --json
```
Use the product's real name (ask the person only if you cannot tell it from the repositories). A repository already in another of their organizations is reported otherOrg; add --move to bring it in.
The current folder is one repository:
```
npx -y archlore@latest . --json
```

The JSON gives the project (or product) URL — show it to the person — and ai.open: how many questions the scan left for you.

4. Connect the Archlore tools (MCP) and skills

The scan writes .mcp.json in each repository; Claude Code and Cursor pick it up (reload the MCP servers or start a new session if the archlore tools do not appear). Install the skills in each repository, so every future session there knows how to use Archlore:

npx -y archlore@latest init-ai <path-to-repository>

It also adds a Claude Code session-start hook to .claude/settings.json: every new session there begins with npx archlore brief — the product's accepted ADRs, the team's rules, proposals waiting on a person and plans in progress. These files are meant to be committed; mention that to the person.

5. Answer the questions the scan left for you

If ai.open is above zero: call the MCP tool ai_tasks_next, read the code each task points at (file:lines in this checkout), answer with ai_tasks_submit, repeat until none are left, then run the scan from step 3 again to publish the answers. On a big codebase, split the work across sub-agents — a task is never handed out twice.

6. Record the architecture decisions

Call list_adrs. For the decisions you can see in the code that are not recorded yet — boundaries between services, who owns which data, how services talk (HTTP, queues such as Kafka), shared libraries, rules every endpoint follows — call propose_adr (context, decision, consequences, alternatives; link the repositories and services). They stay proposed until a person accepts them on the website; never claim they are accepted. Write everything you store in English.

7. Tell the person what is ready

Give them the product URL, how many repositories were mapped, and how many ADRs are waiting for their decision at https://app.archlore.dev → the product → Decisions.

From now on, while you work on this code

At the start: the accepted ADRs and the team's rules arrive by themselves (MCP instructions; the Claude Code hook). Follow them. Without them: npx archlore brief.
Before editing: find, impact, get_endpoint — the blast radius first. To change a boundary or a flow, read the ADR that covers it with get_adr.
To show an idea: a change to something that exists starts from sketch_now (page Now, from the map); add a page Proposed with base: "Now" keeping the ids of what stays, and draw_diagram both: same layout, the change marked, what goes as a dashed ghost. Anything else: draw_diagram. https://app.archlore.dev/sketch/new is a board people draw on together without an account.
A decision came out of it: propose_adr, with the sketch in links.sketches. A person accepts it on the website.
Before you finish: npx archlore diff — what the change breaks for the other repositories of the product — and, with archlore.rules.yaml, npx archlore check. Then scan again so the map stays current.