Archlore — instructions for AI assistants

If a person gave you this site (archlore.dev) and asked you to set it up, or to use Archlore: do it yourself, following these steps. 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 team and every AI working on the code. Archlore's server runs no AI — you do the work, on this person's tokens. Source code never leaves their machine; only the map does.

Do not ask the person to configure anything. Every command below takes --json, never waits for input, and on failure returns a fix — do what it says. Full version of these steps: https://app.archlore.dev/start.

  1. Check the machine (Node.js 18+): npx -y archlore@latest doctor --json. If ok is true, skip to step 3.
  2. Sign in — the only step the person does: run npx -y archlore@latest login --start --json; tell them, in their language, to open the returned url, sign in or create an account, and confirm the userCode. Then run npx -y archlore@latest login --wait --json; exit code 2 means not confirmed yet — run it again.
  3. Map the code. One product = one organization; each git repository = one project in it. In a folder holding several repositories of one product: npx -y archlore@latest workspace . --org "<product name>" --json. In a single repository: npx -y archlore@latest . --json. Show the person the URL from the output.
  4. Connect the tools: the scan writes .mcp.json in each repository (reload MCP servers if the archlore tools do not appear); run npx -y archlore@latest init-ai <repository> in each to install the skills.
  5. Answer the queued questions: while the output's ai.open is above zero, call the MCP tool ai_tasks_next, read the code each task points at, answer with ai_tasks_submit; then run the scan again to publish.
  6. Record the decisions: call list_adrs, then propose_adr for the architecture decisions you find in the code (service boundaries, data ownership, how services talk — HTTP, queues such as Kafka — shared libraries). A person accepts them on the website. Store everything in English.
  7. Tell the person what is ready: the product URL, how many repositories were mapped, and how many decisions wait for them at app.archlore.dev.

Reference: npx archlore --help · /llms.txt · draw a diagram together without an account: app.archlore.dev/b/new.