Qiuner/birdview: Map the Architecture Before the AI Edits Anything

The black box Birdview is trying to open

The README frames the problem in terms of two artefacts developers already have. Logs record which actions the agent took. Diffs record which lines changed. Neither answers where a change sits in the system, what else it can affect, or why the agent decided these particular files belong to the task. That third question is the one that bites in review: a diff shows you a plausible edit to a plausible file, and nothing about whether the file should have been touched at all.

The intended user is someone running a coding agent against a project with enough structure that module boundaries matter. The README's example is adding rate limiting to a login endpoint. In the normal flow the agent searches and edits immediately, and you inspect the final diff for missed or unrelated changes. In the Birdview flow the agent first states which modules handle login, which files it plans to edit, and which source evidence supports that plan, then implements against that map.

The scope claim is deliberately narrow. Birdview does not observe every agent action automatically, and it does not replace Git diffs, tests or code review. It places the agent's understanding of the system and its declared change scope on one map so scope mistakes surface before the implementation is finished. Treat that as the product definition, not as a disclaimer.

What the generated page actually contains

Output is a single standalone HTML file that opens in a browser with no deployed service behind it. The README lists five things on the page. A system map of modules, what each owns, and how they connect. The current change: modules and files the agent says it will touch, plus its current step. Source evidence: the files or code locations behind each architectural claim. A comparison view that puts the full architecture and the current change scope on the same layout. And verification: the checks the agent actually ran and whether they passed.

The viewer has three modes, Architecture, Changes and Side by Side. Selecting a module shows its responsibility, owned files and source evidence. The activity history shows the plan, progress and checks the agent declared. There are light and dark themes, relationship filters, and Chinese and English controls. A Guide walkthrough runs on first visit and can be dismissed with Escape and reopened from the toolbar.

The repository ships the schemas that back this. The layout includes schemas/, and the examples directory holds architecture.json, bilingual.architecture.json, deepseek-harness.architecture.json, system.architecture.json, plus activity files in JSONL form. The README states that architecture data and activity records are checked for structure and consistency before the page is generated, which matches the validate script in package.json. The screenshot in the README is generated from a fictional agent harness bundled in the repository, and the README says plainly that it does not represent observed production activity.

Installing the Birdview skill and running a first map

Installation goes through the third-party skills CLI rather than npm install. The README gives one command:

npx skills add Qiuner/birdview --skill birdview

After that, start a new agent task with an explicit instruction not to edit code. The README's example prompt is to use Birdview to show the project's architecture without editing anything. What you should see is the agent creating `.birdview/architecture.json` and an HTML architecture map that opens in a browser. If neither appears, the skill did not activate and the installation guide under docs/ covers Codex, Claude Code and DeepSeek Harness setup and verification steps.

Activation mode is controlled by a small configuration block that Birdview writes into the project's agent instruction file. Codex and DeepSeek Harness use `AGENTS.md` by default; adding `--agent claude-code` targets `CLAUDE.md`. The CLI is exposed through `scripts/birdview.mjs` and also registered as a bin entry named `birdview` in package.json:

node <skill-root>/scripts/birdview.mjs mode auto --project <project-root>
node <skill-root>/scripts/birdview.mjs mode on-demand --project <project-root>
node <skill-root>/scripts/birdview.mjs mode --project <project-root>

The third form reads the current mode. Auto is the default: before every code change the agent checks the map and declares the affected modules. On demand, Birdview runs only when you explicitly ask for it. The README notes that these commands only add a configuration block; they do not intercept filesystem writes, and saying "use Birdview this time" does not permanently change the mode. If you want to develop the tool itself or run the bundled demo, the repository requires Node.js 18 or newer and exposes npm ci, validate:examples, test and build:demo in package.json. The demo at examples/harness-activity.html is simulated.

Two activation modes and the cost of the default

Auto mode is the interesting choice and also the one to think about. It asks the agent to consult the map and declare affected modules before every code change. That is a per-task token cost and a per-task interruption, paid whether or not the change is architecturally interesting. Renaming a local variable and rewiring a service boundary cost the same in map overhead.

On-demand mode inverts that. You get the map when you ask for it, and nothing otherwise. The README's own phrasing is that Birdview runs only when you explicitly request it or ask to see the map before editing. For a solo developer on a small repository, on-demand is probably the right default, and the README does not push back on that. For a team where several people are reviewing agent output on a shared codebase, auto mode is the only setting that produces a consistent record, because it does not depend on someone remembering to ask.

