DevNotes
Notes that stick where they belong.
The problem isn't that developers don't document — it's that there's nowhere good to put it. Markdown files in the repo root accumulate and get ignored. Code comments can't hold screenshots. External apps don't know your codebase.
DevNotes fills that gap: notes linked to specific files and lines, organised by branch, stored alongside your code, and never more than a sidebar click away. And because DevNotes is also an MCP server, AI assistants like Claude Code can read and update your notes directly from the conversation.
DevNotes is open source and welcomes contributions. Found a bug, have a feature idea, or want to improve something? Open an issue or submit a pull request — all contributions are appreciated.
Quick Start
- Open a workspace folder in VS Code.
- Click the DevNotes icon in the activity bar.
- Press
Ctrl+Alt+Q (Cmd+Alt+Q on Mac) to capture your first note — if an editor is focused, the note is automatically linked to that file and line.
- Click the note body in the sidebar to edit it inline, or click Open in editor for the full rich-text editor.
Features
Notes
| Feature |
Description |
| Sidebar card view |
Inline editing with rich markdown preview directly on each card |
| Full rich-text editor |
Tables, images, task lists, code blocks, headings, links, and more |
| Quick capture |
Ctrl+Alt+Q creates a note from anywhere, auto-linked to the current file:line |
| Note management |
Star, archive, duplicate, and bulk-manage notes |
| Templates |
Six built-in templates (Bug Report, ADR, Meeting Notes, Standup, Feature Spec, Code Review) plus custom templates |
Code Linking
Attach a note to a specific file and line in your workspace:
- A gutter icon marks every line that has a linked note
- Hover the line to see the note title in the standard hover widget
- The status bar shows how many notes are linked to the active file
- Jump to file on any card navigates the editor to the linked line
- Code links update automatically when files are renamed inside VS Code
Organisation
- Tags — coloured pills with custom hex colours and Lucide icons. The five defaults (Idea, Todo, Bug, Meeting, Reference) are fully customisable.
tags.json is committed to git so your team shares the same tag set.
- Branch scoping — scope a note to the current git branch; it only surfaces in the sidebar when you're on that branch.
- Reminders — set a due date on any note. An overdue indicator appears in the status bar and a notification fires when the reminder is due.
- Search and filter — filter by tag, branch scope, starred, or archived state.
Rich-Text Editor
The full editor (opened from any sidebar card) supports:
- Headings (H1–H3), bold, italic, underline, strikethrough, inline code
- Bullet lists, ordered lists, task lists (checkboxes)
- Tables — add and remove rows and columns inline
- Code blocks with monospace formatting
- Images — paste or drag-and-drop; stored in
.devnotes/assets/
- Clickable hyperlinks that open in the browser
- Blockquotes and horizontal rules
The sidebar also supports inline editing — click the body of any card to edit in place without opening the full editor.
Team Features
All notes are private by default (gitignored). To share a note, toggle Share this note from its overflow menu — DevNotes adds an exception to .devnotes/.gitignore for that file so it flows through git like any other source file.
| Feature |
Description |
| Shared notes |
Per-note opt-in sharing via .gitignore exceptions |
| Conflict resolution |
Panel with Keep Mine, Keep Theirs, and Merge Both options when a merge conflict is detected |
| Activity feed |
Lists recent changes from all contributors — you, teammates, and Claude Code — with timestamps and attribution |
GitHub Integration
Connect a GitHub account from the sidebar settings panel (uses VS Code's built-in GitHub auth — no personal access token needed):
- Link a PR or issue — paste a GitHub URL to attach it to a note; status (open, merged, closed) is displayed on the card
- Create an issue — convert any note into a GitHub issue directly from the overflow menu
Claude Code / MCP
Register DevNotes as an MCP server so Claude Code can interact with your notes from the conversation:
Command Palette → DevNotes: Connect to Claude Code (Register MCP Server)
Then restart Claude Code. Claude can list notes, read content, create and update notes, search, append, and complete todos — all attributed in the Activity feed.
Export
- HTML — exports all notes as a styled, self-contained HTML file with images embedded
- Markdown — copy any note as Markdown to paste into Slack, Notion, GitHub, or anywhere else
Keyboard Shortcuts
| Shortcut |
Action |
Ctrl+Alt+Q / Cmd+Alt+Q |
Quick capture — create a note linked to the current file:line |
All other actions are available from the sidebar and the Command Palette (DevNotes: prefix).
Storage
Notes are stored in .devnotes/ at the root of your workspace as plain Markdown files with YAML frontmatter. Images and attachments go in .devnotes/assets/. The folder is gitignored by default — only notes you explicitly share are committed.
This means your notes are:
- Portable — readable in any Markdown editor, no lock-in
- Diffable — shared notes show up in
git diff and PR reviews like any source file
- Backed up — lives wherever your repo lives
