birdview

Birdview is a skill for AI coding agents. It draws a project's architecture, its constraints and the scope of the current change on one map: the agent shows its understanding and plan, waits for your confirmation, then implements and records the checks it actually ran. The output is a standalone HTML page that opens in a browser, with no service to deploy.

The demo uses the fictional agent harness included in this repository. It does not represent observed production activity.

New in v0.4.0

• Architecture review: see source-backed current drawings, red-pencil findings and proposed redesigns before approving implementation.
• Skill compatibility audit: understand which requests can trigger overlapping skills, with scenario-specific conclusions and evidence in a text report.
• Change paths and outside-scope impact: trace the declared plan and inspect directly connected modules outside its scope.

See the release notes for invocation examples, installation and upgrade notes.

Why Birdview

Ask an AI to "add rate limiting to the login endpoint":

• Normal flow: the AI searches and edits immediately, and you are left to guess from the final diff whether anything was missed or changed by mistake.
• Birdview flow: the AI first shows the login modules, the applicable interface and security rules, the files it plans to touch and the evidence behind each choice. It implements only after you confirm that scope, and records the checks it actually ran.

Logs say which actions the AI took and diffs say which lines changed, but neither answers: where does this change sit in the system, what else can it reach, and why does the AI think these files belong to the task? Birdview lets you catch scope mistakes before the implementation is finished, instead of guessing afterwards.

It does not observe every agent action automatically, and it does not replace Git diffs, tests or code review.

Three Views

Switch with Architecture · Constraints · Review at the top of the page.

Architecture: the modules in the project, what each owns and how they connect, with source evidence for every claim. When activity is supplied, the same map becomes the changes view: it marks the modules and files the agent declared, its current step, and an outside-scope impact layer showing modules directly connected to the plan but not declared.

Constraints: reviewed rules with their conditions, explanations, source text and versions. Browse by topic to understand them or by directory to trace files; Coverage states which sources were reviewed and what remains open. Collected documents are not automatically effective rules, and displaying a rule does not prove the implementation satisfies it.

Review: the architecture review page. Ink draws the facts found in source, a red pencil circles the problems, and a clean redraw marked as a proposal shows the improvement. Evidence is quoted source text. Rendering with --repo checks it line by line against the recorded source revision or working tree; without a repository, quotations are marked unchecked.

The review in this recording is the bundled example, written in Chinese; the interface also supports English.

Every view supports light and dark themes and a Chinese or English interface, and inputs are checked for structure and consistency before rendering.

Quick Start

Install it with the third-party skills CLI:

npx skills add Qiuner/birdview --skill birdview

Start a new agent task and invoke the skill explicitly. By default, Birdview runs only when requested; ordinary edits trigger it only after you enable project auto mode.

Codex: type /skills and select Birdview, or enter:

$birdview Show this project's architecture and constraints; do not edit code.

Claude Code: enter:

/birdview Show this project's architecture and constraints; do not edit code.

For DeepSeek Harness and other hosts, use their skill selector or explicitly ask to use Birdview; slash-command support depends on the host.

When it works, the agent delivers a browser-readable page with the architecture, reviewed constraints, source evidence and review gaps. If constraints cannot be reviewed, it should explain the missing coverage instead of inventing rules. Map-only requests end after delivery; coding requests stop and wait for you to confirm the displayed plan.

See the installation guide for complete setup and verification steps, and the 0.4.0 release notes for this release's features and limitations.

Example Pages

The repository has 2 example pages. Both are offline HTML; open them directly in a browser without running anything:

The constraint view needs a curated constraint catalog first, so there is no ready-to-open example for it yet.

To regenerate the examples from source, use Node.js 18 or newer:

npm ci
npm run validate:examples
npm test
npm run build:demo

Community and Feedback

For installation help, inaccurate architecture maps, or discussion about Architecture-first Coding, join the Birdview user community.