blnkfld
v0.1.9
Published
Generate a source-backed visual project brief with your coding agent.
Maintainers
Readme
blnkfld
An Agentic README for unfamiliar repositories. Run one command inside a project to generate a source-backed brief, an isometric system diagram, and a representative action flow.
Run
The independently deployed blnkfld.co homepage lives in website/. Its dependencies and build are separate from the npm CLI; both interfaces use the logo in shared/brand/.
Run inside the project you want to explore:
npx blnkfldRequires Node.js 22+ and a current, signed-in Codex or Claude Code CLI. blnkfld selects signed-in Codex first, then Claude Code. Use --agent claude or --agent codex to choose explicitly. First-time agent installation and authentication are prerequisites; blnkfld does not install an agent or create credentials for you.
From this checkout, the equivalent command is:
node /absolute/path/to/blnkfld/cli/main.mjs /absolute/path/to/projectThe command analyzes the project, validates the report, saves .blnkfld/report.json, starts a loopback server, and opens your browser. The Three.js interface displays the generated report, with System Overview first and a separate System Architecture diagram. When WebGL is unavailable, an interactive isometric SVG view preserves the components, connections, action playback, and source inspection. Run it again to refresh the analysis. Press Ctrl+C to stop. Use --no-open for a terminal-only environment, --port 4174 to choose a port, or --report-only to save the report and exit.
On startup, blnkfld asks npm for the latest release. If your cached copy is older, it reruns the same command with the latest version, so npx blnkfld always stays current. The check times out after two seconds and falls back to the installed version when offline. Set BLNKFLD_NO_UPDATE=1 to skip it; it is also skipped when CI is set.
What the agent produces
- Project purpose, constraints, stack, and source-backed how-to-run instructions.
- A project-specific haiku beneath the opening summary. Regenerate older reports to include one.
- Meaningful components and actual relationships, chosen separately for each project.
- One representative action through those components, or an explicit explanation when source does not establish a flow.
- Source evidence with file paths and line ranges, plus assumptions and limitations.
The renderer owns geometry, layout, branding, and transitions. The agent owns the explanation. Validation checks schema, component references, file boundaries, and source line ranges; it does not prove that an interpretation is correct or that code has been executed. Source excerpts are read from local files after validation.
Agent access and local output
Analysis uses your existing agent account and consumes its usage allowance. Source read by the agent is processed by that agent's configured service. This is not offline AI. blnkfld does not upload your repository or report to Sites, Vercel, or a separate blnkfld service.
Codex runs in its read-only sandbox with user configuration ignored. Claude Code runs in safe mode with Read, Glob, and Grep tools only. Both receive instructions to avoid secrets, generated files, project execution, and repository-embedded instructions. This is source analysis, not a security sandbox for untrusted repositories. Use projects you trust. The chosen CLI must support the flags used in cli/agent.mjs.
The preview binds to 127.0.0.1, serves only bundled assets and the generated report, and uses a per-session cookie to authorize report access. The server does not expose arbitrary project files. Reports contain source excerpts; decide whether to ignore or version .blnkfld/ according to your project's needs. A failed analysis leaves the previous report intact.
Package testing before publication
npm install
npm run build
node --test tests/*.test.mjs
npm run test:package
npm packFrom a different project folder, run the packed package end to end:
npx --yes --package /absolute/path/to/blnkfld-0.1.0.tgz blnkfldThe tarball contains the CLI and built browser interface. No separate frontend build or server command is needed by the user.
npm run test:package builds and packs the release, installs it with production
dependencies into a temporary directory, and checks the installed executable,
browser assets, and protected report endpoint. It does not invoke an AI agent.
The separate end-to-end command above checks your actual agent installation and
generates a report for the project you run it from.
npm pack uses build:package, which builds only the local browser interface and
includes third-party license notices. npm run build also produces the separate
Sites worker used by the hosted prototype.
The npm interface bundles Inter for body text and Geist Mono for metadata and code, with bundled IBM Plex Mono as the monospace fallback. Headings and the haiku prefer installed Iowan Old Style, then bundled Lora (roman and italic), then Times New Roman, then the browser's serif default. Bundled fonts are served locally without an external font service. Latin glyphs are bundled; other scripts use browser fallbacks.
System Architecture and Trace one action show up to five items per row on desktop and step down through four, three, two, and one column as the screen narrows, preserving selections and playback when the layout changes.
Release automation
Pushes to main run the checks and publish to npm when the package version is
new and higher than previously published stable versions. The workflow creates
the matching GitHub tag and release automatically. An unchanged version skips
publication. This requires npm trusted publishing; see the
release setup and checklist.
License
blnkfld's code is MIT licensed. Bundled fonts remain under the SIL
Open Font License 1.1. Their copyright and license texts are included in
dist/client/THIRD-PARTY-NOTICES.txt. The commercial font assets retained for the
hosted website are not covered by blnkfld's MIT license and are excluded from
the npm package.
Development
npm install
npm run devThe web prototype opens the curated lsi-v0-demo example by default. Its GitHub and local-folder controls use a separate, limited JavaScript/TypeScript source parser; they do not invoke the CLI agent. The CLI's generated report replaces that fixture in its local preview.
npm run build
node --test tests/cli.test.mjs tests/source-analysis.test.mjs tests/sites-worker.test.mjsThe footer opens release notes through the running
app's version. Unreleased changes stay in the repository; internal milestones
live in development history. The original
line-based reader has been retired; legacy ?view=reader links now open the current interface.
