unlock-ai-workbench
AGENTS.md4 starsChanged 4 months agoMITView on GitHub
T3 Code is a minimal GUI for coding agents. A Node WebSocket server wraps provider CLIs (Codex, Claude Code, Cursor, Grok, OpenCode) 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 100,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…
- Reads credentials
- Commits and pushes
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository6 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- .cursor/rules/cursor-cloud.mdcCursor rule
- ios-debugger-agentSkill
- ios-simulator-browserSkill
- test-t3-appSkill
- test-t3-mobileSkill
The file
We split this AGENTS.md into the rules it gives an agent
9 rules. About 0 are common, 8 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 63
Baking in origins: Never set VITE_HTTP_URL or VITE_WS_URL for dev.
- Distinctive: line 73
Reverse states: If you added a way in, add the way out and the way to see it.
- Distinctive: line 84
Stop what you started, by the PID you tracked.
- Distinctive: line 114
Never make a PR unless the developer explicitly asks you to do so.
- Distinctive: line 120
When babysitting: poll checks and comments newer than the last push, verify each bot finding against the source, fix real ones, dismiss …
- Distinctive: line 143
If a rule here fights the task in front of you, say so loudly and get a human sign-off before breaking it.
- Distinctive: line 147
Don't verify with browsers or computer use unless the user explicitly agrees or requests it.
- Distinctive: line 158
Delete merged branches, local and remote, after every merge (git push origin --delete BRANCH, then git remote prune origin).
- Distinctive: line 159
Keep large binaries out of git history: recordings, exports, and other heavy artifacts go to Agent Drop (or another owned store) with the …
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
T3 Code
T3 Code is a minimal GUI for coding agents. A Node WebSocket server wraps provider CLIs (Codex, Claude Code, Cursor, Grok, OpenCode) 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.
What makes T3 Code special?
We have over 100,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.
1. Open at the core
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.
2. Performance without compromise
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.
3. Remote ready
The architecture of T3 Code's websocket layer (npx 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.
4. Multi-surface
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 npx 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.
A note from Theo
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.
A small glossary
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.
The three ways to hurt yourself
- 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.
Hit every surface
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 - Providers. Codex, Claude, Cursor, Grok, and OpenCode each have an adapter. Provider-shaped features need a decision per adapter, even if the decision is "not supported here".
- 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.
- Docs.
docs/splits by audience. Behavior changes that a user would notice belong indocs/user/(shipped-product voice, no repo tooling or source paths); architecture and contributor changes indocs/internals/; runbooks indocs/operations/; new vocabulary indocs/internals/glossary.md.
Dev servers
vp iinstalls. Worktrees get this from the t3.json setup script; if module resolution looks broken, it probably did not run.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.- 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. --sharepublishes over the tailnet. Do not open the URL when you use this, just send it to the user with the pairing code included in url- The web app requires pairing. Hand over the pairing URL, not the bare origin. A URL without its token is useless to whoever you gave it to.
- Stop what you started, by the PID you tracked. See rule 1.
Test data
An empty database is a bad test. Seed your worktree's .t3 with a copy of real data instead of pointing at live state:
- Copy from
~/.t3/userdata(the developer's real data, the most realistic test set) or~/.t3/dev. Worktree state lives at<worktree>/.t3/userdata. Snapshot the database with
VACUUM INTO, which is safe even while a server has the source open and yields one consistent file:mkdir -p .t3/userdata rm -f .t3/userdata/state.sqlite* # VACUUM INTO refuses to overwrite bun -e "new (require('bun:sqlite').Database)(process.env.HOME + '/.t3/userdata/state.sqlite', { readonly: true }).run(\"VACUUM INTO '.t3/userdata/state.sqlite'\")"A plain
cpis only safe when no server has the source open, and must bring the-waland-shmsiblings along. A live file copy is a corrupt copy.- Bring
secretsandsettings.jsononly if the flow under test needs them. - Copy in, never symlink. Data flows one way: into your sandbox, never back out.
Verifying
- Smallest proof that the change works.
vp test run <files>for the tests you touched, targeted lint and typecheck for the scope you changed. - 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.
- The server is event-sourced and its async flows emit typed receipts. Wait on receipts and worker drains, never on sleeps or polling. A test that needs a timeout to pass is wrong.
- Upon request, user-visible frontend changes should get one integrated pass in a real client:
test-t3-appfor web,test-t3-mobilefor mobile. The primary agent does this once after integrating. Subagents do not launch their own dev servers. Ask permission before doing computer use or spinning up browsers.
Pull requests
- Never make a PR unless the developer explicitly asks you to do so.
- 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.
- Rebase onto latest main before opening. Stale branches conflict and burn a review round.
- UI changes need before/after images. Motion or timing needs a short video.
- One concern per PR. If the description says "also", split it.
- When babysitting: poll checks and comments newer than the last push, verify each bot finding against the source, fix real ones, dismiss false positives with a written reason. Stay quiet when nothing is new. Stop when the bots are green on the latest commit.
How it works
Clients send typed WebSocket requests. The server turns them into commands, a pure decider turns commands into persisted events, and a projector derives the read model the UI renders. Provider CLIs run as subprocesses; per-provider adapters translate their native protocols into orchestration events. Side effects run in queue-backed reactors that emit receipts when milestones land. Each turn ends with a checkpoint, a hidden git ref, so the app can diff and restore.
Full glossary with file links: docs/internals/glossary.md
Where code lives
apps/server- WebSocket, orchestration, providers, checkpointing. Effect-heavy: read.repos/effect-smol/LLMS.mdbefore writing Effect code.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.
Taste
- Complexity belongs at the adapter boundary. Orchestration stays pure, UI stays dumb.
- Inferred types over annotations.
anyis the enemy. - Comments describe how a thing is used, and move when the code moves. To be used mostly to describe functions, not to annotate every line of behavior.
- 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.
Additional tips
- Don't verify with browsers or computer use unless the user explicitly agrees or requests it.
- Security is important, but should not be over-indexed on, especially for dev mode/maintainer-only features.
Tracker and repository hygiene
Standing practice (Jonathan, 2026-08-30): the ticket board and the branch list must describe reality, so nobody starts a work session by cleaning up.
- At the end of every substantial working session — and always before marking a carrier issue
Done— audit the project's open Linear issues against what actually shipped. - Close as
Doneany issue whose deliverable now objectively exists, with a one-line evidence comment naming the merged pull request or the artifact. - Cancel any issue whose subject was cut or superseded by a recorded decision, with a one-line comment naming that decision. When a parent's children split between delivered and superseded, say which went where in one parent comment.
- An issue that is merely old is not stale; an issue that no longer describes work anyone intends is. When ownership of a lane is unclear, leave the lane and flag it to its owner instead of judging it.
- Delete merged branches, local and remote, after every merge (
git push origin --delete BRANCH, thengit remote prune origin). Close superseded pull requests with a comment saying what replaced them. - Keep large binaries out of git history: recordings, exports, and other heavy artifacts go to Agent Drop (or another owned store) with the link committed in their place.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

