|
| 1 | +# T3 Code fork |
| 2 | + |
| 3 | +This file tracks the behavior this fork adds on top of |
| 4 | +[upstream T3 Code](./README.md). The fork uses the stock |
| 5 | +**T3 Code (Alpha)** desktop identity; the differences below are product |
| 6 | +behavior, not parallel-app branding. |
| 7 | + |
| 8 | +This file is the canonical fork-feature record. Update it when a feature's |
| 9 | +behavior changes, not merely when syncing with upstream. |
| 10 | + |
| 11 | +## Composer `$` skill invocation |
| 12 | + |
| 13 | +The composer `$` picker is a user-invocation surface, the same role as a provider |
| 14 | +slash menu. Codex already treats `$name` as an explicit skill invoke. Claude and |
| 15 | +Grok dispatch skills by sending `/name` in the prompt, so the fork rewrites |
| 16 | +composer `$name` tokens to `/name` on those providers' wire paths. Skills the |
| 17 | +model is not allowed to trigger on its own (Claude/Grok `disable-model-invocation`) |
| 18 | +therefore still run when the user picked them. The stored message keeps the `$` |
| 19 | +token. Claude ultrathink does not wrap a leading `$skill` pick, because that |
| 20 | +prefix would turn the invoke into prose before the rewrite. |
| 21 | + |
| 22 | +Implementation: `packages/shared/src/composerInlineTokens.ts`, |
| 23 | +`packages/shared/src/model.ts`, |
| 24 | +`apps/server/src/provider/Layers/ClaudeAdapter.ts`, and |
| 25 | +`apps/server/src/provider/Layers/GrokAdapter.ts`. |
| 26 | + |
| 27 | + |
| 28 | + |
| 29 | +## Workspace-aware skills |
| 30 | + |
| 31 | +Skill inventories are resolved per project. The server queries the selected |
| 32 | +provider instance with the active project's directory as its working directory |
| 33 | +instead of reusing one server-wide snapshot probed at startup. Projects with |
| 34 | +different repo-local or nested skill sets therefore see their own inventory in |
| 35 | +the `$` and `/` menus. |
| 36 | + |
| 37 | +Implementation: provider skill drivers under |
| 38 | +`apps/server/src/provider/Drivers/` and their provider layers. On mobile the |
| 39 | +cwd-scoped catalog is consumed by the shared composer menu hook |
| 40 | +(`apps/mobile/src/features/threads/use-composer-command-menu.ts` via |
| 41 | +`apps/mobile/src/state/use-provider-context-skills.ts`), which retains the |
| 42 | +last good answer so a probe refresh cannot blank an open picker; both thread |
| 43 | +composers and the new-task draft screen share it. |
| 44 | + |
| 45 | +The project and personal labels in the picker make the cwd-scoped inventory |
| 46 | +visible to the user: |
| 47 | + |
| 48 | + |
| 49 | + |
| 50 | +## Symlink-aware explorer and search |
| 51 | + |
| 52 | +The native workspace scanner (`@ff-labs/fff-node`) does not traverse symlinks. |
| 53 | +The fork supplements it with a cycle-safe, bounded walk that enumerates |
| 54 | +root-level symlinks and follows symlinked directories, including targets outside |
| 55 | +the workspace. Supplemental entries merge into the legacy whole-tree listing |
| 56 | +and path search and obey the project's VCS ignores. The walk is capped at 5,000 |
| 57 | +entries and rebuilt when the workspace index refreshes. Search reports |
| 58 | +truncation when unique supplemental results exceed the requested limit. The |
| 59 | +lazy explorer follows symlinks directly as directories are expanded. |
| 60 | + |
| 61 | +Entries that are themselves symbolic links carry an optional `symlink` flag on |
| 62 | +the `ProjectEntry` contract (omitted for regular entries; `kind` still reflects |
| 63 | +the resolved target). The file explorer renders a small muted ↗ badge on those |
| 64 | +rows — web/desktop through the tree's row-decoration hook, mobile next to the |
| 65 | +row name. Descendants reached through a link are not flagged, and on web a |
| 66 | +symlinked directory absorbed into a flattened single-child segment shows no |
| 67 | +badge. |
| 68 | + |
| 69 | +Implementation: `apps/server/src/workspace/WorkspaceSearchIndex.ts`, |
| 70 | +`packages/contracts/src/project.ts`, |
| 71 | +`apps/web/src/components/files/FileBrowserPanel.tsx`, and |
| 72 | +`apps/mobile/src/features/files/FileTreeBrowser.tsx`. |
| 73 | + |
| 74 | +`CLAUDE.md` is a symlink in this checkout; the explorer marks it with the muted |
| 75 | +arrow badge: |
| 76 | + |
| 77 | + |
| 78 | + |
| 79 | +## Hidden-root visibility |
| 80 | + |
| 81 | +The same supplemental walk exposes root-level dotfiles and dot-directories that |
| 82 | +the native index omits. `.git`, `.DS_Store`, and upstream's `.convex` cache |
| 83 | +exclusion remain hidden, as do paths ignored by the active VCS. |
| 84 | + |
| 85 | +Implementation: `apps/server/src/workspace/WorkspaceSearchIndex.ts`. |
| 86 | + |
| 87 | + |
| 88 | + |
| 89 | +## Lazy per-directory file explorer |
| 90 | + |
| 91 | +Upstream's explorer fetches the whole workspace as one flat listing through |
| 92 | +`projects.listEntries`, silently capped at 25,000 entries (directories count), |
| 93 | +so large repos lose everything past the alphabetical cutoff. The fork loads the |
| 94 | +explorer VS Code-style instead: a new `projects.listDirectory` RPC returns one |
| 95 | +directory's direct children from a plain `readdir` (no search-index dependency, |
| 96 | +no entry cap), and both the web tree and the mobile tree fetch a directory the |
| 97 | +first time it is expanded. The tree opens fully collapsed (the VS Code |
| 98 | +default), so only the root listing is fetched up front. Listings obey the |
| 99 | +same hard exclusions as search: `.git`, `.DS_Store`, and `.convex` stay hidden. |
| 100 | +All other direct children are shown even when the active VCS ignores them; an |
| 101 | +optional `ProjectEntry.ignored` marker lets web and mobile render those rows in |
| 102 | +a muted color without making them less interactive. A failed ignore probe |
| 103 | +leaves rows visible and undecorated. Symlinks resolve to their target kind, and |
| 104 | +broken links are skipped. The legacy whole-tree listing and search remain |
| 105 | +VCS-ignore-aware; their supplemental symlink walk fails open when |
| 106 | +`git check-ignore` rejects pathspecs beyond a symbolic link. This deliberately |
| 107 | +follows VS Code's default split: ignored paths remain visible in the Explorer |
| 108 | +but are omitted from path and content search. The `.git` and `.DS_Store` |
| 109 | +exclusions also match VS Code defaults; `.convex` is a T3-specific cache |
| 110 | +exclusion. |
| 111 | + |
| 112 | +Watcher events and manual refresh refetch every loaded directory and diff the |
| 113 | +results into the tree, so expansion and selection state survive. Because the |
| 114 | +in-tree search only sees loaded rows, a bounded server path search (limit 200) |
| 115 | +merges its matches — with synthesized ancestor directories — into the tree |
| 116 | +while a search query is active. |
| 117 | + |
| 118 | +Upstream's expand/collapse-all control (#8889) is adapted to lazy loading: in |
| 119 | +lazy mode it toggles only the workspace root's direct child directories — one |
| 120 | +bounded listing fetch per directory instead of a cascade through the whole |
| 121 | +workspace — while legacy servers keep upstream's full-tree toggle. Collapsing |
| 122 | +leaves nested expansion state intact, so re-expanding a folder restores the |
| 123 | +subtree the user had open. Upstream's workspace-mutation refresh (#8803) is |
| 124 | +disabled in lazy mode because the filesystem watcher already converges the |
| 125 | +tree after agent edits. |
| 126 | + |
| 127 | +Version skew: the server advertises the `workspaceDirectoryListing` capability; |
| 128 | +clients fall back to the legacy capped `listEntries` flow against servers that |
| 129 | +lack it. `projects.listEntries` itself is unchanged for old clients. |
| 130 | + |
| 131 | +Implementation: `apps/server/src/workspace/WorkspaceEntries.ts`, |
| 132 | +`packages/contracts/src/project.ts`, |
| 133 | +`apps/web/src/components/files/useLazyFileTree.ts`, and |
| 134 | +`apps/mobile/src/features/files/useLazyProjectEntries.ts`. |
| 135 | + |
| 136 | +The initial root listing is collapsed, and ignored entries such as |
| 137 | +`node_modules` remain usable but muted: |
| 138 | + |
| 139 | + |
| 140 | + |
| 141 | +## Live filesystem updates |
| 142 | + |
| 143 | +While a client subscribes to workspace changes, the server watches the active |
| 144 | +workspace and pushes invalidations for changes made outside T3. The watcher is |
| 145 | +shared by subscribers to the same resolved workspace and is released after the |
| 146 | +last subscriber disconnects. Because `@parcel/watcher` does not follow directory |
| 147 | +symlinks, the fork also watches discovered external symlink targets. It does not |
| 148 | +blanket-ignore `node_modules`, because those entries can be visible in the |
| 149 | +explorer when the project's VCS rules allow them. |
| 150 | + |
| 151 | +Because the watcher can miss changes (unwatchable filesystems, failed |
| 152 | +subscriptions), a manual explorer refresh — the web refresh button and mobile |
| 153 | +pull-to-refresh — calls `projects.refreshEntries`, which rescans the workspace |
| 154 | +index from disk and then emits a change event so every subscribed client |
| 155 | +refetches, instead of merely re-reading the possibly stale index. |
| 156 | + |
| 157 | +Implementation: `apps/server/src/workspace/WorkspaceWatcher.ts`, with client |
| 158 | +query invalidation in the web and mobile `state/queries.ts` modules. |
| 159 | + |
| 160 | +The refresh control in the explorer is the manual fallback for the same |
| 161 | +invalidation path. A still image cannot demonstrate watcher-driven updates, |
| 162 | +but it does show the user-visible recovery control: |
| 163 | + |
| 164 | + |
| 165 | + |
| 166 | +## Deterministic web-client cache headers |
| 167 | + |
| 168 | +Upstream serves the bundled web client with no `Cache-Control`, leaving |
| 169 | +Chromium's heuristic cache to decide freshness — after a deploy, clients |
| 170 | +could serve the previous frontend for up to an hour depending on file ages |
| 171 | +(the "hit Cmd+R after relaunch" ritual). The static route now marks |
| 172 | +content-hashed `assets/*` responses `public, max-age=31536000, immutable` |
| 173 | +and everything else (`index.html`, the SPA fallback, root files) |
| 174 | +`no-cache`, so every load revalidates the entry point and a swapped build |
| 175 | +is picked up on the next reload, deterministically. Applies to all |
| 176 | +surfaces the server serves: the desktop renderer (whose `t3code://app` |
| 177 | +protocol proxies these headers through), local browsers, and remote |
| 178 | +clients. |
| 179 | + |
| 180 | +Implementation: `apps/server/src/http.ts` (`staticResponseCacheControl`). |
| 181 | + |
| 182 | +This is HTTP cache behavior and has no distinct client UI state to capture. |
| 183 | + |
| 184 | +## Tilde paths stay plain in chat |
| 185 | + |
| 186 | +Inline-code mentions beginning with `~/` stay plain code rather than being |
| 187 | +expanded against a home directory guessed from the thread workspace. This |
| 188 | +avoids fabricating local links for paths mentioned on remote machines. Absolute |
| 189 | +and relative path chips, explicit Markdown links, and image embeds are |
| 190 | +unchanged. |
| 191 | + |
| 192 | +Implementation: `apps/web/src/markdown-links.ts`. |
| 193 | + |
| 194 | + |
| 195 | + |
| 196 | +## Desktop runs a swappable server payload |
| 197 | + |
| 198 | +When `~/.t3/fork/desktop-server-root` exists on the desktop machine, its first |
| 199 | +non-empty, non-comment line names a directory that replaces the bundled server |
| 200 | +tree in packaged builds. The directory must contain `apps/server/dist/bin.mjs` |
| 201 | +(with `dist/client` inside) and a `node_modules` resolvable from its root — |
| 202 | +the same shape as the app.asar server root. Because the web client is served |
| 203 | +by the backend, one payload swap updates both server and frontend; only |
| 204 | +desktop shell changes (Electron main process, natives, packaging) still need a |
| 205 | +DMG rebuild. The file is read once at launch, `~/` expands to the home |
| 206 | +directory, and a missing or invalid target falls back to the bundled tree, so |
| 207 | +a stale pointer can never brick the app. Development launches ignore the file. |
| 208 | + |
| 209 | +The payload is staged from the same npm tarball the remote hosts install |
| 210 | +(`deploy/stage-server-payload.sh` in the wrapper repository extracts it and |
| 211 | +runs `npm install`), so local and remote deploys share one artifact. Whether |
| 212 | +the override took effect is observable in the backend child process's argv, |
| 213 | +which contains the resolved entry path. |
| 214 | + |
| 215 | +Implementation: `apps/desktop/src/main.ts` and |
| 216 | +`apps/desktop/src/app/DesktopEnvironment.ts`. |
| 217 | + |
| 218 | +This launch-time payload selection has no distinct client UI state to capture. |
| 219 | + |
| 220 | +## SSH launch runs the fork server |
| 221 | + |
| 222 | +When `~/.t3/fork/ssh-t3-package-spec` exists on the desktop machine, its first |
| 223 | +non-empty, non-comment line is used as the npm package spec for the remote T3 |
| 224 | +runner. An explicit override is authoritative even when a global `t3` binary is |
| 225 | +already installed remotely. Remove the file to restore upstream's normal |
| 226 | +channel-derived package selection and global-binary preference. |
| 227 | + |
| 228 | +Deploys are covered by `.agents/skills/DEPLOY_FORK.md` in the wrapper repository. |
| 229 | +`deploy/pack-server-tarball.sh` builds a SHA-versioned package for the remote |
| 230 | +host, and `deploy/swap-fork-app.sh` replaces the stock-named desktop app. |
| 231 | + |
| 232 | +Implementation: `packages/ssh/src/command.ts`, `packages/ssh/src/tunnel.ts`, and |
| 233 | +`apps/desktop/src/main.ts`. |
| 234 | + |
| 235 | +This remote-launch selection has no distinct client UI state to capture. |
| 236 | + |
| 237 | +## Claude session recovery after latched auth errors |
| 238 | + |
| 239 | +The Claude CLI latches into a logged-out state for its whole process lifetime |
| 240 | +when its OAuth refresh fails (typically because a concurrent Claude process |
| 241 | +rotated the shared credentials first): every later turn short-circuits to |
| 242 | +"Not logged in · Please run /login" even after credentials are valid again. |
| 243 | +Upstream keeps that process alive across turns, stranding the one thread while |
| 244 | +new threads work. The fork detects auth-error results, posts a runtime warning |
| 245 | +to the thread, and closes the runtime so the normal teardown path emits |
| 246 | +`session.exited`; the next message respawns the CLI, which reads the current |
| 247 | +credentials and resumes from the persisted cursor. |
| 248 | + |
| 249 | +Implementation: `apps/server/src/provider/Layers/ClaudeAdapter.ts` |
| 250 | +(`isClaudeAuthErrorResult`, `handleResultMessage`). |
| 251 | + |
| 252 | +Recovery is a transient provider-process lifecycle, so there is no stable UI |
| 253 | +state that honestly demonstrates it in a screenshot. |
| 254 | + |
| 255 | +## Checkpoint revert returns the prompt to the composer |
| 256 | + |
| 257 | +Upstream's "Revert to this message" discards the target prompt outright, and a |
| 258 | +client-side retention bug made it linger in the timeline as a ghost: user |
| 259 | +prompts are stored with a null `turnId`, the client reducer kept all |
| 260 | +turn-less messages after `thread.reverted` while the server projector capped |
| 261 | +them at the reverted turn count, so the displayed prompt no longer existed in |
| 262 | +the server read model or the provider's rolled-back context. Worse, the ghost |
| 263 | +was durable: the client persists thread snapshots (IndexedDB on web/desktop) |
| 264 | +and resumes subscriptions with `afterSequence`, so a cached ghost was never |
| 265 | +corrected by a fresh snapshot — it survived app restarts indefinitely. |
| 266 | + |
| 267 | +The fork fixes retention in the shared client reducer: turn-less messages |
| 268 | +(user prompts carry a null `turnId`) are kept only when they predate the last |
| 269 | +retained checkpoint's `completedAt`; anything newer sits past the revert cut. |
| 270 | +A count-based rescue is deliberately avoided because `thread.messages` is a |
| 271 | +paginated window while turn counts are whole-thread. The thread snapshot |
| 272 | +cache schema version is bumped (web v4, mobile v4) so caches written before |
| 273 | +the fix are discarded once and refetched. On the web client, the reverted |
| 274 | +prompt's text is placed back into the composer after a successful revert for |
| 275 | +edit-and-resend — matching the rewind UX of the Codex and Claude desktop |
| 276 | +apps. An unsent composer draft is never overwritten, and the confirm dialog |
| 277 | +states that the prompt will be returned. |
| 278 | + |
| 279 | +Implementation: `packages/client-runtime/src/state/threadReducer.ts` |
| 280 | +(`retainMessagesAfterRevert`), `apps/web/src/components/ChatView.tsx` |
| 281 | +(`onRevertToTurnCount`, `onRevertUserMessage`), |
| 282 | +`apps/web/src/connection/storage.ts`, and |
| 283 | +`apps/mobile/src/connection/environment-cache-store.ts`. |
| 284 | + |
| 285 | + |
| 286 | + |
| 287 | +## Sync status |
| 288 | + |
| 289 | +Last synced on 2026-09-01 against upstream `c78ae50a5` (v0.0.35 → v0.0.38 |
| 290 | +nightlies). The pre-sync fork is preserved at |
| 291 | +`backup/upstream-test-drive-pre-sync-20260901` (`fb5e3edd5`). This sync adapted |
| 292 | +the expand/collapse-all control to the lazy explorer. The previous sync point |
| 293 | +is preserved at `backup/upstream-test-drive-pre-sync-20260826` (`1a1658c21`). |
0 commit comments