SynapTrace documentation

Overview

SynapTrace is a local-first VS Code extension for AI-assisted coding. It traces how your project evolves, helps you understand important changes, surfaces the knowledge required to own the work, and connects those needs to contextual teaching.

AI can make code appear faster than you can build and retain the mental model behind it. SynapTrace is designed to help you keep that model — so you can explain the implementation, predict its behavior, and direct the next change yourself.

Early preview. SynapTrace is under active development. The current release uses a bring-your-own-key model for AI-assisted analysis.

Over time, the gap AI creates looks like this:

• the code works, but you no longer remember why it works;
• important decisions disappear into old AI conversations;
• a change touches more of the system than the diff makes obvious;
• returning to a project means reconstructing context from scratch;
• successful AI-assisted work can look like understanding even when key parts were never actually verified.

SynapTrace turns development history into a structured, navigable ownership layer instead of another chat transcript.

Trajectory

See how your work actually evolved — including interruptions, returns, changes of direction, and the larger arc they belong to.

Development rarely happens in a straight line. You may work on A, switch to B, get pulled into C, and later return to A:

A → B → C → A

A chronological activity log makes that look like four separate moments. SynapTrace treats the return to A as a continuation of the same meaningful work when the evidence supports it, rather than inventing a duplicate task just because other work happened in between.

Trajectory compresses history at multiple levels:

• Recent path — the concrete sequence of work that got you here;
• Current arc — the larger outcome or direction those steps belong to;
• Project trajectory — the major arcs that show how the project changed over time.

The goal is to answer, quickly: Where was I? What changed? Why did I leave this work? What did I finish in between? And what am I returning to now?

Changes

A diff tells you what lines moved. SynapTrace tries to recover the model you actually need to own the change.

For an important change, the Changes view starts with the mechanism itself: why it exists, where it sits in the system, what behavior existed before, and what behavior exists now. It then follows only enough surrounding code to explain how the change participates in the larger flow — the input that reaches it, the decision or state transition it controls, the output it produces, and the upstream or downstream pieces that depend on it.

For example, if an AI changes a form renderer to stop a recursive render loop, SynapTrace should not hand you twenty modified files and call that understanding. It should help you get to a compact model closer to:

configuration arrives
    ↓
renderer chooses field structure
    ↓
state is updated without recursively rebuilding the same tree
    ↓
validated payload is produced

Before: nested rendering could repeatedly recreate the same work
After:  the renderer follows a bounded data-driven path

From there, SynapTrace can point you to the smallest code/evidence path worth reading so you can answer not only “what changed?”, but “why does this implementation now behave differently, and what would I risk breaking if I changed it again?”

Gap Map

The Gap Map shows what you need to understand to own the work you are doing now.

SynapTrace identifies the concepts and capabilities the current task depends on, grounds them in the project, and compares them with the learning and reasoning history it has observed from you.

For example, if you are adding automatic token refresh to an authenticated client, the work may require you to understand:

Token lifecycle
→ when credentials become invalid and what replaces them

Concurrent refresh
→ what happens when several requests fail at once

Retry semantics
→ which requests can safely be replayed

Failure behavior
→ what the client should do when refresh itself fails

The Gap Map then shows which of those capabilities already look supported and which ones need more attention for the current work.

Concurrent refresh
Previously demonstrated in a similar flow.

Retry semantics
Needs more attention for this change.

Failure behavior
Current project evidence conflicts with earlier reasoning.

When a capability needs attention, you can carry it directly into Teaching.

Teaching

Teaching uses the capability selected from the Gap Map and helps you work through it in the context of the project.

You can choose the depth that fits the situation: Practice for a short explanation or reasoning check, Focused for a deeper plan-first walkthrough of the mechanism, or Create to generate a project-grounded learning artifact as a .ipynb notebook that you can run, inspect, and revisit.

For example, a gap around retry semantics could become a quick Practice check, a Focused walkthrough of the request flow and failure cases, or a Create notebook that isolates the retry behavior with executable examples.

Current work
    ↓
Gap Map
    ↓
selected capability
    ↓
Teaching
Practice / Focused / Create (.ipynb)

Teaching stays tied to the capability and project context that caused the gap to surface.

How it works

supported AI CLI activity
        ↓
local capture
        ↓
project/work reconstruction
        ↓
Trajectory + Changes
        ↓
required concepts + developer evidence
        ↓
Gap Map
        ↓
Teaching when attention is useful

SynapTrace combines deterministic local processing with selective AI-assisted analysis. The model is used where semantic interpretation is useful; it is not called for every captured event.

Repeated processing is designed to be incremental and idempotent: unchanged work should not create duplicate project history or unnecessary provider calls.

Existing projects

