# birdview: an architecture map built from what the agent says it will change

> birdview is a skill for AI coding agents that renders the system map, the project constraints and the declared change scope onto one standalone HTML page, then waits for your confirmation before the agent edits anything. The important caveat is in the project's own words: it shows the agent's understanding, not observed reality, and it does not replace diffs, tests or review.

**Qiuner/birdview** — Stop letting AI code blind. Map the architecture before every change with Birdview.

- Repository: https://github.com/Qiuner/birdview
- Website: https://qiuner.github.io/birdview/
- Stars: 687 · Forks: 63
- Language: JavaScript
- License: MIT
- Published: 2026-09-17 · Updated: 2026-09-17 · Language: en
- Canonical page: https://hysenlabs.com/projects/qiuner-birdview

## The map shows what the agent declared, not what it did

The clearest sentence in the project is its own limitation. Birdview does not automatically observe every agent action, and it does not replace Git diffs, tests or code review. What it does is put the agent's understanding of the system and its declared change scope onto one architecture map, so scope mistakes can be caught before the implementation finishes.

That is a narrower claim than the marketing lines suggest, and it is the right one. The page is built from the agent's own statements about what a module owns and which files it will touch, so a wrong belief produces a wrong map that still looks authoritative.

The documentation is consistent about this. The activity history records the agent-declared plan, its progress and its checks. The screenshot in the README uses a fictional agent harness that ships in the repository and does not represent observed production activity, and the bundled demo states that the project and agent activity shown are simulated.

So the correct reading is: a page that makes the agent's model of your system explicit enough to disagree with.

## Seven panels, two of which exist to report what is missing

The page carries seven regions, and five of them describe content while two describe its absence.

The content side is the system map, which gives the modules in the project, what each owns and how they connect. Project constraints holds reviewed rules with their conditions, explanations, source evidence and tracked versions. Current change lists the modules and files the agent says it will touch, plus its current step. Source evidence points at the files or code locations behind each architectural claim. Comparison puts the full architecture and the current change scope on the same layout.

The other two are the interesting ones. Reading coverage records which sources were collected and reviewed and, crucially, what remains uncertain or uninspected. Verification records the checks the agent actually ran and whether they passed.

Two disclaimers apply to the constraint view. Collected documents are not automatically effective rules, and displaying a rule does not prove the implementation satisfies it. Role colours match the architecture palette and explicitly do not represent compliance.

That combination is why this is more than a diagram tool. A map that also tells you how much of the repository was never read is a different artefact from one that pretends to be complete.

## By default it never runs, and once it does it waits for you

The default behaviour is the opposite of what you might expect from a guard tool. Birdview runs only when requested, and ordinary edits do not trigger it unless you enable project auto mode.

Once activated in either mode, the sequence is fixed. Birdview displays the map and proposed changes, then waits for your confirmation before editing code. Confirmed work then continues without repeated prompts within the same scope, and a material change of scope requires confirmation again.

The release history shows this being built deliberately. v0.3.0, published 2026-09-20, is titled for on-demand invocation and plan confirmation, which is exactly this mechanism. v0.3.1 on 2026-09-22 fixed the CLI and tuned the animations, and v0.2.1 on 2026-09-17 was about better guidance for AI coding.

The confirmation gate is therefore a versioned feature rather than an aspiration, and it is opt-in twice over: you invoke it, and then you approve the scope.

## Install goes through a third-party CLI, because the npm package is private

Installation is one command, run through the third-party `skills` CLI rather than npm:

```sh
npx skills add Qiuner/birdview --skill birdview
```

That is consistent with the manifest, which marks the package private while still declaring a binary named `birdview` pointing at `scripts/birdview.mjs`. There is no published npm artifact to install.

Invocation then differs by host, which is the part worth knowing before you install. On Codex you type `/skills` and select Birdview, or enter a command beginning with a dollar sign followed by the skill name and the request to show architecture and constraints without editing code. On Claude Code the same request is prefixed with a slash. For DeepSeek Harness and other hosts you use their own skill selector or ask for Birdview explicitly, and the documentation states plainly that slash-command support depends on the host.

The example request is worth reading as a template: show this project's architecture and constraints, and do not edit code.

## Verification is written as acceptance criteria, not as hope

The quick start tells you how to check that the thing actually worked, which is unusual enough to quote in full.

You check that the agent delivers a browser-readable page containing architecture and reviewed constraints, with source evidence and review gaps. And there is a negative condition: if constraints cannot be reviewed, it should explain the missing coverage instead of inventing rules.

