Skip to content

Commit d4f79f8

Browse files
chore(fork): separate feature ledger from upstream readme
1 parent e243dc7 commit d4f79f8

6 files changed

Lines changed: 417 additions & 475 deletions

File tree

‎FORK_FEATURES.md‎

Lines changed: 293 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,293 @@
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+
![Composer skill picker showing user-invocable skills](./assets/fork-features/skills.png)
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+
![Project-scoped and personal skills in the composer picker](./assets/fork-features/skills.png)
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+
![File explorer showing a symlink badge](./assets/fork-features/symlink-explorer.png)
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+
![File explorer showing hidden root entries](./assets/fork-features/hidden-root.png)
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+
![Collapsed lazy file explorer with muted ignored entries](./assets/fork-features/file-explorer.png)
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+
![File explorer with its refresh control](./assets/fork-features/live-refresh.png)
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+
![A tilde path rendered as plain inline code](./assets/fork-features/tilde-path.png)
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+
![Checkpoint revert confirmation explaining that the prompt returns to the composer](./assets/fork-features/checkpoint-revert.png)
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

Comments
 (0)