Codeology

Document your life's work, right from your editor.

Put your cursor on any code — a function, a loop, a variable, a single line — and press Ctrl+Alt+D. Codeology captures the complete statement or scope, fills in the signature, parameters, and the libraries the code uses, copies any comment that already explains it, and gives you room to explain — in your own words and in as much detail as you like — how it works. Your explanation is saved as Markdown next to your code in .codeology/, so it lives in Git with everything else.

Every project you document joins your Lifework: a private, searchable brain of how you have built things. Years from now, when you need to remember how you wrote that character controller, press Ctrl+Alt+F and search everything you have ever documented.

Features

• Documentation wizard — the hotkey opens a form beside your code with the signature, parameters, specifiers (UFUNCTION, <suspends>, decorators, attributes), and captured code already filled in. Write How it works in a Markdown editor with live preview, start from an outline, and link other docs by typing [[.
• Smart capture — a selection widens to whole statements, and a cursor on an if, for, while, switch, try, using, with, or Verse loop/race/sync line captures the entire block. Codeology records what the code is — a local variable and its declared type, a constant, a call, a loop, a branch, an import — and the wizard tells you exactly what it captured.
• Comments become docs — documentation comments and docstrings (XML docs, JSDoc, Doxygen, and Google or NumPy style) fill in the summary, How it works, parameters, returns, and edge cases. Select a comment to copy it into How it works and capture the code below it. Everything filled in stays yours to rewrite.
• Uses — every doc lists the libraries and APIs its code depends on: C++ standard headers, Unreal Engine, .NET, Unity, LINQ, npm packages, Python modules and built-ins, and Verse modules. Search for std::sort or FMath::Lerp to find everything you documented that uses it.
• Paste code — run Document Pasted Code (or press Ctrl+Alt+D with no file open, or in an untitled editor) and paste the code. If it is in your workspace, the doc is linked to that file and tracked for changes. If not, it becomes a Plasmid: portable code saved to your Lifework Library, ready to reuse in any project.
• Reuse while typing — code you have documented shows up as ghost text when you start writing something similar: the structure of the line you are typing, or the words of a comment you just wrote, find it. Press Tab to accept. Variable names adapt to your scope — loop variables take the names you typed, and the values the code needs are matched to your parameters, locals, and fields by type; anything without a match becomes a placeholder you Tab through. With a language extension installed (TypeScript, C#, C/C++, Python), Codeology also asks its IntelliSense which variables are in scope and what types they hold, so code adapts to auto and var locals and to fields declared in other files.
• Hovers and insertion — hover a call to a function you documented, or an API like FMath::Lerp, to see your docs for it and the documented code that uses it. Insert from My Lifework puts any documented code at the cursor with names adapted.
• Doc pages — every doc gets a clean page with a project tree, breadcrumbs, the explanation, parameters, edge cases, the code and what it uses, related docs, and an outline of the page.
• Search My Lifework — full-text search across every documented project on your machine, from a quick pick or a full search page with filters by project, kind, and language.
• In-editor indicators — CodeLens and gutter marks show which code is documented. When the code changes after a doc was written, Codeology flags it so you can review the explanation. Hover a documented declaration to read its summary.
• Drift detection with Git — each doc remembers the commit it was written against. When its code changes, the CodeLens, hover, and doc page explain why: Logic changed 3 days ago in commit 8c1f5e2 by Ada: "Triple damage", with every commit that touched those lines since, or a note that the change is not committed yet.
• AI drafts (optional) — off until you turn them on. Run Codeology: Set Up AI Drafts to pick a model running in Ollama on your machine, or Claude with your own Anthropic API key, then choose Draft with AI in the wizard. It suggests a summary, How it works, edge cases, and parameter descriptions, and only the suggestions you tick are used. Everything stays yours to rewrite.
• Organism view — the Codeology Activity Bar view lays your project out as Organs (systems), Files, Cells (modules), Genes (functions and classes), and Codons (statements and blocks).

The living taxonomy

Languages

C++ (including Unreal Engine UCLASS / UFUNCTION / UPROPERTY macros and delegate declarations), Verse, C# (Unity and .NET), TypeScript, JavaScript (including JSX), and Python. Code in other languages can still be captured as Codons and Plasmids, and documented as Cells and Organs.

Commands

Keybindings can be changed in Preferences: Open Keyboard Shortcuts.

Settings

The codeology.ai.* settings are machine settings, so a workspace you open cannot turn AI drafts on or change where code is sent.

Your Codeology account

Signing in is optional. Run Codeology: Sign In to Codeology and confirm the code shown in VS Code on the Codeology website; the status bar then shows your account and plan.

• Backup: Codeology: Back Up This Project uploads the Markdown files in the project's .codeology folder that changed since the last backup, so you can read and search them on the website and in the Codeology app. While you are signed in, projects back up by themselves when their docs change (codeology.backup.onSave). Free accounts back up 3 projects and 10 MB; Premium backs up 100 projects and 100 MB.
• XP and streaks: saved docs count toward your level, streak, and achievements. Only doc ids, kinds, and dates are sent, never titles or code.
• Premium: suggestions while you type and AI drafts are Premium features. New accounts get Premium free for 30 days, and a plan Codeology has confirmed keeps working offline for a week.

Sign-in tokens are kept in VS Code's secret storage and only ever sent to the server in codeology.account.serverUrl (https, or http to this machine). Codeology: Sign Out of Codeology removes them and ends the session.

Where your docs live

<your repository>/.codeology/
├─ project.json                      name, description, visibility (private by default)
├─ index.json                        index of every doc, sorted for clean merges
├─ docs/<source path>/<Symbol>.md    Genes
├─ docs/<source path>/regions/*.md   Codons
├─ docs/<source path>/_cell.md       Cells
└─ systems/<slug>.md                 Organs

~/.codeology/
├─ brain.json                        your Lifework registry: the documented projects on this machine
└─ library/.codeology/snippets/*.md  Plasmids in your Lifework Library

Each doc is readable Markdown with YAML front matter, so it renders on GitHub and diffs cleanly in pull requests.

Privacy

Codeology does not send your code or documentation anywhere unless you sign in to a Codeology account or turn on AI drafts. Everything is written to your repositories and your local Lifework. Drift detection runs your local git against your own repository. Codeology only runs in trusted workspaces because it writes files.

AI drafts are off by default, and nothing is sent until you choose Draft with AI. With Ollama at its default address, drafting runs on your machine. With Claude, the code you draft (for Cells and Organs, the files they cover) is sent to the Anthropic API with your API key. Codeology keeps that key in VS Code's secret storage, or uses ANTHROPIC_API_KEY from the environment VS Code started in.

Security

Codeology treats everything it reads from a repository — docs, file paths, project names, and source — as untrusted.

• Workspace Trust: the extension only runs in trusted workspaces.
• Pages: Codeology pages load only the extension's own bundle, under a Content Security Policy with a per-page nonce. They cannot load remote images, frames, or plugins, and doc Markdown never renders raw HTML. A remote image in a doc shows as a link you can choose to open.
• Requests from pages: every request a page sends is checked for its type and size before VS Code acts on it, and only web and email links can be opened.
• Files: Codeology writes only inside a project's .codeology folder and your ~/.codeology Lifework folder. Paths cannot leave a project through .., symbolic links, or junctions, and oversized files are skipped rather than loaded.
• Hovers, CodeLens, quick picks, and notifications: titles, summaries, and names from docs are shown as plain text, so they cannot become links, commands, images, or icons.
• Git: Codeology runs the Git found on your PATH by its full path, only to read history, with the repository's core.fsmonitor hook turned off, and never asks Git to compare your working tree, so repository config cannot run programs.
• AI drafts: off by default, controlled only by machine settings, and never sent a file that a link inside the project points outside it.

License

MIT. See LICENSE.txt, included with the extension.