Birdview makes the agent show its model before it edits
Birdview asks a coding agent to map modules, responsibilities, file ownership, relationships, local constraints, and source evidence. For a coding task, the same page adds the proposed target files, intended behavior, progress, and verification records. The agent must present that scope and receive explicit confirmation before implementation. Map-only requests stop after the artifact. The output is one standalone HTML page rather than a hosted service.
The approval moment is useful because a bad architecture assumption is cheaper to catch before a 12-file change than after it. Birdview also records gaps: uninspected sources, uncertain relationships, and rules that could not be reviewed. Its contracts reject inconsistent sequences, invalid targets, and malformed ownership records. That gives a reviewer a better-shaped claim, though the reviewer still has to decide whether the claim matches the repository.
What happened when we ran it
Our sandbox installed commit acddbf0 in 15 seconds, adding 22 packages. The installed environment occupied 120 MB, compared with a 2.6 MB checkout containing 197 files and roughly 5,037 lines of source. The TypeScript build passed in 10 seconds. We used an unprivileged Node 22 container with 3 CPUs, 8 GB of RAM, and no secrets.
All 92 tests passed in 28 seconds. Npm audit reported 0 known vulnerabilities at critical, high, moderate, and low severity. The repository had 2 CI workflow files and a test directory, but no Dockerfile. Those results cover installation, compilation, and the Node test command. They do not measure whether an agent produced an accurate map of a real codebase or whether the confirmation step prevented a bad edit.
The map validates structure, not truth
Birdview's architecture.json stores modules and evidence, constraints.reviewed.json stores reviewed rules and coverage, and activity.jsonl stores the agent's declared task events. Validation can catch a file assigned to an unknown module or a check result with an invalid sequence. It cannot prove that a claimed module owns the file, that a cited source still exists, or that the agent touched only the files listed.
Version 0.3.1 is direct about that boundary. Activity is agent-declared, confirmation lives in the conversation, and the HTML page is not a write lock. A completed event does not establish that tests passed; only the recorded check results make that statement inside the artifact. Birdview also lacks live transport and automatic refresh. When the plan changes, the agent must regenerate the file and the reviewer must refresh the browser.
On-demand mode keeps the process from swallowing every edit
New projects default to on-demand use. In Codex, the user selects the skill or mentions $birdview; Claude Code exposes /birdview. Ordinary edits do not trigger a map unless a project opts into auto mode. Auto mode activates before every code-changing task, including small changes and planning that analyzes affected modules. An off mode disables the managed foundation and map workflow until the user explicitly invokes it.
Configuration writes a marked block to AGENTS.md for Codex and DeepSeek Harness, or CLAUDE.md for Claude Code. It preserves surrounding content and refuses malformed or duplicate markers. That is careful, but it depends on the host reading those instructions. A fresh task is part of verification. The doctor command runs one installed worker CLI and renders an example in memory; the documentation says this does not prove agent activation or exercise every command.
Installation is a full skill bundle, not an npm package
The quick path uses the third-party skills installer against Qiuner/birdview, followed by npm ci inside the installed directory and a doctor run. Manual Codex installation places the complete release under ~/.agents/skills/birdview. Scripts, schemas, assets, examples, references, package files, and notices must travel together. Copying only SKILL.md leaves the renderer and validators behind.
Node.js 18 or newer is required. The npm package is marked private, so npm install -g birdview is not the distribution route. Development browser checks require Playwright or a configured BIRDVIEW_PLAYWRIGHT_PATH. Release v0.3.1 says CI covers Windows and Linux on Node 18 and 24. The README and operational guides are paired in English and Chinese, which is unusually helpful for a tool whose workflow is mostly written instruction.
Active maintenance cannot turn declarations into enforcement
GitHub showed 687 stars and 2 open issues on October 3, 2026, with no open pull requests. The repository was pushed on October 2 after a fix for extra bends in architecture-map connectors. Release v0.3.1 shipped on September 22 with symlink-aware CLI startup, stricter doctor checks, reduced-motion work, and reproducible build checks. One open issue concerns a suspicious batch of stars, so the raw star count deserves less weight than the recent merged fixes.
Birdview earns a trial for migrations, cross-cutting features, and unfamiliar repositories where scope errors are costly. The 92 passing tests make the tool itself easier to trust, while its own caveats set the correct ceiling: it organizes an agent's explanation. It does not independently observe the work. Keep Git diffs, tests, and code review as the enforcement layer, and use the map to challenge the plan before those later checks become expensive.