|
| 1 | +# Atom++ — Agent Guide (CLAUDE.md) |
| 2 | + |
| 3 | +Atom++ is an **AI-native, hackable, Notepad++-powered code editor for macOS**, built as a |
| 4 | +**fork of Code-OSS** (the MIT core behind VS Code). Goal: the user's "last editor" — Atom feel, |
| 5 | +Notepad++ power-editing, native Claude AI, all MIT/license-clean. |
| 6 | + |
| 7 | +Read `PLAN.md` for the vision/roadmap and `docs/CORE-PATCHES.md` for every change made inside |
| 8 | +the upstream source. |
| 9 | + |
| 10 | +## ⚠️ The most important rule: what's tracked vs generated |
| 11 | + |
| 12 | +`vscode/` is a **gitignored, disposable clone** of Code-OSS produced by `scripts/bootstrap.sh`. |
| 13 | +**Never edit anything in `vscode/` directly — it gets overwritten.** Everything that is *ours* |
| 14 | +lives in the tracked repo and is re-applied onto a clean clone: |
| 15 | + |
| 16 | +| Ours (edit here, tracked) | Gets installed into (generated) | By | |
| 17 | +| --- | --- | --- | |
| 18 | +| `extensions/atom-npp-pack/`, `extensions/atom-ai/` | `vscode/extensions/*` | `apply-branding.mjs` (copy) | |
| 19 | +| `branding/product.overlay.json`, `branding/icons/` | `vscode/product.json`, `vscode/resources/...` | `apply-branding.mjs` (merge/copy) | |
| 20 | +| `patches/atom-core.patch` | edits to `vscode/src/**`, `vscode/build/**` | `bootstrap.sh` (`git apply`) | |
| 21 | + |
| 22 | +So: **edit extensions in `extensions/…`, not `vscode/extensions/…`.** After editing, run |
| 23 | +`./scripts/run-dev.sh` (it syncs canonical → checkout first) to test. |
| 24 | + |
| 25 | +A full rebuild from nothing = `bootstrap.sh` → `build-macos.sh`. Nothing is lost if `vscode/` is deleted. |
| 26 | + |
| 27 | +## Repo layout |
| 28 | + |
| 29 | +``` |
| 30 | +PLAN.md vision + phased roadmap (M0/M1/M2…) |
| 31 | +CLAUDE.md this file |
| 32 | +docs/CORE-PATCHES.md log of every edit inside vscode/ (tagged // [Atom++]) |
| 33 | +docs/M0-RUNBOOK.md, EXIT-TEST.md, M1-SPEC.md |
| 34 | +branding/product.overlay.json Atom++ identity + Open VSX gallery (deep-merged onto product.json) |
| 35 | +branding/icons/ app icon source PNG, generated .icns, 1024 png |
| 36 | +extensions/atom-npp-pack/ Notepad++ power-editing pack (plain JS, no build step) |
| 37 | +extensions/atom-ai/ native Claude AI (chat, providers, edit-with-diff, LM provider) |
| 38 | +patches/atom-core.patch our core source edits, applied on bootstrap |
| 39 | +scripts/ bootstrap.sh, apply-branding.mjs, run-dev.sh, build-macos.sh, make-icon.sh |
| 40 | +vscode/ GITIGNORED upstream Code-OSS checkout (generated) |
| 41 | +``` |
| 42 | + |
| 43 | +## Build / run |
| 44 | + |
| 45 | +```bash |
| 46 | +./scripts/bootstrap.sh # fresh: clone Code-OSS @ pinned tag, brand, install extensions, apply patches, npm ci |
| 47 | +./scripts/run-dev.sh # dev: sync + compile + launch (Copilot disabled). Fast iteration. |
| 48 | +./scripts/build-macos.sh # package Atom++.app (arch-aware). Output: VSCode-darwin-<arch>/Atom++.app |
| 49 | +./scripts/make-icon.sh # regenerate .icns from branding/icons/atom-plus-plus-source.png (sips+iconutil) |
| 50 | +``` |
| 51 | + |
| 52 | +## Toolchain (hard requirements — these bit us) |
| 53 | + |
| 54 | +- **Node = `vscode/.nvmrc` (currently 24.15.0)**. Older majors fail to compile native modules. |
| 55 | +- **Python ≥ 3.8** for node-gyp (its bundled gyp uses `:=`; 3.7 crashes). |
| 56 | +- **Native arm64 everything.** If you run under Rosetta (x64 Node on an arm64 Mac), esbuild/tsgo |
| 57 | + crash mid-build ("wrong platform" / "tsgo exited with code unknown"). Fix: native arm64 terminal + |
| 58 | + arm64 Node, then `rm -rf vscode/node_modules && npm ci`. `bootstrap.sh`/`build-macos.sh` now hard-fail on mismatch. |
| 59 | + |
| 60 | +## Core patches (things changed inside vscode/) |
| 61 | + |
| 62 | +Tracked in `patches/atom-core.patch`, tagged with `// [Atom++]`. Find them all: |
| 63 | +`grep -rn "\[Atom++\]" vscode/src vscode/build`. Re-create the patch after editing core: |
| 64 | +`git -C vscode diff -- <files> > patches/atom-core.patch`. Current patches: |
| 65 | + |
| 66 | +1. `src/vs/workbench/contrib/files/browser/files.contribution.ts` — `files.hotExit` default → `onExitAndWindowClose` (Sublime-style persistence; application-scoped so can't be set by an extension). |
| 67 | +2. `build/lib/extensions.ts` (`packageCopilotExtensionStream`) — returns empty: do NOT bundle the proprietary GitHub Copilot Chat extension (not MIT). |
| 68 | +3. `build/lib/copilot.ts` (`prepareBuiltInCopilotRipgrepShim`) — skip instead of throw when Copilot absent. |
| 69 | + |
| 70 | +## Copilot is removed everywhere (keep it that way) |
| 71 | + |
| 72 | +- Not bundled in the packaged app (patches #2/#3). |
| 73 | +- Disabled in dev: `run-dev.sh` launches with `--disable-extension GitHub.copilot-chat`. |
| 74 | +- **DON'T null `product.defaultChatAgent`** — the onboarding code does `assertDefined(product.defaultChatAgent)` |
| 75 | + and the workbench crashes at startup if it's missing. Leave it a valid object; we just don't show/use it. |
| 76 | + |
| 77 | +## Settings shipped as defaults (via extension `configurationDefaults` or core patch) |
| 78 | + |
| 79 | +- `files.hotExit = onExitAndWindowClose` (core patch — application-scoped). |
| 80 | +- `workbench.editorLargeFileConfirmation = 2048`, `chat.commandCenter.enabled = false`, `chat.disableAIFeatures = true` (atom-npp-pack). |
| 81 | +- Extensions can only override **machine-overridable / window / resource / language-overridable** scoped settings — NOT application/machine. (That's why hotExit needed a core patch.) |
| 82 | + |
| 83 | +## Feature status |
| 84 | + |
| 85 | +**M1 — Notepad++ pack (`extensions/atom-npp-pack/`, all done, plain JS):** |
| 86 | +macros (`Cmd+Shift+R`/`Cmd+Alt+P`), Duplicate file (`Cmd+D` / Explorer menu), Sublime hot-exit, |
| 87 | +line operations (sort/dedup/case/…), column incrementing numbers, encoding/EOL status-bar toggle, |
| 88 | +big-file mode badge. Files: extension.js + fileOps/lineOps/columnOps/encodingEol/bigFile.js. |
| 89 | + |
| 90 | +**M2 — native AI (`extensions/atom-ai/`, working):** |
| 91 | +- `providers.js` — streaming Anthropic Messages API + Ollama `/api/chat` (direct, BYO key, no backend). |
| 92 | +- `extension.js` — webview chat panel: streaming, model picker (Claude Opus 4.8 / Sonnet 4.6 / Haiku 4.5 + Ollama), |
| 93 | + `Add selection` context, and **auto-includes the whole open file** as context (chip in input; `atompp.ai.includeActiveFile`). |
| 94 | + Key stored in SecretStorage (`atompp.ai.anthropicKey`). |
| 95 | +- `lmProvider.js` — registers Claude as a native `LanguageModelChatProvider` (vendor `atompp`). Stable API. |
| 96 | +- `aiEdit.js` — **edit-with-diff**: select code → `Cmd+Alt+E` → instruction → side-by-side diff → ✓ Keep / ✗ Discard |
| 97 | + buttons on the diff toolbar (gated on `atompp.ai.diffActive`). |
| 98 | +- `inlineReview.js` — **dead code** (an inline per-hunk Keep/Undo attempt that was reverted; nothing imports it). |
| 99 | + |
| 100 | +## Deferred / known limits (don't waste time re-hitting these) |
| 101 | + |
| 102 | +- **Copilot-grade inline edit review** (floating Keep/Undo button widget + red removed-line phantom rows) is |
| 103 | + **core `chatEditing` UI only** — unreachable from an extension (no overlay widgets, no view-zones). Doing it |
| 104 | + "right" means driving VS Code's native chat-editing: register a chat participant + a complete |
| 105 | + `IDefaultChatAgent` in product.json + patch out Copilot's sign-in/entitlement gating in `chatSetup*`. Big, |
| 106 | + multi-session core effort. We use the diff-tab review instead. |
| 107 | +- Not yet built: inline tab-completion, codebase-wide (multi-file) chat context, Notepad++ keymap preset. |
| 108 | + |
| 109 | +## Conventions |
| 110 | + |
| 111 | +- Extensions are plain JS, no build step (so they ship via `fromLocalNormal`/vsce with no compile). Keep it that way. |
| 112 | +- `// @ts-check` + JSDoc at top of JS files. |
| 113 | +- Test JS logic with `node --check` and small unit snippets before wiring into the editor. |
| 114 | +- After any change, `./scripts/run-dev.sh` to verify; package with `./scripts/build-macos.sh`. |
| 115 | +- Commit `extensions/`, `patches/`, `branding/`, `scripts/`, `docs/`, `PLAN.md`, `CLAUDE.md`. Never commit `vscode/`. |
0 commit comments