That second half is the whole safety argument compressed into a sentence. An agent asked to produce a constraints view will always be able to produce something. The requirement is that the gap be reported rather than filled.

The two request types also behave differently. A map-only request stops after delivery. A coding request waits for your confirmation of the displayed plan.

Two further documents back this up and are named in the text: an installation guide covering Codex, Claude Code and DeepSeek Harness setup and verification steps, and the release notes for 0.3.1 listing that release's features and limitations.

## Ten scripts, four tsconfigs, and six of seven dev dependencies pinned exactly

The manifest is a build-tooling document rather than an application one, and the numbers are worth reading.

There are ten scripts. Type checking runs two separate TypeScript projects. The build compiles, then runs a viewer build script and a contracts export. The demo build renders a system architecture JSON, an HTML page and an activity JSONL file together, with an explicit simulation flag. Example validation checks an architecture JSON and an activity JSONL. Tests build first and then run, in a unit mode and a separate browser mode, and two scripts act as gates, one for pull requests and one for install verification.

That corresponds to four TypeScript configurations at the root, the default plus specialised ones for tests, types and the viewer.

The seven devDependencies are where the pinning shows: typebox, the Node types, ajv, esbuild, Playwright and TypeScript are all pinned to exact versions, and only the static icon package uses a caret range. An exact pin on Playwright and on the Node type definitions is a deliberate choice about reproducibility in a project that renders HTML and drives a browser.

## Bilingual down to the skill definition, and feedback without private code

The repository root holds 30 entries, and four of the documents exist in pairs. `README.md`, `SKILL.md`, `AGENTS.md` and `CONTRIBUTING.md` each have a Simplified Chinese counterpart, and the rendered page offers Chinese and English controls alongside light and dark themes. The project is maintained in both languages at the level of the skill definition itself, not just the front page.

The remaining structure follows the pipeline. `schemas/` and `references/` hold the data contract and the material, `agents/` and `assets/` hold the skill payload, `scripts/` holds the twelve entry points named in the manifest, `src/` and `test/` hold the code, and `examples/` holds thirteen fixtures. Two entries are unexplained by the README: a `compatibility-audit/` directory and a `build-artifacts.json`.

The examples are worth a note because of their extensions. Architecture and rules are JSON, while activity is JSONL, an append-only event format, and there are separate DeepSeek Harness fixtures alongside the generic ones.

The feedback route asks for the opposite of source code. A GitHub issue template invites successful runs, missing modules, incorrect relationships and installation problems, and states that no private source code is needed, with screenshots and sanitised examples optional. The community itself is a QQ group with a published number.

## Conclusion

Use birdview if your agents regularly make changes that sprawl beyond the task and you want to see the blast radius before the edit rather than in the final diff. Do not treat its output as evidence, since it records what the agent declared, and it explicitly does not observe every action or replace tests. Before enabling project auto mode, check that your host supports slash commands, run the example validation from source, and read the coverage panel first, because the honest reading of a map is bounded by what was actually reviewed.

## FAQ

### What is birdview?

birdview is an MIT-licensed skill for AI coding agents that brings architecture and constraints into one reviewable view. It renders a system map, project constraints, reading coverage, the declared change scope, source evidence and verification results as a standalone interactive HTML page that opens in a browser, and for coding tasks it waits for your confirmation before the agent edits anything.

### How do I install Birdview?

Run `npx skills add Qiuner/birdview --skill birdview` using the third-party `skills` CLI, then start a new agent task and invoke it explicitly. On Codex you select it from `/skills` or enter a dollar-prefixed command, on Claude Code you use the `/birdview` slash command, and on other hosts you use their own skill selector. The package is marked private in its manifest, so there is no npm install path.

### Does Birdview replace code review or tests?

No. It states that it does not automatically observe every agent action and does not replace Git diffs, tests or code review. What it does is place the agent's understanding of the system and its declared change scope on one architecture map, so scope mistakes can be caught before the implementation is finished.

### When does Birdview run automatically?

By default it runs only when requested, and ordinary edits do not trigger it unless you enable project auto mode. Once activated in either mode, it displays the map and proposed changes and waits for your confirmation before editing code, then continues without repeated prompts within the same scope.

## Sources

- [License: MIT](https://github.com/Qiuner/birdview/blob/main/LICENSE)
- [Project website](https://qiuner.github.io/birdview/)
- [Qiuner/birdview on GitHub](https://github.com/Qiuner/birdview)
- [README](https://github.com/Qiuner/birdview/blob/main/README.md)
- [Releases](https://github.com/Qiuner/birdview/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/qiuner-birdview