Codeography
You code. Codeography tells the story.
Record the shape of a coding session without uploading its source code. Codeography captures editor activity, syncs it to your account, and gives you a session story with claims linked to recorded evidence. You decide which eligible sessions to publish.
Install from the Marketplace · Open your dashboard · Privacy policy
Get started · Capabilities · Privacy · Troubleshooting · Development
Get started
Requires VS Code 1.115.0 or newer. Extension users do not need a separate Node.js installation.
-
Install Codeography by codeographyHQ from the Marketplace, or run:
code --install-extension codeographyHQ.codeography
-
Sign in with GitHub at codeography.dev.
-
In the dashboard, generate an API key and choose Connect to VS Code. Allow VS Code to open the connection link.
-
Open a project folder and work normally. The Codeography status bar shows recording and setup problems.
If the connection link does not open, use the Command Palette (Cmd/Ctrl+Shift+P) and run Codeography: Set API Key. Keys are stored through VS Code SecretStorage, not in workspace settings.
What gets recorded
| Signal | What it means | What it does not establish |
|---|
| File opens and saves | Activity in supported file-backed documents | The contents or purpose of the code |
| Writes outside VS Code's save command | A watched file changed on disk, recorded separately from saves | Which person, agent, or process made the change |
| Diagnostic-count changes | Changes in the editor's reported error count | Which bugs were fixed or why |
| Git commit activity | Supported commit operations observed in the reflog | The commit message or a measure of work quality |
| Session timing and languages | When activity was recorded and the languages associated with it | Continuous attention, intent, or productivity |
Generated files and common build output are filtered. Diff views and other non-file documents do not count as file activity. A VS Code save is deduplicated against the corresponding disk-write event.
From activity to a story
Editor activity → local queue → API ingestion → finalized evidence → cited narrative
- Queued events sync every 5 minutes. The recorder starts a new session when activity resumes after more than 15 minutes of inactivity.
- Each event has a stable identity. Uploads are chunked at 1,000 events and remain queued when a request fails. Backend idempotency prevents known-ID retries from being stored twice.
- The queue is persisted per window and recovered after a crash or offline shutdown. Persistence is debounced, so activity not yet written to disk can still be lost in a sudden crash.
- The backend finalizes quiet sessions after 25 minutes of server-observed silence and generates narratives asynchronously. A sync is not a promise that a story is ready immediately.
- Late events can reopen a session and clear an outdated narrative.
pending, ready, failed, and skipped describe narrative processing, not the quality of your coding session.
Narratives describe stored evidence. They do not establish developer intent, debugging reasoning, or who authored a change. Developer-authored reasoning is not captured by this extension.
Privacy and control
Source code is not part of the event payload. The recorder does not collect code text, keystrokes, clipboard contents, or diagnostic message text.
| Data | Current behavior |
|---|
| File identity | Basenames only, without full paths. Sensitive names such as .env*, keys, and credential files are omitted; activity can still be counted. |
| Project identity | The workspace folder name is not sent. |
| Commits | Messages are not sent. A seven-character SHA is included only when codeography.includeCommitSha is enabled; it defaults to false. |
| Local queue | Metadata is stored in VS Code's extension storage for recovery. Legacy queue files are retained after import and may contain older, less-filtered metadata. |
| Publication | Sessions start private. The owner chooses whether to publish an eligible session from the website. |
| Public evidence | Uses file labels rather than real basenames, and excludes commit SHAs and internal event IDs. |
Old narrative text without evidence citations cannot be published under the current rules. Do not attach queue files, API keys, or private session details to a public issue. See the privacy policy for the service's data practices.
Troubleshooting
| What you see | What to check |
|---|
| Set API key | Connect from the dashboard or run Codeography: Set API Key. |
| Can't read API key | VS Code could not read SecretStorage. Check the system keychain, reload VS Code, and reconnect if needed. Events stay queued. |
| Sync failed | Check whether the key was revoked or expired. Generate a replacement in the dashboard. |
| Sync rejected | The server refused the payload. Update the extension and report the symptom without sharing the queue. Events are retained for retry. |
| No story yet | Check the narrative status in the dashboard. Finalization and generation run asynchronously; a short or unrecognized-language session can be skipped. |
| Offline or a request timed out | Pending events are retried on a later sync or recovered on the next start. Do not delete extension storage as a troubleshooting shortcut. |
| Disk changes appear without saves | These are external-write events. The extension cannot identify the tool or author responsible. |
For a reproducible problem, open an issue with the extension version, VS Code version, operating system, and a description of the status shown. Remove private information from logs and screenshots.
Development
Use Node.js and npm with the checked-in lockfile. Security CI currently uses Node 20; VS Code supplies the runtime when the extension is running.
git clone https://github.com/codeographyHQ/codeography.git
cd codeography
npm ci
npm run compile
Open the repository in VS Code and press F5 to launch an Extension Development Host. The API origin is fixed in src/extension.ts; do not treat a development-host run as isolated from the live service. Use only an explicitly authorized test account and approved API configuration for integration work.
| Check | Command |
|---|
| Typecheck without output | npx tsc --noEmit -p . |
| Lint | npm run lint |
| Compile and unit tests | npm run test:unit |
| VS Code integration tests | npx vscode-test --code-version 1.115.0 |
| Watch compilation | npm run watch |
Integration tests may download a VS Code test runtime. Packaging and publishing are separate release actions, not prerequisites for the unit tests.
Source map
| File | Responsibility |
|---|
| src/core.ts | Recorder, session identities, retries, queue recovery, legacy import, filename filtering, and commit parsing |
| src/extension.ts | VS Code event wiring, SecretStorage, status bar, disk persistence, and network sync |
| Unit tests | Recorder and recovery behavior without a VS Code host |
| Integration test | Extension activation in the test host |
| AGENTS.md | Shared assistant safety and handoff rules |
Release notes
Version 0.1.13 updates this guide. Recording, synchronization, privacy behavior, and VS Code requirements are unchanged from 0.1.12. See CHANGELOG.md for the release history.
License
MIT.