For the richest and most accurate history, we recommend starting a project with SynapTrace enabled, or adding it as early as possible. That gives SynapTrace direct evidence of how the work, decisions, changes, and learning evolved from the beginning.

But you can also add SynapTrace midway through an existing project.

When SynapTrace joins an existing codebase, it first builds a lightweight local repository baseline from project structure. This gives you useful context immediately without pretending SynapTrace observed work that happened before it was installed.

existing codebase
        ↓
local repository baseline
        ↓
"No observed work yet"
        ↓
new activity is captured
        ↓
normal SynapTrace history begins

The repository baseline describes what exists. It does not fabricate:

• historical work;
• developer intent;
• learner evidence;
• past trajectory.

Getting started

1. Install SynapTrace

1. In VS Code, open the Extensions view.
2. Search for SynapTrace — or open the Marketplace listing.
3. On the SynapTrace listing, choose Install — this is a pre-release, so select the pre-release version if VS Code offers you the choice.
4. Reload the window if VS Code asks you to.

2. Open a project

Open an existing project or a new workspace. SynapTrace will distinguish between:

• a new project with no captured activity;
• an existing project SynapTrace has joined midway;
• a project with existing SynapTrace history.

3. Configure SynapTrace

Open the Settings tab. The main settings are:

• General — running/paused state and project tracking;
• AI Provider — provider, API key, model, and AI-assisted CLI analysis;
• Capture — supported development-activity sources;
• Data & Storage — local project state and database health;
• Diagnostics — extension/runtime status and sanitized diagnostics.

4. Connect your AI provider

SynapTrace currently uses a bring-your-own-key model. The default provider/model for a new configuration is:

Provider: OpenAI
Model:    GPT-5

API keys are entered through VS Code's secure input flow and stored in VS Code SecretStorage. Connecting a key does not automatically enable AI-assisted analysis.

5. Enable AI-assisted CLI analysis

When you are ready, enable AI-assisted CLI analysis. This allows SynapTrace to use the selected provider to analyze captured CLI development activity. Capture and AI-assisted analysis are separate controls.

6. Work normally

Continue using your supported AI CLI workflow in the project. As meaningful activity is captured and processed, SynapTrace begins building your Trajectory, Changes, Gap Map, Teaching context, and other project state.

Local-first & privacy

SynapTrace's project model lives with the project:

<workspace>/.synaptrace/

That local state includes the durable project/learning history SynapTrace uses to reconstruct your work. Today, SynapTrace has no required account and no cloud control plane.

API keys

Provider credentials are stored in VS Code SecretStorage. They are not stored in:

• .synaptrace;
• the project database;
• project configuration;
• the webview DOM;
• diagnostics output.

AI-assisted analysis

AI-assisted CLI analysis is explicit and can remain off. When enabled, SynapTrace sends captured developer prompt text and bounded activity metadata needed for analysis to the AI provider you configured. This can include file paths, edit/line counts, tool-outcome counts, and timing information.

The normal digest path does not send repository source-file contents or diff bodies to the provider. Capture can remain enabled while AI-assisted analysis is disabled.

Design principles

Project memory is not developer memory

What exists in the repository, what SynapTrace observed you doing, and what you have demonstrated understanding of are different kinds of evidence. SynapTrace keeps them separate.

No fake history

Opening an old repository does not cause SynapTrace to invent past Work Units, decisions, trajectory, or intent from the source tree.

No mastery score

Understanding is not reduced to a permanent score. Evidence can be incomplete, contextual, contradicted, or newly applicable as the project changes.

Human authority

Explicit user intent and corrections outrank lower-authority machine inference.

Preserve broadly, surface narrowly

SynapTrace can retain a large amount of project history while showing only the context that matters for the current work.

Current scope

SynapTrace is currently focused on the VS Code developer workflow and captured AI CLI development activity. The first public preview targets Windows x64. Additional platforms will be added after they are tested through the same packaged-extension lifecycle.

The current product includes:

• local project state and automatic database migration;
• project Trajectory;
• important Changes and structural context;
• Gap Map;
• Teaching;
• existing-project repository baselines;
• configurable capture sources;
• bring-your-own-key AI-assisted CLI analysis;
• provider cost observability;
• packaged VS Code installation and upgrade-safe local state.

Broader capture coverage, account/subscription infrastructure, and optional managed AI are not required for the current local product.

SynapTrace is an early public preview and is still under active development. The current release has been validated as an installable VS Code extension across separate machines, including reload, reinstall, and upgrade lifecycle behavior. Expect the product surface and supported integrations to continue evolving.

Support

Questions, problems, or feedback on this preview go to Contact, or directly to contact@synaptraceapp.com.

See also the changelog for what shipped in each release, and the license for the terms that apply to use and distribution.