You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 2038f11
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: AGENTS.md
+18-9Lines changed: 18 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -28,7 +28,7 @@ T3 Code has 3 key app surfaces: **web**, **desktop**, and **mobile**.
28
28
29
29
**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.
30
30
31
-
**Mobile** is a React native app for both iOS and Android. The mobile app allows for connecting to any T3 Code server to control work remotely. It is still in early access (Testflight), but it is pretty close to shipping globally.
31
+
**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.
32
32
33
33
## A note from Theo
34
34
@@ -59,7 +59,7 @@ We need to be on the same page with terminology. When communicating, use this la
59
59
## The three ways to hurt yourself
60
60
61
61
1.**Killing by pattern.** Never `pkill -f`, `pgrep | kill`, or `kill` a 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 from `ss -H -ltnp` after confirming `/proc/<pid>/cwd` is your worktree.
62
-
2.**Touching the live install.**`~/.t3/userdata` is the developer's real T3 Code database, in use while you work. Read-only inspection is fine. Never start a server against it, never open it read-write, never clean it up.
62
+
2.**Writing to the live install.**`~/.t3/userdata` is 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.
63
63
3.**Baking in origins.** Never set `VITE_HTTP_URL` or `VITE_WS_URL` for 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.
64
64
65
65
## Hit every surface
@@ -72,7 +72,7 @@ The most common defect in this repo is a change that works on the path you teste
72
72
-**Contracts.** Anything crossing the wire is typed in `packages/contracts`. Change the schema and the server, web, mobile, and desktop all follow.
73
73
-**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.
74
74
-**Connection modes.** Local, remote/relay, and tunnel behave differently. Multi-device and multi-environment cases are real.
75
-
-**Docs.**`docs/`mirrors this structure. Behavior changes that a user would notice belong in `docs/user/`; architecture changes in `docs/architecture/`; new vocabulary in `docs/reference/encyclopedia.md`.
75
+
-**Docs.**`docs/`splits by audience. Behavior changes that a user would notice belong in `docs/user/` (shipped-product voice, no repo tooling or source paths); architecture and contributor changes in `docs/internals/`; runbooks in `docs/operations/`; new vocabulary in `docs/internals/glossary.md`.
76
76
77
77
## Dev servers
78
78
@@ -85,10 +85,19 @@ The most common defect in this repo is a change that works on the path you teste
85
85
86
86
## Test data
87
87
88
-
An empty database is a bad test. Seed your worktree's `.t3` instead of pointing at live state:
88
+
An empty database is a bad test. Seed your worktree's `.t3` with a copy of real data instead of pointing at live state:
89
+
90
+
- Copy from `~/.t3/userdata` (the developer's real data, the most realistic test set) or `~/.t3/dev`. Worktree state lives at `<worktree>/.t3/userdata`.
91
+
- Snapshot the database with `VACUUM INTO`, which is safe even while a server has the source open and yields one consistent file:
92
+
93
+
```bash
94
+
mkdir -p .t3/userdata
95
+
rm -f .t3/userdata/state.sqlite*# VACUUM INTO refuses to overwrite
96
+
bun -e "new (require('bun:sqlite').Database)(process.env.HOME + '/.t3/userdata/state.sqlite', { readonly: true }).run(\"VACUUM INTO '.t3/userdata/state.sqlite'\")"
97
+
```
98
+
99
+
A plain `cp` is only safe when no server has the source open, and must bring the `-wal` and `-shm` siblings along. A live file copy is a corrupt copy.
89
100
90
-
- Copy from `~/.t3/dev`, never from `~/.t3/userdata`.
91
-
- Copy `state.sqlite` together with its `-wal` and `-shm` siblings, and only while no server has the source open. A live copy is a corrupt copy.
92
101
- Bring `secrets` and `settings.json` only if the flow under test needs them.
93
102
- Copy in, never symlink. Data flows one way: into your sandbox, never back out.
94
103
@@ -114,13 +123,13 @@ An empty database is a bad test. Seed your worktree's `.t3` instead of pointing
114
123
115
124
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.
116
125
117
-
Full glossary with file links: `docs/reference/encyclopedia.md`
126
+
Full glossary with file links: `docs/internals/glossary.md`
-`apps/web` - React/Vite UI. `apps/desktop` wraps it, `apps/mobile` is React Native, `apps/marketing` is the site.
123
-
-`packages/contracts` - Effect/Schema contracts. Schema only, no runtime logic.
132
+
-`packages/contracts` - Effect/Schema contracts plus small derived helpers. No heavy runtime logic.
124
133
-`packages/shared` - shared runtime utils, subpath exports, no barrel.
125
134
-`packages/client-runtime` - client code shared by web and mobile.
126
135
-`.repos/` - vendored read-only references. Prefer their patterns over invented ones. Never edit or import from them. Sync with `vpr sync:repos` when bumping the matching dependency.
Copy file name to clipboardExpand all lines: README.md
+15-12Lines changed: 15 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# T3 Code
2
2
3
-
T3 Code is an "agent harness control surface". It enables control of the agents on your machine with a best-in-class mobile app, [web app](https://app.t3.codes) and [Electron-based desktop app](https://t3.codes).
3
+
T3 Code is an "agent harness control surface". It enables control of the agents on your machine with a best-in-class mobile app ([iOS](https://apps.apple.com/us/app/t3-code-remote-claude-more/id6787819824), [Android](https://play.google.com/store/apps/details?id=com.t3tools.t3code)), [web app](https://app.t3.codes) and [Electron-based desktop app](https://t3.codes).
4
4
5
5
Works with your subscriptions on Claude Code, Codex, Cursor, Grok Build, and OpenCode. If they're set up on your computer, T3 Code can control them.
6
6
@@ -17,13 +17,13 @@ We wanted something performant, remote-ready, and truly open. If we ever go the
17
17
>
18
18
> - Codex: install [Codex CLI](https://developers.openai.com/codex/cli) and run `codex login`
19
19
> - Claude: install [Claude Code](https://claude.com/product/claude-code) and run `claude auth login`
20
-
> - Cursor: install [Cursor CLI](https://cursor.com/cli) and run `cursor-agent login`
20
+
> - Cursor: install [Cursor CLI](https://cursor.com/cli) and run `agent login`
21
21
> - Grok Build: install [Grok Build CLI](https://x.ai/cli) and run `grok login`
22
22
> - OpenCode: install [OpenCode](https://opencode.ai) and run `opencode auth login`
23
23
24
24
### Try it out (install-free)
25
25
26
-
The easiest way to test T3 Code is to run the server in your terminal:
26
+
The easiest way to test T3 Code is to run the server in your terminal (requires Node.js 22.16+, 23.11+, or 24.10+):
27
27
28
28
```bash
29
29
npx t3@latest
@@ -61,17 +61,20 @@ We are very very early in this project. Expect bugs.
61
61
62
62
We are (mostly) not accepting contributions yet. Small fixes may be considered. Big features will not be.
63
63
64
-
There's no public docs site yet, checkout the miscellaneous markdown files in [docs](./docs).
0 commit comments