Dev Notes

Bring the documentation and knowledge of the code as close to the code as possible. Make any vibe coded app readable and digestible for a better mental model

Comment

Dev Notes — Hackathon Submission

Inspiration

Codebases grow. New teammates join. You open a file and ask: What does this do? How does it connect to the rest of the system? Today you either read line by line, hunt for docs, or interrupt a teammate. There’s no lightweight way to see structure and flow right where you code.

We wanted the editor to turn code into visuals—diagrams that map flows, entities, and APIs—and link those visuals back to the exact lines. Not a separate tool. Not a one-off export. A live, contextual view that stays in your workflow. Devnotes: See the system. Stay in the flow.

What it does

Dev Notes is a VS Code extension that:

  • Analyzes code — Sends the active file (or selection), or tagged files, to a configurable API and gets back annotations and Mermaid diagrams.
  • Shows diagrams in the sidebar — Custom Context and Analysis Results live in a Dev Notes view in the Activity Bar, so you don’t leave the editor.
  • Deep-links diagram to code — The API returns code insights (e.g. “diagram line 7 → code lines 9–11”). Click a link and you jump to that range in the file.
  • Custom context — You can add tagged files/selections and edit .devnotes (Markdown, double-click to edit) so analysis has business context. Custom instructions render as Markdown; diagram appears below.
  • Works with your API — Point devnotes.analysisApiUrl at a localhost API for demos; no API key required for localhost. Or use Devnotes: Analyze with mock response (demo) for an instant demo with a hardcoded sequence diagram and code insights.
  • Holistic .devnotes — Generate one top-level .devnotes that aggregates all folder-level .devnotes and diagram references for the whole workspace.

How we built it

  • VS Code Extension API — TypeScript extension with package.json contributions: commands, configuration, view container (Activity Bar), and two webview views (Custom Context, Analysis Results).
  • Webview views — Custom Context and Analysis Results are WebviewViewProvider views so they live in the sidebar and survive panel moves. HTML/CSS/JS in the webviews use VS Code theme variables and Mermaid.js for diagram rendering.
  • Structured API contract — We support a JSON response shape: { mermaid_diagram, code_insights } where code_insights is an array of { mermaidStartLine, codeStartLine, codeEndLine }. The parser normalizes \n in the diagram and falls back to OpenAI-style chat completion parsing for compatibility.
  • API client — Node https/http for POST JSON. We added isLocalhostUrl() so when the API URL is localhost we skip the API key prompt and don’t send an Authorization header.
  • Tagged context — In-memory list of file/selection entries persisted in globalState; used as analysis input and shown as chips in Custom Context with add/remove/clear.
  • .devnotes — Per-folder .devnotes files read/written by the extension; Custom Context shows them as Markdown (double-click to edit, Save to persist). Holistic command walks the workspace and aggregates into one root .devnotes.

Challenges we ran into

  • Npm task detection — The editor showed “Npm task detection: failed to parse package.json” even though the JSON was valid. We added a .vscode/tasks.json with explicit npm tasks and normalized package.json so users can run compile/test regardless of auto-detect.
  • Webview views vs panels — We first used floating WebviewPanels; moving to sidebar WebviewViewProvider required a different lifecycle (resolve once, postMessage to update), storing the last diagram so Custom Context could show it below instructions, and handling messages (save, openCodeAt) in both providers.
  • Edit vs preview for custom instructions — We wanted Markdown rendering but “open editor only on double-click.” We added a preview div (Markdown via marked.js), hid the textarea by default, and toggled to edit mode on double-click; Save switches back to preview and updates the diagram section when analysis runs.
  • API key for localhost — For a local demo API we didn’t want to require a key. We added isLocalhostUrl() in the API client and skip the API key prompt when the URL host is localhost/127.0.0.1/::1.

Accomplishments that we're proud of

  • One-click diagram → code — Code insights are clickable in both Custom Context and Analysis Results; one click opens the file and reveals the range (with 1-based → 0-based line handling).
  • Single place for code, context, and visuals — Context chips, Markdown custom instructions, and the diagram (with insight links) all live in the Dev Notes sidebar, with no separate app or tab.
  • Flexible backend — Works with OpenAI-style chat APIs, a structured mermaid_diagram + code_insights API, or a hardcoded mock for demos; localhost URLs work without an API key.
  • Cursor/Windsurf-style Custom Context — Context chips, Add current file / Clear all, and a Markdown custom-instructions block with double-click-to-edit and a Diagram section below.
  • Ship-ready UX — Launch config (F5), tasks (compile, test), and a Command Palette command for mock demo so judges and users can try it without configuration.

What we learned

  • WebviewViewProvider has a different lifecycle than WebviewPanel: the view is resolved once, so we use postMessage to push updates (e.g. diagram data, tagged entries) instead of rebuilding HTML every time.
  • VS Code theme variables in webview CSS (--vscode-editor-background, --vscode-button-background, etc.) make the sidebar feel native and respect light/dark theme.
  • Structured API responses (mermaid_diagram + code_insights) are easy to parse and enable deep-linking without scraping diagram DOM; keeping compatibility with OpenAI-style responses gave us flexibility.
  • Localhost detection in the client (and skipping the API key prompt) improved the demo experience and matches how many hackathon backends are run.

What's next for Dev Notes

  • More diagram types — Class diagrams, ER diagrams, and call graphs from the same analysis pipeline, with code insights for each.
  • Persist last diagram — Store the last analysis result in workspace state so the Diagram section survives reloads and is available as soon as you open Dev Notes.
  • Inline code lens — Show “View in diagram” or line-range badges in the editor gutter for lines that appear in the current diagram’s code insights.
  • Real-time analysis — Optional watcher that re-runs analysis (or a lightweight pass) when the active file or tagged context changes, so the diagram stays in sync.
  • Export — Export the current diagram (and optional code snippets) to Markdown, PDF, or a shareable link for docs or onboarding.
  • Multi-file code insights — Support code_insights with a filePath (or workspace-relative path) so one diagram can link to multiple files.
  • Templates — Predefined .devnotes templates (e.g. “REST API”, “Event-driven”) and optional prompts so teams can standardize context and diagram style.

Built With

Share this project:

Updates