The mode commands do not intercept writes. That is a real limitation, not a technicality. If the agent skips the map step, nothing stops the edit. Birdview's guarantee comes from the agent following its instruction file, so the quality of the map is bounded by the quality of the agent's compliance. The README acknowledges the same shape of problem when it says Birdview does not automatically observe every agent action.

Where Birdview is the wrong tool

The clearest failure case is a repository where the architecture is not the risk. In a small service with a handful of files, a diff is already the map, and the extra step buys a page you will not read. The README is honest about the adjacent gap too: Birdview does not replace Git diffs, tests or code review. If your actual problem is that agent output is wrong, you need tests. If your problem is that it is unreviewed, you need review. Birdview addresses a narrower failure, where the change is correct in isolation but lands in the wrong place.

The second case is expecting enforcement. Because the mode commands only write a configuration block into an instruction file, there is no hook that fails a build when the agent edits an undeclared file. Nothing in the README describes a CI gate, a pre-commit check, or a diff-vs-scope comparison. A team that wants a hard boundary between declared scope and actual edits will not get one here, and the README does not claim otherwise.

The third case is a codebase where the architecture lives in something Birdview cannot read. The map is built from what the agent can find in the project and cite as source evidence. If the real boundaries are enforced by an external gateway, a deploy configuration, or an infrastructure repository that is not in the working tree, the map will describe the code and miss the constraint that matters.

How it differs from architecture diagram tools

The obvious comparison is a diagram-as-code tool such as Structurizr or Mermaid-based C4 diagrams. Those approaches ask a human to author the model, then render it. The model is the source of truth and the diagram is a view of it. Birdview inverts the direction: the agent derives the model from the code and from what it can cite, the model is stored as `.birdview/architecture.json`, and the HTML page is a rendering of that derived state at a point in time.

That difference decides which one you want. A hand-authored C4 model stays stable and reviewable but drifts the moment nobody updates it. A derived map cannot drift in the same way because it is regenerated, but it inherits the agent's mistakes and its blind spots, and two runs on the same codebase may not agree. Birdview's source evidence field is the mitigation: each architectural claim points at the files or code locations behind it, so a wrong relationship can be traced and argued with rather than silently trusted.

The second difference is that Birdview carries the change scope alongside the architecture. A C4 diagram tells you what the system is; it does not tell you what the current task intends to modify. Putting both on one layout, which is what the Side by Side view does, is the part that is genuinely specific to the agent workflow. Whether that is worth a per-task step depends on how often your agent edits the wrong module.

Licence, maintenance and what an upgrade costs you

Birdview is MIT licensed, and package.json carries the same identifier. MIT is permissive: you can use, modify and redistribute it, including in commercial work, provided the copyright notice and licence text travel with it. The repository also contains a THIRD_PARTY_NOTICES file, which is where the attribution for bundled dependencies lives. That file is worth reading before you vendor the generated HTML into a product, because the page bundles rendering assets and the notices file is the record of what those are. Nothing here is legal advice; if you are shipping the output inside a commercial product, have someone check the notices.

The release cadence visible in the repository is fast. v0.1.1 landed on 2026-09-13, v0.2.0 on 2026-09-15, and v0.2.1 on 2026-09-17, with the last push to main on the same day as v0.2.1. The v0.2.1 release notes are titled around better guidance for AI coding, and the README points at docs/release-notes-0.2.1.md for that release's features and limitations. Three releases in five days is a project still finding its shape, which is normal at 0.2.x and also means the schema in schemas/ and the shape of `.birdview/architecture.json` should be treated as movable. If you generate architecture files in CI, pin the version you install rather than tracking the default branch.

The upgrade cost is mostly the schema. Because the HTML is validated against the architecture and activity records before rendering, a schema change can invalidate files you generated earlier. Regenerating them means re-running the agent, which costs tokens and produces a map that may differ from the one you reviewed. The README does not document a migration path between architecture file versions, so plan on regeneration rather than transformation.

Editorial conclusion

Adopt Birdview if you already use Codex, Claude Code or DeepSeek Harness on a codebase large enough that a wrong scope costs real review time, and you accept that the map is the agent's own claim rather than a measurement. Skip it if you want automatic capture of every agent action, or if you work in a repository small enough that a diff is self-explanatory. Before trusting it, generate a map for a project you know well and check the source evidence behind two or three relationships: that is the only part of the output you can falsify cheaply.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. Qiuner/birdview on GitHub
4. README
5. Releases