CodeQuill

Annotate your code with inline notes — without touching the source files.

What it does

Add notes to any line of code. Notes appear as a small ▸ caret after the line. Place your cursor on the line and the note expands inline. Hover for the full note with quick Edit/Remove actions.

Notes are stored in .vscode/notes.json — a plain JSON file that lives in your workspace. This means:

• Notes persist across sessions
• Notes can be shared with your team via version control
• External tools (like Claude Code) can read and write notes directly

Features

• Inline annotations — collapsed ▸ caret expands to ▾ note text when your cursor is on the line
• Gutter icons — blue note marker in the gutter for quick scanning
• Hover card — full note content with Edit and Remove actions
• Sidebar panel — all notes grouped by file in the "CodeQuill" activity bar
• Line tracking — notes follow their code when you insert or delete lines above them
• Anchor recovery — if code shifts between sessions, notes relocate by matching their original text
• File rename support — rename a file and its notes move with it
• External sync — edit notes.json from the terminal or another tool and changes appear instantly

Installation

From source

git clone https://github.com/skonkalmatt/codequill.git
cd codequill
npm install
npm run compile

Then open the folder in VS Code and press F5 to launch the Extension Development Host.

Package as VSIX

npm run package
code --install-extension codequill-0.1.0.vsix

Usage

Adding a note

1. Open any file in your workspace
2. Place your cursor on a line (or select text)
3. Right-click → Add Note
4. Type your note and press Enter

Viewing notes

• Inline: Look for the ▸ caret after annotated lines. Click on the line to expand it.
• Hover: Hover over any annotated line to see the full note.
• Sidebar: Click the CodeQuill icon in the activity bar to browse all notes grouped by file.

Editing a note

• From hover: Hover over the line → click Edit
• From context menu: Right-click on an annotated line → Edit Note
• From sidebar: Right-click a note → Edit Note

Removing a note

• From hover: Hover over the line → click Remove
• From context menu: Right-click on an annotated line → Remove Note
• From sidebar: Right-click a note → Remove Note

Navigating to a note

Click any note in the sidebar to jump directly to its location.

Commands

Storage format

Notes live in .vscode/notes.json:

{
  "version": 1,
  "notes": [
    {
      "id": "a1b2c3d4-...",
      "filePath": "src/server.ts",
      "lineStart": 42,
      "lineEnd": 42,
      "selectedText": "const port = process.env.PORT || 3000;",
      "content": "TODO: Make this configurable via CLI args",
      "createdAt": "2026-03-26T10:30:00.000Z",
      "updatedAt": "2026-03-26T10:30:00.000Z"
    }
  ]
}

Integrating with external tools

Any tool that can read/write JSON can work with Code Notes. The extension watches the file and picks up external changes immediately.

For example, with Claude Code:

Read .vscode/notes.json to see all code annotations in this project.

Configuration

No configuration needed. The extension activates automatically when VS Code starts.

Contributing

1. Fork the repo
2. Create a feature branch
3. Make your changes
4. npm run compile to verify
5. Open a PR

License

MIT