Context Gecko

Context Gecko is a VS Code extension for attaching private context notes to selected source code. It acts as a local context layer for understanding large codebases without retracing the same decisions, assumptions, and business meaning from zero.

What It Helps With

• Capture investigation notes near the code that triggered them.
• Explain business meaning, assumptions, edge cases, and operational context.
• Reopen notes from the source code, dashboard, or note mentions.
• Keep notes local-first in markdown files inside the workspace.

Core Features

• Add a Context Note from selected code.
• Show CodeLens markers for code ranges that have notes.
• Browse notes from the Context Notes dashboard.
• Filter dashboard results by All Notes or Current File.
• Search notes by title, source file, and note body.
• Open a dedicated Context Note view with editable title and body.
• Use Read/Edit mode for reading rendered mentions or editing markdown text.
• Explore connected notes through Trace Map.
• Review and recover stale anchors after source changes or refactors.
• Reveal the original source range from a note.
• Open the underlying markdown note file.

Keyboard Shortcut

Select code and press:

Alt+=

On Mac this may feel like Option + + because + is on the = key.

Mentions

In Edit mode, type @ to link files or Context Notes.

File mentions support workspace-relative paths and optional line ranges:

@path/to/file.go
@path/to/file.go:120
@path/to/file.go:120-150

Note mentions use note IDs:

@note:note-id

Read mode renders mentions as clickable links.

Search Exclude Settings

File mention search and the unified mention picker use one editable exclude list. Defaults are stored in codeContextNotebook.search.exclude, so individual defaults like **/dist/** can be removed without disabling the rest:

{
  "codeContextNotebook.search.exclude": [
    "**/.git/**",
    "**/node_modules/**",
    "**/dist/**",
    "**/build/**",
    "**/out/**",
    "**/coverage/**",
    "**/.next/**",
    "**/.cache/**",
    "**/.nx/**",
    "**/target/**",
    "**/generated/**",
    "**/mocks/**"
  ]
}

The internal notes storage folder is always excluded separately and is not part of the editable list.

Use the command palette command:

Code Context Notebook: Configure Search Exclude Folders

Anchor Reliability

Notes store source range metadata and lightweight anchor context. If code moves, the extension tries to relocate the note to the best matching range. If the anchored code changes and cannot be confidently relocated, the note can be marked as possibly outdated.

From Note Detail, choose Review anchor to either accept the current code at validated saved coordinates or select a new anchor in the same workspace root. Context Gecko does not silently save dirty notes or source files during recovery.

Storage Format

Notes are stored locally in the workspace:

.context-notes/index.json
.context-notes/notes/*.md

The markdown files contain frontmatter metadata plus the note body. No cloud sync or external service is required.

Data and Privacy

Context Gecko reads source files and stores note metadata inside the current workspace. It does not require a Context Gecko account, cloud service, telemetry endpoint, or external AI service.

Limitations

Code Context Notebook is not intended to be:

• a team wiki
• a graph database
• an AI documentation generator
• a cloud sync product
• semantic code search
• a full markdown/rich text editor

Build a VSIX

npm run test:regression
npm run vscode:prepublish
npx vsce package

Install the generated .vsix from VS Code with Extensions: Install from VSIX....