T3 Code Agent Rules

Web, desktop, and mobile clients for controlling coding agents on your own machines.

Overview

Contributors may be working inside the T3 Code app they are changing, so the guide protects the live process and database. It also checks changes across clients and providers, and explains how commands become events.

Hard prohibitions Behavioral framing Architecture as narrative Pointing at the source of truth House vocabulary

Documents

├── 
├──  · imports AGENTS.md
├── .repos
│   └── effect-smol
│       └── 
├── docs
│   ├── internals
│   │   └── 
│   └── operations
│       └── 
├── 
├── test-t3-app — test-t3-app verification skill
└── test-t3-mobile — test-t3-mobile verification skill

Techniques in this file

01 / Hard prohibitions

Protect the process hosting the contributor

The process rule bans selecting a process to kill by a name or path match because the agent itself can match that pattern. It gives two narrower ways to identify a process the contributor owns.

611. **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.

02 / Hard prohibitions

Keep test data separate from live state

The live database may be read and copied but never opened for writes or used by a server. Test data comes from consistent one-way snapshots, not symlinks.

622. **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.

03 / Behavioral framing

Check the reverse operation

The cross-surface checklist includes entry points, clients, providers, contracts, and connection modes. One item requires a way back out of a new state, with snooze and close as concrete examples.

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.

04 / Architecture as narrative

Describe the event pipeline

The architecture paragraph traces a request through commands, decisions, persisted events, projections, adapters, and reactors. It connects typed completion receipts with the checkpoints used for diffing and restoring a turn.

145Clients 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.

05 / Pointing at the source of truth

Reserve documentation for reasoning the code does not carry

Internal documentation is for decisions, cross-component constraints, and traps. The guide asks what a maintainer would get wrong without the paragraph and rejects duplicating facts that the relevant code already answers.

129- `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.

06 / House vocabulary

Disambiguate the actor from the agent being built

The glossary separates the contributor agent, maintainers, end user, provider, and client. It also defines environment, project, thread, and turn so discussions about this agent product use the same terms.

47- **you** means the agent reading this file and changing T3 Code.48- **we, us, and maintainers** mean Theo, Julius and the people building T3 Code. These are who you are talking to now.49- **user** means the person using T3 Code to direct coding agents.50- **agent** means the coding agent a user runs inside T3 Code. Depending on context, that may also include you.51- **provider** means the agent runtime or harness T3 Code talks to, such as Codex, Claude, Cursor, or OpenCode.52- **client** means the web, desktop, or mobile UI.

Ideas for your repo

Protect the live application that contributors may be using to do the work.
Create isolated test data with a documented, consistent snapshot method.
Check reverse actions and alternate entry points alongside the main flow.
Explain the system as a sequence of transformations and completion signals.
Keep internal documentation focused on reasoning and constraints that code cannot explain alone.