Birdview

Transform your development workflow with Birdview! Shift your focus from code to architecture—and break open the black box of AI coding!

See AI changes before they happen.

Quick Start · How It Works · Live Demo · Project Site · 简体中文

Stop letting AI code blind. Use the Birdview Skill to overturn the default coding flow: map the architecture first, expose the modules an agent plans to touch, then let it edit with evidence in view. Birdview turns architecture descriptions and agent-declared activity into a standalone, interactive HTML view so teams can see what will change before it changes.

Project site: qiuner.github.io/birdview · Topics: agent-tools architecture-as-code code-visualization coding-agents developer-tools software-architecture

Birdview improves coding quality by making the model inspect the architecture before it edits. That forced context check exposes affected modules early, reduces blind changes, and keeps implementation aligned with the system around it.

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

Why Birdview

AI coding logs explain what happened over time, while diffs explain which lines changed. Birdview adds the missing system context: which architectural responsibilities are involved, what evidence supports the map, which modules are in scope, and what was actually verified.

Birdview v0.1 provides:

• Evidence-linked architecture maps with stable module IDs and explicit file ownership.
• Architecture, changes, and side-by-side comparison views on the same layout.
• JSON Schema and semantic validation for maps and activity histories.
• Self-contained HTML output with no server or network dependency.
• Responsive light and dark themes, relationship filtering, and module inspection.
• Chinese and English controls, plus authored content in other languages.

Quick Start

To use Birdview in your agent, follow the installation guide. For the first release's features and limitations, see the 0.1.1 release notes.

To run the demo from a source checkout:

Birdview requires Node.js 18 or newer.

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

Open examples/harness-activity.html in a browser. The demo is a simulation built from examples/system.architecture.json and examples/harness.activity.jsonl.

Viewer Guide

Open Guide in the viewer toolbar for a spotlight walkthrough: architecture, current changes, comparison, module evidence and activity history. Maps without activity show only the architecture and evidence steps. The first-visit invitation is optional; close, skip or press Escape at any time. Exiting restores the original view, record, selection and zoom. Text follows the selected Chinese/English UI language. Dismissal is remembered in browser storage when available; the toolbar always allows replay.

Activation Modes

Birdview defaults to auto: every code-changing task first inspects and reuses/updates the architecture map, renders it and declares affected modules before editing. It also covers explicit affected-module planning. Projects explicitly set to on-demand retain that setting and require a Birdview or map-before-editing request. Say "enable Birdview auto mode for this project" or "switch to on-demand", or run:

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 command manages only its own block in the project's AGENTS.md. "Use Birdview this time" does not persist a setting. This is agent guidance, not a write interceptor. See modes and CLI setup.

Render Your Project

Create an architecture file that follows schemas/architecture.schema.json, then validate and render it:

node scripts/validate.mjs .birdview/architecture.json
node scripts/render.mjs .birdview/architecture.json .birdview/architecture.html

To include a declared activity history:

node scripts/validate.mjs .birdview/architecture.json .birdview/activity.jsonl
node scripts/render.mjs .birdview/architecture.json .birdview/activity.html .birdview/activity.jsonl

Use --bilingual with the validator when both Chinese and English authoring is required. Use --simulation with the renderer only for fictional activity records.

How It Works

project source ──> architecture.json ─┐
                                     ├──> validate ──> render ──> standalone HTML
agent declarations ─> activity.jsonl ┘

The architecture file defines modules, responsibilities, ownership, evidence, relationships, and layout. The optional JSONL stream binds ordered task events to a specific project, map revision, and set of module IDs. The renderer validates both inputs before producing the view.

The recommended workflow has two ordered stages:

1. Inspect the project, establish or update its evidence-backed architecture map, validate it, and review the rendered HTML.
2. For a concrete coding task, declare planned scope, current targets, files, lifecycle phase, and real check results against that same map revision.

Data Contracts

| Input | Purpose | | --- | --- | | architecture.json | Project identity, modules, ownership, evidence, relationships, groups, and stable layout | | activity.jsonl | Ordered, agent-declared task scope, targets, files, phases, and verification records | | architecture.html | Generated standalone viewer containing the validated map and optional activity history |

The schemas enforce structure. scripts/validate.mjs also checks cross-record rules such as stable map identity, contiguous sequences, valid scope and targets, file ownership, and consistent check results. Validation does not prove that architecture claims are true or that referenced source files exist.

Project Layout

| Path | Contents | | --- | --- | | schemas/ | Architecture and activity JSON Schemas | | scripts/ | Validator, standalone renderer, and documentation checks | | assets/ | Shared viewer template, styling, routing, activity, and localization code | | examples/ | Fictional maps, activity records, and the generated interactive demo | | references/ | Authoring workflow, contract, activity, and bilingual guidance | | test/ | Contract, rendering, and optional browser-level checks |

Current Boundaries

Birdview v0.1 is deliberately file-based:

• Activity is declared by an agent; Birdview does not automatically observe coding operations.
• Updates require regenerating the HTML and refreshing the browser.
• Live transport, automatic refresh, and rendered-display acknowledgements are not implemented.
• A completed event does not prove checks passed; only recorded check results make that claim.
• The package is currently marked private and is not published to npm.

Development

npm test                 # Contract and renderer tests
npm run validate:examples
npm run build:demo       # Rebuild the fictional activity demo
node scripts/check-docs.mjs

Browser-level checks live in test/viewer.browser.mjs and require a local Playwright installation or BIRDVIEW_PLAYWRIGHT_PATH pointing to one.

For the field semantics and invariants, read the Birdview contract. Documentation changes must follow the bilingual rules in CONTRIBUTING.md.

License

Released under the MIT License. Copyright (c) 2026 Qiuner. Third-party notices are preserved in THIRD_PARTY_NOTICES.

For release preparation, see the release checklist.