Code Context Notes

Add contextual notes to your code with full version history and intelligent tracking. Notes stay with your code even when line numbers change — and AI coding agents can read and write them too, on your terms.

Why

Code comments clutter source files and pollute git history; external docs drift out of sync and lose their connection to the code. Code Context Notes is a third way: contextual annotations that live alongside your code without being part of it.

• ✅ Non-invasive — notes live in a .code-notes/ directory, never in your source
• ✅ Intelligent tracking — notes follow code by content hash when it moves or is refactored
• ✅ Complete history — every edit preserved with author and timestamp
• ✅ Structured — type, tags, priority, scope, and references on every note
• ✅ Workspace sidebar — all notes organized by file, plus agent-activity and proposal views
• ✅ AI-agent ready — a standalone MCP server gives agents access, governed by a trust model
• ✅ Team-friendly — commit .code-notes/ to share, or .gitignore it to keep local

Install

code --install-extension jnahian.code-context-notes

Or search Code Context Notes in the Extensions view. Also on the Open VSX Registry for VS Codium. Requires VS Code 1.80.0+.

Quick start

1. Select code (or place the cursor on a line)
2. Press Ctrl+Alt+N (Cmd+Alt+N on Mac)
3. Type your note and Save (Ctrl+Enter)

A CodeLens appears above your code and the note shows in the Code Notes sidebar. See Getting started.

Documentation

Guides

• Getting started — install and first note
• Usage — add, edit, view, navigate, delete
• Note types & metadata — types, tags, priority, scope, references, expiry
• Agents & MCP — give AI agents access to your notes
• Trust model — audit / queue / direct agent-write modes
• Configuration — all settings
• Commands & shortcuts
• FAQ

Reference

• Architecture — the monorepo and how the pieces fit
• Note schema — the Note type and enums
• Storage format — the on-disk layout of .code-notes/

Packages

• @jnahian/code-notes-mcp — the MCP server

Development

git clone https://github.com/jnahian/code-context-notes
cd code-context-notes
npm install
npm run compile

Press F5 in VS Code to launch an Extension Development Host. The repo is an npm-workspaces monorepo (packages/code-notes-core, packages/extension, packages/code-notes-mcp) plus a web/ site — see Architecture. Tests: 446 across packages (core 168, MCP 76, extension 24 unit + 178 integration). See CONTRIBUTING.md.

Links

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Changelog: docs/changelogs/
• License: MIT