THE FIELD GUIDE
Getting started.
01. QUICK START
One command, inside your project.
Open a terminal in the repository you want to understand, then run:
blnkfld reads the source with your signed-in coding agent, checks its references, and opens a visual brief in your browser. Keep the terminal running while you explore.
02. REQUIREMENTS
Bring your coding agent.
- Node.js 22 or later, with npm.
- A current Codex or Claude Code CLI, installed and signed in.
- A local project with source files to analyze.
blnkfld selects Codex first when available, then Claude Code. To choose explicitly, run npx blnkfld --agent claude or npx blnkfld --agent codex.
03. YOUR BRIEF
From source to a working picture.
The brief brings together a project summary, system diagrams, one representative action flow, source references, and instructions for getting the project running.
It is saved in .blnkfld/report.json inside your project. Press Ctrl+C to stop the local preview. Run the command again to generate a fresh brief and open it; the CLI currently re-analyzes the project each time.
References help you check the explanation. The brief is an interpretation of the source, not proof that the project has been executed or tested.
04. PRIVACY & ACCESS
Your agent. Your local report.
Analysis uses your existing agent account and may consume its usage allowance. Source read by the agent is processed by that agent’s configured service; analysis is not offline.
blnkfld saves the report locally and serves its preview on your computer. It does not upload your repository or report to a separate blnkfld service. Review the report before sharing it: it can contain source excerpts and project details.
05. OPTIONS
A few useful variations.
06. TROUBLESHOOTING
When something gets in the way.
A little orientation goes a long way.