Atoms — Knowledge Automation

Atoms is a VS Code extension (it also runs in Cursor) that distills durable knowledge from your development process — Claude Code sessions, GitHub PRs, and commits — into a reviewed atom store (.knowledge/), then projects it into human docs and AI-context files. Working name.

New here? Start with Getting Started, then the Tutorial. Looking up a setting or command? See the Configuration reference.

🌐 Website / docs site: the landing page and a browsable version of these docs live in website/ — a Next.js + Tailwind app deployed to Vercel. The Markdown in docs/ is the single source of truth; the site renders it. See website/README.md to run or deploy it.

The problem

The meta-layer of a repo — docs/, READMEs, architecture notes, and the .claude/ agent files — is maintained by hand and rots the moment someone forgets to update it. But the durable knowledge already exists in the development process: the pair-programming sessions, the PRs, the commits, the diffs. The thesis of Atoms:

Documentation is a derived artifact. A machine should distill knowledge from the process continuously and project it into whatever form a reader (human or agent) needs. Humans should review, not author.

What it does

• Distills Claude Code sessions, commits, and GitHub PRs into atoms — one durable fact each, with a claim, subjects, and provenance back to the source.
• Reconciles new evidence against the existing store: merge, supersede, relate, or create new — so the same fact never spawns duplicates.
• Projects atoms into docs and .claude/ agent files inside <!-- atoms:begin … --> / <!-- atoms:end --> regions, so generated content and your hand-written prose coexist in the same file without clobbering each other.
• Review-gated: nothing is written silently. Every distillation is a proposal you accept, edit, or reject (you can opt into auto-apply later).
• Auto-triggers: distills on session end, on each new commit, and (optionally) on merged PRs — without you remembering to run a command.
• Zero-config LLM: the default backend shells out to the claude CLI you already use, so there's no API key to configure. Bring your own Anthropic key if you prefer.
• Privacy first: secrets are redacted from all text and diffs before anything reaches the model. On by default.
• Same engine, two surfaces: a VS Code extension and an atoms CLI for CI, git hooks, or a Claude Code Stop hook.

60-second quick start

VS Code / Cursor — install Atoms from the Marketplace (search "Atoms" in the Extensions view, or run the command below):

code --install-extension bebridge.atoms

