Should an AI agent read the whole repository?

Usually not for a first architecture question. Start with entry points, service wiring, persistence, and the specific runtime path you need to understand. A smaller evidence set is easier to review and makes unsupported claims visible.

How do I stop the agent from inventing services?

List the allowed files, name the decision the diagram must support, forbid unsupported vendors and flows, and ask the agent to label uncertainty. Then verify every node and edge against source; prompt constraints help, but review remains required.

What should a human change first?

Correct the model before styling it: misplaced trust boundaries, collapsed storage responsibilities, missing queue transitions, incorrect ownership, or a hidden failure path. Those edits make the diagram useful for engineering decisions.

How does the diagram stay current?

Keep stable element ids, preserve the source scope beside the artifact, and ask the agent for targeted updates to the same persistent diagram after code changes. Review the diff in meaning, not just appearance.

Repository onboarding · persistent workflow

Turn an unfamiliar repository into a reviewable system map

Ask a coding agent to inspect only the files that define runtime boundaries. Make it show synchronous and queued paths, challenge the model in the browser, and keep the corrected architecture on one persistent canvas.

Question

Runtime path

Source

Named files

Agent

Bounded map

Human

Challenge model

Agent

Same-diagram update

Repository diagrams fail when the prompt asks for ‘the architecture’ without defining evidence. Start with a bounded question and a named file set, then make the first diagram answerable to human review.

Product boundary: Only send source your organization permits the chosen agent and Excaliwow to process. Exclude secrets, credentials, customer data, private keys, generated vendor trees, and unrelated files. Private Excaliwow implementation details are intentionally omitted from this public page.

Reproduce it

Copy setup

Start with a decision, not the whole repository

Ask what the diagram must help someone understand: request handling, data ownership, deployment, failure recovery, or another bounded path. Then select only the files that prove that path.

Connect the coding agent once

Mint a read + write PAT and add @excaliwow/mcp to the agent that can already inspect the repository. Keep publish and delete disabled for the review loop.

MCP client config

{
  "mcpServers": {
    "excaliwow": {
      "command": "npx",
      "args": ["-y", "@excaliwow/mcp"],
      "env": {
        "EXCALIWOW_TOKEN": "excw_pat_…"
      }
    }
  }
}

Require non-invention and preservation

Name the allowed files, forbid unsupported services and flows, request stable element ids, and state which later human corrections must survive the same-diagram follow-up.

Human review

Change what the agent misunderstood

Correct a misplaced system boundary before polishing the layout.
Clarify one ambiguous responsibility so reviewers do not treat separate concerns as one system.

Same-canvas follow-up

Send the correction back

Update the same diagram in place with the reviewed relationship while preserving the human-positioned regions.

Review the critical path, not the pixels

Every service and edge traces to a named source file or an explicitly standard runtime relationship.
Known relationships are visually separate from uncertain or inferred relationships.
The human correction changes the system model rather than merely polishing layout.
The later agent turn updates the same diagram and preserves named human edits.

Common questions

Should an AI agent read the whole repository?: Usually not for a first architecture question. Start with entry points, service wiring, persistence, and the specific runtime path you need to understand. A smaller evidence set is easier to review and makes unsupported claims visible.
How do I stop the agent from inventing services?: List the allowed files, name the decision the diagram must support, forbid unsupported vendors and flows, and ask the agent to label uncertainty. Then verify every node and edge against source; prompt constraints help, but review remains required.
What should a human change first?: Correct the model before styling it: misplaced trust boundaries, collapsed storage responsibilities, missing queue transitions, incorrect ownership, or a hidden failure path. Those edits make the diagram useful for engineering decisions.
How does the diagram stay current?: Keep stable element ids, preserve the source scope beside the artifact, and ask the agent for targeted updates to the same persistent diagram after code changes. Review the diff in meaning, not just appearance.

Map one real runtime path

Start free—no credit card. First 10,000 verified accounts keep the core workspace free; 3 diagrams to start and earn more capacity.

Start free