T3 Code is a minimal GUI for coding agents. A Node WebSocket server wraps provider CLIs and agents (Codex, Claude Code, Cursor, Grok, OpenCode, Antigravity, Kiro, Pi, Muse Code, fx) and serves web, desktop, and mobile clients.
You can think of T3 Code as an open source "bring-your-own-subscription" alternative to apps like Claude Desktop, Codex App, Cursor Glass and Conductor.
We have over 500,000 users who love T3 Code. It's important we maintain the things they love as we continue to iterate on the product. Here's a brief list of the things we can never compromise on.
T3 Code is truly open. We share our roadmap, we share how we think about things, and of course we share all our code. A large number of our users run forks. We work in the open, and should strive to stay that way.
Lots of apps have gotten bogged down with bad tech decisions and "slop". We have not, and we're proud of the performance of T3 Code. We regularly audit for performance regressions, often caused by sending too much data over websockets, css animations causing gpu spikes, lists being hard to render, and more. Make sure all changes are considerate of performance impact.
The architecture of T3 Code's websocket layer (t3) enables a lot of awesome remote features. These have become core to the product. Whether users are connecting directly over their local network, using Tailscale, or leaning in fully with T3 Connect (our tunnel solution, also in this repo), we need to make sure new features are properly supported.
T3 Code has 3 key app surfaces: web, desktop, and mobile.
Web is kind of two surfaces, as we have the public facing "app.t3.codes" as well as locally hosting the web app through the t3 command. Both need to be supported by all new features where reasonable.
Desktop is the main surface most users install first. It's a full Electron app that bundles the server runner as well. The desktop app can also be used as the host server, allowing remote connections from app.t3.codes or the mobile app.
Mobile is a React Native app for both iOS and Android, available on the App Store and Google Play. The mobile app allows for connecting to any T3 Code server to control work remotely.
I like ambitious ideas, simple systems, and software that feels obvious. Do not preserve complexity just because it already exists. Do not introduce machinery because it looks architecturally impressive. Understand the real constraint, then fight for the smallest model that makes the correct behavior unsurprising.
Channel both "measure twice, cut once" and "yagni". Fight scope creep. Try to honor the dev's intent in both a minimal and realistic fashion.
The rest of this document is meant to help you navigate the codebase and make changes effectively. Think of these instructions less as "hard rules", more as "good defaults". The developer's preferences should be able to override anything here.
Of note: Most T3 Code contributions will come from T3 Code itself, often controlled remotely. This means you should be careful about accessing data, killing dev servers, and other things that may damage the T3 Code instance that the contributor is using.
If I haven't said what done looks like for a task, state the done condition you're assuming in your first reply, then proceed without waiting for me to confirm it. Report status as distance from that condition.
A status answer, including one given mid-task, ends with what happens next: what you are doing about each open item, and what, if anything, you need from me. If the next step is within what I already asked for, do it rather than offering it. Do not add offers for work beyond the request.
We need to be on the same page with terminology. When communicating, use this language:
- you means the agent reading this file and changing T3 Code.
- we, us, and maintainers mean Theo, Julius and the people building T3 Code. These are who you are talking to now.
- user means the person using T3 Code to direct coding agents.
- agent means the coding agent a user runs inside T3 Code. Depending on context, that may also include you.
- provider means the agent runtime or harness T3 Code talks to, such as Codex, Claude, Cursor, or OpenCode.
- client means the web, desktop, or mobile UI.
- environment means one running T3 server and the machine, filesystem, provider credentials, and state it owns.
- project means an environment-local workspace record rooted at a directory.
- thread means the durable conversation and work history for a project.
- turn means one user-to-agent cycle, including follow-up work such as checkpointing.
- T3 home means the base data directory. Runtime state normally lives below its userdata directory.
- Killing by pattern. Never
pkill -f,pgrep | kill, orkilla PID you found by matching a name, path, or worktree string. Your own agent process has this worktree's path in its argv, and this machine runs several other dev servers at once. Kill only a PID you captured at spawn, or the owner of your port fromss -H -ltnpafter confirming/proc/<pid>/cwdis your worktree. - Writing to the live install.
~/.t3/userdatais the developer's real T3 Code database, in use while you work. Reading it and copying from it are fine, and a good way to get real test data (see Test data). Never start a server against it, never open it read-write, never clean it up. - Baking in origins. Never set
VITE_HTTP_URLorVITE_WS_URLfor dev. Dev is single-origin and Vite proxies/api,/ws,/oauth, and/.well-known. Setting them bakes localhost into the bundle and silently breaks every remote browser.
The most common defect in this repo is a change that works on the path you tested and is missing everywhere else. Before calling frontend work done, walk this list and say which entries applied:
- Entry points. A behavior reachable from the chat view is usually also reachable from Settings, the command palette, and a keybinding. Fixing one is not fixing the feature.
- Clients. Web, desktop (wraps web, adds Electron shell/IPC), and mobile (React Native, separate navigation). Shared logic lives in
packages/client-runtime. This entry is about where the code must change; which client to QA in is under Verifying. - Providers. Codex, Claude, Cursor, Grok, OpenCode, Antigravity, Kiro, Pi, Muse Code, fx, and ACP Registry each have an adapter. Provider-shaped features need a decision per adapter, even if the decision is "not supported here".
- Agents. A capability a user can trigger is usually one an agent should reach through MCP tools, and scheduled tasks run the same paths. That only works when it is a service method, not handler code.
- Contracts. Anything crossing the wire is typed in
packages/contracts. Change the schema and the server, web, mobile, and desktop all follow. - Reverse states. If you added a way in, add the way out and the way to see it. Snooze needs unsnooze. Close needs reopen. A one-way door is a bug.
- Connection modes. Local, remote/relay, and tunnel behave differently. Multi-device and multi-environment cases are real.
- Languages. User-facing text ships in every locale: translate new keys in
apps/{web,mobile}/src/i18n/translationsaftervp run i18n:generate(vp run i18n:checkgates it) and inapps/marketing/src/i18n. - Docs. Check whether the change makes existing guidance inaccurate. Apply the documentation rules before adding anything.
LastCode supports macOS and Linux only. Windows is unsupported and will stay that way, so it must never cost time in checkpoints, package builds, CI, or review. Upstream contributions (upstream-fix) follow upstream's platform support instead.
- LastCode-owned code (
scripts/lastcode-*,scripts/lib/lastcode-*, LastCode features and Actions) assumes POSIX. Do not addwin32branches, PowerShell launchers, Windows path handling, or Windows test cases to it. - Leave upstream's Windows code, tests, and workflows (
windows-tests.yml, the Windows release jobs) in place, because deleting them only creates rebase conflicts. Do not dispatch, fix, or extend them. - When upstream Windows changes conflict during a checkpoint rebase, keep both sides' entries as they are. Do not reconcile how anything behaves on Windows.
- When a Windows-only test, assertion, or type fails a macOS or Linux gate (Quick CI, Full CI, a package build, or
CI Gate), make the smallest change that clears it: a type annotation, an updated expectation, orit.skipwith a one-line reason. Do not investigate or repair Windows runtime behavior. - Dismiss review findings that affect only Windows with the reason "Windows is unsupported in LastCode."
- Worktree setup only links environment files. Inspect the task and actual branch/PR base before preparing dependencies; Git, docs, and thread research do not need an install. When tests, dev, or builds need packages, list Project Actions, launch Prepare Dependencies (
lc-prepare-dependencies) withrun_project_action_and_resume, and end the turn immediately. Resume after its result, then run the intended work. The Action uses the target checkout's cwd and lockfile, including on older branches, and may be repeated after cleanup. Run Quick CI prepares dependencies before CI. For a saved Full CI Action, copy the Run Quick CI command fromt3.jsonand change its final--quickargument to--full. Its Node launcher resolves the primary helper fromprocess.env.T3CODE_PROJECT_ROOT, keeps the target cwd, and runs CI only after preparation succeeds, without shell-specific environment expansion or chaining. Do not assume tests or dev entry points install packages themselves. Preparation does not warm web caches or build outputs. - In a delegated child task, every resumable Action this repository's guidance names, including Prepare Dependencies, Run Quick CI, checkpoint waits, and package builds, goes to your parent as a handoff request; your parent launches it. The exception is a brief stating that your parent verified child Action ownership for this environment; then you launch it yourself and end your turn. Ordinary top-level threads launch their own. See Parent-mediated Actions.
vp run devstarts server and web. In a worktree, state defaults to that worktree's gitignored.t3, which deliberately outranks an ambientT3CODE_HOMEso you cannot land on shared state by accident. An explicit--home-dirstill wins. A plaingit cloneis not a worktree: it shares~/.t3/devwith the main checkout and is not seeded. To isolate one, runvp run migrate-dev-db --base-dir <clone>/.t3, thenvp run dev --home-dir <clone>/.t3.- Ports derive from the worktree path and are stable across restarts, but read the real ones from the
[dev-runner]line since occupied ports shift. - Sharing over the tailnet is three steps: run
vp run dev --sharein the background, wait for thepairingUrl:line in its output, then give that full URL to an unpaired browser. Do not wire uptailscale serveby hand, open the URL yourself, or consume the user's pairing link. A browser with the reusable dev cookie can use the bare origin. If a normal one-time token was consumed, mint a fresh one withnode apps/server/src/bin.ts pair. It carries standard scopes, while the startup URL carries admin scopes needed for Connections settings. - To reuse web dev auth across worktrees, configure one fixed
T3CODE_DEV_AUTH_TOKENin the main checkout's gitignored.env. Thet3.jsonsetup links that file into worktrees. Never commit or publish the token or a startup URL. See Reusable dev credential. - Stop what you started, by the PID you tracked. See rule 1.
vpdoes not pass SIGTERM on, so signalling thevp run devPID alone leaves Vite and the server running. Stop the background task with your harness's own stop, which ends the whole tree. - Run dev servers, Metro, and builds from your own shell so they end with your session. Do not detach them with
systemd-run,nohup,setsid, ortmuxunless the user asks for one that outlives the session. Detached servers ran for weeks and filled RAM and swap. The dev runner stops itself above--memory-limit-gb(half of RAM, at most 16 GiB) on Linux. - Need a second checkout? Get one a thread owns:
delegate_taskwithisolation:"worktree", or a new thread with a worktreeworkspaceStrategywhen the user asks for one. Storage cleanup can remove a worktree a thread owns; one no thread owns stays on disk until someone removes it. Reading another ref needs no checkout:git show <ref>:<path>. If you must run code at another ref yourself,git worktree addit next to this worktree andgit worktree removeit before you report your result.
An empty database is a bad test. Seed your worktree's .t3 with a copy of real data instead of pointing at live state:
- The first
vp run devin a worktree does this for you when its database is missing and the source is at most 500 MiB. Larger sources warn and dev starts with an empty database.--no-seedorT3CODE_DEV_SEED=0skips seeding. Manual migration still accepts larger sources and may use substantial disk space before pruning. - Run
vp run migrate-dev-dbwith your dev server stopped to refresh. It rebuilds<worktree>/.t3/userdata/statev2.sqlitefrom a read-only snapshot of~/.t3/userdata/statev2.sqlite, the developer's real data. It keeps recent projects and their stopped threads, and drops scheduled tasks, pending work, auth sessions, and links to other environments, so your dev server never runs the developer's agents or reaches their other machines. Raise--projectsand--threads-per-projectfor more data. - Refresh
statev2.sqlite, notstate.sqlite. The server copies the V1state.sqliteonly whenstatev2.sqliteis missing. - Bring
secretsandsettings.jsononly if the flow under test needs them. - Copy in, never symlink. Data flows one way: into your sandbox, never back out.
-
Before you push, run
vp run check:changed origin/lastcode/main. It runs CI's fast checks for changed files: format, lint, knip, typecheck of affected packages and dependents, tests beside changes, and the cross-file checks those miss. Without the ref it compares againstorigin/main, the upstream mirror, and checks the whole fork's diff. CI still runs the full test suites. -
Smallest proof that the change works.
vp test run <files>for the tests you touched, targeted lint and typecheck for the scope you changed. -
Run compiled web React checks with
pnpm --dir apps/web exec vp test run --project unit src/...; the root Vite config omits the web React compiler. Mounted tests can still pass through compiler fallback. For a new or refactored hook/component, also runpnpm --dir apps/web exec vp test run --project unit src/reactCompilerCoverage.test.ts -t 'compiles apps/web/src/path/to/file.tsx'to verify compilation without bailouts. -
Use
vp run typecheck; it caches per package. Each package runseffect-tsgo tsrs --noEmit, the Rust TypeScript 7 checker with Effect's diagnostics built in. There is notypescriptpackage to run. -
Run
node -esnippets fromapps/serveror the owning package.effectdoes not resolve from the repo root. -
Test behavior that can break, such as orchestration and event-sourcing, provider protocol translation, auth and permission guards, persistence and migrations, external-format parsing, race fixes, and the logic a bug fix changed. Leave out tests for what types already guarantee, trivial logic, copy text, smoke runs, mock-call mirrors, callback wiring, and props rendered to static markup.
-
Extend before you add. When an existing test or table covers the behavior, add a row or an assertion there. Write a new
itonly when no case fits. -
In LastCode work, read Where LastCode changes go before you place new behavior or its tests. Outside ports of upstream changes, new behavior goes in a fork-owned module with only small seams in upstream-owned files that hand off to it, and tests for a fork-owned module go in a fork-owned test file, not an upstream one.
docs/internals/testing.mdleaves this LastCode rule out. -
Test at one layer: the lowest one that fails on
main. Do not repeat the case in a wrapper test, at each call site, or in web and mobile copies of the same logic. -
Write a browser test only for behavior that needs a real browser: layout and scrolling, focus and pointer input, real workers, or a component wired to its hooks. Logic a component calls gets a unit test beside it (
*.logic.test.ts). A browser test file spends seconds in CI loading its module graph before its first test runs; a unit test takes milliseconds. -
Testing carries these same test rules, plus review guidance, for review bots. Change both together.
-
Do not run repo-wide checks. No
vp check, novp run -r test, novp run -r typecheckunless I ask. CI owns the full suite. -
Backend behavior changes ship with focused tests for that behavior.
-
Proof for a bug fix depends on the bug. Logic, data, state, and protocol bugs get a failing test first (the fewest that fail on
mainfor that reason, in an existing case of the module's test file where one fits), then the fix. Purely visual bugs (spacing, colour, alignment, a layout shift) get before/after captures as their proof and no test: do not add UI tests for nitpicks, and do not ask for one in review when a capture already shows it. A server-only fix with no visible surface ships the test plus a short runtime transcript. For a bug a user can reproduce in the web client,vp run scenarios:proveshows it failing on base and passing on the fix in the real app; see Scenarios. -
The server is event-sourced, and side effects run after the command commits. In tests, drain the effect worker (
OrchestrationEffectWorkerV2.drain) or await the specific persisted event orDeferredthat marks the milestone. Never wait on sleeps or polling. A test that needs a timeout to pass is wrong. Concretely:it.effectruns on aTestClock;Effect.sleeponly advances throughTestClock.adjust.it.liveis wall-clock and only for subprocess or network fixtures.- No
yieldNoworsleeppolling loops. Await theDeferred, take from theQueue, or drain the worker. - No per-test timeout argument or
retry. The project timeout is the ceiling, and flaky tests are fixed, not retried. - No
performance.now()orDate.now()deltas. Assert on events and counts, not elapsed time. - Browser tests assert through
expect.elementorvi.waitFor, neverrequestAnimationFrameortransitionend. vi.mockfactories must not spread a real module that pulls in Shiki or the diff workers.it.skipand friends need a tracking issue on the line above:// quarantine: #1234 <why>.- Lint enforces this:
t3code/no-test-timeout-or-unreasoned-skip,t3code/no-frame-waits-in-browser-tests,t3code/no-wall-clock-in-tests,t3code/no-real-time-wait-in-tests,t3code/no-polling-loop-in-tests.
-
Web browser tests are
*.browser.test.tsxor*.browser.test.tsand render withawait using screen = await render(...)fromapps/web/test/render.tsx.t3code/require-disposable-rendererrors on the old patterns.- Acquire what the test drives after mounting (fake timers it advances, spies it sets up after mounting) after the render, so it disposes before the unmount. Anything the first render reads comes before it.
- A helper that renders and then waits or clicks puts the screen in an
AsyncDisposableStackandmove()s it out only on success, so a failed wait still unmounts. rerenderneeds a fresh element on every call.- No lifecycle hooks and no module-level mutable state. Shared mock state that
vi.mockfactories read is reset by asetup()call at the top of the test. routeris on by default. Passrouter: falseonly with a one-line comment saying why.
it("saves on Enter", async () => { const onSave = vi.fn(); using _now = vi.spyOn(Date, "now").mockReturnValue(0); await using screen = await render(<TitleEditor onSave={onSave} />, { router: "/threads/1" }); await userEvent.type(screen.getByRole("textbox"), "Title{Enter}"); expect(onSave).toHaveBeenCalledWith("Title"); });
-
User-visible frontend changes should get one integrated pass in a real client: a web client or desktop QA instance through
test-t3-app, mobile changes included. Usetest-t3-mobileonly when the user explicitly asks for native mobile verification; that skill owns simulator setup and shutdown. QA you set up for the user to try also goes in a web client or desktop QA instance. The primary agent does this once after integrating. During checkpoint recovery, prepare dependencies and run the focused recovery gate in one separate gate/QA checkout, start the service's Full CI, then run this integrated pass from that checkout alongside it; follow Resuming a repaired checkpoint. QA is still required, but does not delay Full CI. Subagents do not launch their own dev servers. Routine automated QA in an isolated development instance is authorized: use a thread-owned background preview withpreview_open({ open: false, reuseExistingTab: false })and keep the returned tab ID. Do not focus an application, switch the user's thread, or operate their live workspace. Ask before foreground computer use or back-and-forth human QA, according to the machine interaction policy. -
Real agent turns cost money. To watch a turn stream through the pipeline and UI, use the free
Replay (dev)provider thatvp run devregisters; test-t3-app shows how to start one. Use a real provider only when the change depends on that provider's behavior, and then pick its cheapest model, such as Haiku for Claude or Luna for Codex.
Before dev-browser QA, identify the actual browser host as well as the app host.
When they differ, use the runner's --share recipe and published HTTPS origin;
an unshared loopback URL and a backend --host override do not make the web
listener reachable by the remote desktop. Navigate directly to the runner's
published HTTPS URL. Follow test-t3-app for the one descriptor-readiness
check and record any manual pairing separately from automatic authentication.
When the user has asked for native mobile verification, a missing or outdated native client is an install step, not a blocker. Run vp run mobile:install <ios|android> [device-id] on the device host before starting Metro; it targets the only booted simulator or connected Android device when the id is omitted. It installs the dev client for this checkout's native fingerprint from the shared cache in seconds and builds only when no machine has built it yet, so prefer it over expo run:*, xcodebuild, or gradlew, which rebuild from scratch. Its stdout is one JSON line; build output goes to the log it names. See test-t3-mobile for the full workflow.
For an already-started LastCode checkpoint service run, use the resumable
Wait for Checkpoint action instead of agent-side sleep/status loops. Follow
the action handoff and result rules in docs/lastcode/release.md; this action
does not start or repair the service.
For an authorized local Apple Silicon package build, select the exact installable
tag and use the resumable Build Local Package action (lc-build-local-package)
as described in docs/lastcode/release.md. End the turn after launch; do not run
the build helper directly or poll build logs. The action builds only; installation
and restart remain separate decisions. If another Action continuation is pending,
end the turn so its result can arrive, then list Actions again. An automated
message alone does not make Actions unavailable; use the actual disabled reason.
evals/ checks how real models behave with T3 Code's model-facing text: agent instructions, MCP tool descriptions and schemas, and generated titles. Before you change that text, read evals/README.md and run the evals it names. When you fix a model behavior bug, add a case that fails before the fix.
Thread-read routing has one contract: the t3_thread_read tool description and via schema, plus the recovery text in apps/server/src/mcp/ThreadReadDiagnostics.ts. The attached-thread sentence in packages/shared/src/composerContextReferences.ts and "Find mentioned threads" in packages/provider-core/src/server/orchestrationInstructions.ts restate it, so change them together.
When given a budget for local reviews (e.g., example: "up to 5 rounds of Astra High review" or "review (up to 3 rounds)", run the reviews & address issues until a review comes back clean, or the budget is exhausted. Always finish addressing issues from the last review! Then proceed (if instructed) with babysitting the pr (addressing ci failures and github review comments). If instructed to merge, do so when ci/github-reviews are clean, even if the last round of local review was not clean. If instructed to "merge if clean", proceed through babysit pr but don't merge if the last local review was not clean, and notify the user.
- Never make a PR unless the developer explicitly asks you to do so.
originis not always GitHub. Checkgit remote get-url originbefore your first forge command and use that forge's CLI and skill. See Forge mirror.- If
originis git.cafe, follow GitCafe mirror: push toorigin, open and track PRs withcafeand their git.cafe URLs, and keepghfor merging. - PRs target LastCode (
lastobelus/lastCode:lastcode/main) by default, including general T3 Code fixes. Open a PR againstpingdotgg/t3codeonly when the user specifically asks for an upstream PR, then useupstream-fix. Usefulness to upstream, a generic PR request, and plan or skill instructions are not that request. Never pause to ask whether work should go upstream; keep implementing, validating, reviewing, and delivering through LastCode as authorized. - For LastCode PRs targeting
lastcode/main, including authorized checkpoint or build repair PRs, follow.agents/skills/lastcode-pr/SKILL.md. When CI or review is passive and no current finding needs judgement, callwatch_pull_requestwith the PR URL, then runpnpm --config.verify-deps-before-run=false lastcode:pr-gatesonce; if it reportspending, end the turn immediately. The gate check andpnpm --config.verify-deps-before-run=false lastcode:mergeneed only Node,gitandgh, so they run in a worktree withoutnode_modules; the flag stops pnpm installing dependencies first. A new watch wakes only for comments posted after it starts, so the check must come after the watch call. On each wake, rerun the check and act on what changed; do not poll GitHub or run a separate watcher. This applies without a separate “babysit” request and does not authorize creating or merging a PR. T3 Code wakes you on checks, comments, or conflicts. Verify each bot finding against the source, fix real ones, dismiss false positives with a written reason, and stay quiet when nothing is new. The savedWait for PRProject Action is retired (#419); wait withwatch_pull_requestonly. - An app-owned delegated child owns a PR watch only when its brief says the parent verified
features.appOwnedPullRequestWatchContinuationVersionand #482 Phase 4 acceptance of its destination's installed checkpoint, or authorized an isolated acceptance scenario. Otherwise the parent owns the watch, and mediated requests keep their recorded owner. An owning child watches, runs one gate check, ends its turn unfinished while waiting, and unwatches before handback. Owning the watch adds no merge authority, and nobody polls or relays its events. - Conventional commit titles, plain language:
fix(web): new threads no longer spike CPU. - Body: the problem in a sentence or two, then how you fixed it. End with the model and harness that did the work.
- Use
https://redirect.github.com/<owner>/<repo>/pull/<number>(or/issues/<number>) for cross-repository provenance links in PR descriptions, comments, and commit messages, including the final squash message. Ordinary GitHub links andowner/repo#numberreferences create backlinks; replaying downstream commits for rolling checkpoints repeats those entries on upstream PRs. Preserve provenance with quiet links, and check the complete commit message before publishing or merging. Keep canonical repository/API URLs for Git operations and tooling. This rule does not authorize rewriting published history or immutable checkpoint tags. - UI changes need before/after images. Motion or timing needs a short video.
- Upload PR evidence to GitHub. Never commit PR-only screenshots or assets such as
.github/pr-assets/. - One request is one PR. Split it only when the maintainer asks. Outside contributions follow the stricter one problem per PR rule.
Finding out why a failure happened, yours or another thread's, is the moment to ask whether the next thread will hit it too. If the cause was guidance that is wrong, stale, missing, or easy to misread, or a tool or error message that pointed the wrong way, repairing your own run leaves the trap in place. In the same reply as the diagnosis, say what would remove it and where that change belongs. Make the change when it falls inside your task; otherwise leave the recommendation with the developer.
Most code changes do not need an internal documentation change. Agents can read the code.
docs/internals/is for architectural decisions and their reasons, constraints that span components, and implementation traps that are hard to discover from the source. Before adding a paragraph, ask what a maintainer would get wrong without it. If reading the relevant code answers the question, leave it out.- Do not document every feature, enumerate fields or methods, narrate control flow, maintain file catalogs, or append PR summaries. Types, tests, and code already record the implementation. The glossary defines shared vocabulary; it is not a feature index.
- A local reason the code can't show goes in a short nearby code comment. Use an internal doc when the reasoning crosses boundaries or needs context the code cannot carry well. Link to the relevant source instead of copying it.
- When a documented decision or constraint changes, rewrite or remove the affected text. Do not append another account of the new behavior. A new internal page needs a distinct, durable reason to exist.
docs/user/helps users accomplish tasks. Give each major feature a concise section explaining what it does, how to start, and anything unintuitive. A settings path is useful; descriptions of visible buttons, icons, layouts, animations, or every UI state are not. Before adding text, ask what task or decision it helps the user with.- Keep user docs in the shipped product's voice, without implementation details or contributor tooling. Update the relevant feature section when how to use it changes. A UI tweak does not need a documentation entry, and a new control does not need its own page.
docs/operations/holds maintainer setup, release, and debugging procedures. Keep instructions for operating an installed T3 Code server in the user guides.- Guidance for agents (this file,
.agents/skills/, tool descriptions, and prompts) follows the same rules and is read far more often. When a failure exposes a gap, prefer fixing the tool or its error message, which is read at the moment it matters. Otherwise change the sentence that misled, in the one file that owns the rule, and point to it from anywhere else that needs it. State the rule and its reason. The attempts that failed along the way do not each need a prohibition.
LastCode may contain generic, reusable infrastructure tooling only. Never put maintainer-specific machine names, private endpoints, host roles, network topology, ports, paths, service names, schedules, deployment configuration, credentials, operational procedures, or descriptions of how a maintainer uses the tooling in this public repository. This applies to code, documentation, fixtures, commits, branches, issues, pull requests, comments, reviews, releases, logs, screenshots, and generated artifacts. The private infrastructure project owns the concrete wiring, deployment policy, and operational detail.
Before any public GitHub write or push, inspect the proposed content for private
infrastructure details. A violation is blocking: stop and move the private
material to the infrastructure project rather than paraphrasing, abbreviating,
or encoding it. Public examples and test fixtures must use unmistakably generic
names such as workstation.example, managed-server, or build-host.
- Do not commit implementation plans, research notes, or agent scratch files. Keep temporary working material outside the worktree.
.plans/is gitignored only as a safety net for legacy tooling. - Track active maintainer work in the GitHub issue or project item that owns it. External proposals follow
CONTRIBUTING.mdand belong in Ideas discussions. - A merged PR is the implementation record. Close or update its tracking item when the work lands; do not preserve a second checklist in the repository.
Clients send typed WebSocket requests. The server turns them into commands. The orchestrator (apps/server/src/orchestration-v2/Orchestrator.ts) serializes commands and decides events without doing any I/O. The event sink commits those events, the projections the UI reads, the command receipt, and outbox effects in one transaction. The effect worker then runs the effects, such as starting a provider turn or capturing a checkpoint, and feeds results back as commands. Provider CLIs run as subprocesses; per-provider adapters translate their native protocols into orchestration events. Each turn ends with a checkpoint, a hidden git ref, so the app can diff and restore.
Architecture and its constraints: docs/internals/overview.md. Glossary: docs/internals/glossary.md
apps/server- WebSocket, orchestration, providers, checkpointing. Effect-heavy: read Effect services before adding server code, and.repos/effect/LLMS.mdfor the Effect library itself.apps/web- React/Vite UI.apps/desktopwraps it,apps/mobileis React Native,apps/marketingis the site.packages/contracts- Effect/Schema contracts plus small derived helpers. No heavy runtime logic.packages/shared- shared runtime utils, subpath exports, no barrel.packages/client-runtime- client code shared by web and mobile..repos/- vendored read-only references. Prefer their patterns over invented ones. Never edit or import from them. Sync withvpr sync:reposwhen bumping the matching dependency. If it is missing (sparse checkout), read a file withgit show origin/main:.repos/<path>.
- Complexity belongs at the adapter boundary. Orchestration stays pure, UI stays dumb.
- Client mutations use
createEnvironmentRpcCommand. Add protected methods toCLIENT_GUARDED_RPC_SCOPESin contracts and use the command'spermissionAtomfor UI availability. Grants are checked at execution against the destination environment; the server remains authoritative. Keep raw RPC clients insiderpc/, and extend the permission behavior tests when adding a protected method. - Server features are services; transports stay thin. A
ws.tsRPC handler, HTTP route, or MCP tool decodes input, calls one service method, and maps errors. See Effect services. apps/web/src/components/uiexports own their look. Pick avariantorsize; do not restyle one withclassName. If none fits and the look is a generic concept, add a variant to the component; a look that belongs to one feature stays in that feature's own component, not incomponents/ui. Layout classes (width, flex, margin, position) belong on the parent.shadcn/no-restylefails lint on violations. See Web UI.- Reusable Effect functions use
Effect.fn("Service.operation")with a stable span name, not a function wrappingEffect.gen. KeepEffect.genfor inline programs and layer construction. UseEffect.fnUntracedonly when spans would be too frequent (stream chunks, per-event projection, tight loops) or duplicate an existing tracing boundary; explain that choice nearby. NamedEffect.fncreates a span; the unnamed form does not. Preserve existing span names and options, and pass combinators as additional function-builder arguments. - Inferred types over annotations.
anyis the enemy. - Default to no comment. Write one only for a constraint, an external quirk, or an invariant the code can't show, in one line where you can and four at most. Don't restate names or signatures, narrate steps, record history, or explain the fix you just made; the PR carries that.
t3code/no-low-value-commentsenforces the length cap and the mechanical cases. - React effects are for synchronizing with something outside React. Derive in render and act in handlers instead of syncing state, but don't hide real lifecycle work in refs or stores to dodge one. The
t3code/no-unreasoned-state-synclint rule reports every effect; one that stays states its reason with// oxlint-disable-next-line t3code/no-unreasoned-state-sync -- <why>. - Our users drive agents all day and notice a dropped frame, a lying spinner, and a stale label. No continuously repainting animations; they peg the GPU on high-refresh displays.
- If a rule here fights the task in front of you, say so loudly and get a human sign-off before breaking it.
- Use background browser QA without a separate permission prompt. Foreground computer use and human acceptance remain subject to the machine interaction policy.
- Security is important, but should not be over-indexed on, especially for dev mode/maintainer-only features.
- Before a security audit or triaging a vulnerability report, read SECURITY.md for the trust model and what is intended.