1. Open a project that has Claude Code sessions (a repo you've worked in with Claude Code).
2. Open the Atoms view from the activity bar (the layers icon) → "Knowledge Atoms".
3. Run Atoms: Review & Distill a Session… from the Command Palette or the view toolbar, pick a session, review the proposed atoms, and click Apply selected.
4. Your atoms land in .knowledge/ and render into the projection docs.

Terminal — the same engine ships as a standalone CLI on npm:

npm install -g @bebridge/atoms   # `atoms` on your PATH
atoms distill                    # interactive: pick the sessions you haven't distilled yet
atoms project                    # render every atom into the projection docs (no-ops when current)

atoms distill is the front door: run it in a repo and it shows the Claude Code sessions you haven't distilled yet, so you can pick one or several — no session ids or file paths to hunt down. With no TTY (CI, a git hook, the Claude Code Stop hook) it falls back to the latest undistilled session. Pass atoms distill latest or a session id to skip the prompt; atoms distill-session <file.jsonl> and friends remain for scripting an explicit source.

See Getting Started for prerequisites, backend setup, and the full first-run walkthrough.

Which surface? Extension vs. CLI

Both surfaces are thin wrappers over the same engine, write the same .knowledge/ store, use the same LLM backends, and run the same redaction — so you can mix them freely on one repo. The difference is whether there's a human in the loop and whether distillation happens on its own:

| | Extension (VS Code / Cursor) | CLI (atoms) | | --- | --- | --- | | Best for | Interactive, day-to-day use with review | CI, git hooks, the Claude Code Stop hook, plain terminals | | Selective review | ✅ review panel — accept/reject each proposed decision before writing | Dry-run only: --plan prints the reconcile plan; applying is all-or-nothing | | Auto-triggers | ✅ distills on session end, new commit, and (optional) merged PR | ❌ — you invoke each run (or wire the Stop hook / a git hook yourself) | | Pending-review queue | ✅ survives dismissed notifications | ❌ | | Browse & mark atoms | ✅ tree view, Mark Verified / Proposed | ❌ (auto-promotion on independent re-derivation still applies) | | distill-commit | only via the commit watcher | ✅ direct command | | Credentials | encrypted VS Code secret storage | --api-key / --token flags or env vars | | Requires | VS Code or Cursor, an open workspace folder | just Node.js — fully headless |

Rule of thumb: use the extension when you want to review proposals and have knowledge distilled ambiently as you work; reach for the CLI to automate distillation headlessly (CI, a git hook, or a Claude Code Stop hook) where you trust the plan or apply wholesale.

How it works (the pipeline)

 SOURCES                         ENGINE (host-agnostic)                    OUTPUTS
 Claude Code sessions  ─┐   ingest → extract → reconcile → project   ┌─ .knowledge/atoms/*.md
 git commits + diffs   ─┼─▶ (LLM)      (LLM)      (LLM)               ├─ .knowledge/projections/
 GitHub PR title/body  ─┘                          ↓                  └─ (optional) .claude/, CLAUDE.md
                                          review (you approve)

• Ingest normalizes a source into a bundle of text + diffs.
• Extract (LLM) turns the bundle into candidate atoms, prioritizing non-derivable knowledge: decisions and rejected alternatives, external-system behavior, and gotchas.
• Reconcile routes each candidate against the store — merge / supersede / related / new.
• Project renders atoms deterministically into the store's projection files (and, on request, into a repo's real .claude/ + CLAUDE.md).
• Narrate (opt-in, separate command) composes LLM-written prose grouped by subject.

The store of record lives under .knowledge/ and is committed to the repo, so distilled knowledge propagates to the whole team regardless of who distilled it.

Documentation

| Guide | What's in it | | --- | --- | | Getting Started | Prerequisites, install/build, choosing an LLM backend, the Atoms view tour, your first distill, the redaction privacy note. | | Tutorial | End-to-end walkthrough: distill → review → verify → re-project → hand-edit preservation, auto-triggers, narrative docs, and a parallel CLI walkthrough. | | Configuration | Reference tables for every setting and every command. | | Design spec | The full design, motivation, and milestones. |

The CLI

The same engine ships as the atoms binary (package.json bin), published to npm:

npm install -g @bebridge/atoms

In a checkout you're developing against, invoke it without installing as node out/cli.js <cmd>:

node out/cli.js list-sessions
node out/cli.js distill-session <session.jsonl>      [--store <dir>] [--force] [--plan] [--backend claude-cli|anthropic] [--model <m>] [--api-key <key>] [--no-redact] [--redact-pattern <regex>]
node out/cli.js distill-commit  <sha>                [--store <dir>] [--force] [--plan] [--backend …] [--model <m>] [--api-key <key>] [--no-redact] [--redact-pattern <regex>]
node out/cli.js distill-pr      <owner/repo#N | URL> [--store <dir>] [--force] [--plan] [--backend …] [--model <m>] [--api-key <key>] [--token <pat>] [--no-redact] [--redact-pattern <regex>]
node out/cli.js project                              [--store <dir>] [--targets store|real] [--overwrite]
node out/cli.js narrative                            [--store <dir>] [--backend …] [--model <m>] [--api-key <key>] [--max-groups N] [--overwrite]

--plan runs a dry-run and prints the reconcile plan without writing. --overwrite (project / narrative) replaces hand-edited regions in their generated files.

The CLI is headless by design: there's no interactive review panel, no auto-trigger watchers, and no pending-review queue — --plan is the CLI's "review," and applying is all-or-nothing. For the in-editor, per-decision review and ambient auto-distillation, use the extension. See Extension vs. CLI for the full comparison.

As a Claude Code hook

hooks/distill-on-stop.sh wires the CLI into a Claude Code Stop hook, so every finished session is distilled into .knowledge/ automatically — detached (it never blocks session end) and fail-safe (a distill error can't break your session). See hooks/README.md for setup.

Develop

npm install
npm run compile        # or: npm run watch

Press F5 ("Run Atoms Extension") to launch an Extension Development Host. The default LLM backend requires the claude CLI on your PATH.

Test harnesses (no LLM required)

Every engine behavior has a deterministic, no-LLM harness under src/scripts/:

node out/scripts/reconcileCheck.js        # reconcile prefilter + adjudication + auto-promote
node out/scripts/projectCheck.js          # projection upsertRegion + renderers
node out/scripts/projectRealCheck.js      # projection into a target repo's .claude/ + CLAUDE.md
node out/scripts/distillCommitCheck.js    # commit ingest → extract → reconcile → project
node out/scripts/sessionWatcherCheck.js   # session-settle debounce
node out/scripts/commitWatcherCheck.js    # commit-watcher sha tracking
node out/scripts/redactCheck.js           # secret redaction patterns + e2e prompt capture
node out/scripts/handEditCheck.js         # hand-edit detection + preserve/overwrite
node out/scripts/pendingCheck.js          # pending-review queue IO + lifecycle
node out/scripts/narrativeCheck.js        # narrative LLM projection (stub LLM)
node out/scripts/prPollWatcherCheck.js    # PR poll watcher baseline + dedup

Layout

atoms/
├── src/
│   ├── extension.ts                # activate(): commands + auto-trigger wiring
│   ├── cli.ts                      # `atoms` binary
│   ├── engine/                     # host-agnostic pipeline (the brain — no vscode imports)
│   │   ├── types.ts                # Atom, SourceBundle, SessionMeta
│   │   ├── adapters/               # claudeCode.ts, git.ts, github.ts
│   │   ├── store.ts                # .knowledge atoms + ledger + pending queue
│   │   ├── llm.ts                  # pluggable LLM client (claude -p / anthropic)
│   │   ├── extract.ts              # extractor prompt + parser
│   │   ├── reconcile.ts            # subject-token prefilter + LLM adjudication
│   │   ├── project.ts              # renderers + projection targets
│   │   ├── narrate.ts              # opt-in LLM narrative projection
│   │   ├── redact.ts               # secret redaction (pre-LLM)
│   │   └── index.ts                # distillBundle / distillSession / distillCommit / distillPr
│   ├── surfaces/                   # thin VS Code wrappers (atomsTree, reviewPanel, watchers, autoTrigger)
│   └── scripts/                    # no-LLM deterministic harnesses
└── package.json

License

MIT © Atoms contributors