T3 Tots rules

Every t3-* skill follows these rules. Other skills link here instead of repeating them.

Writes

Change nothing on the user's computers unless the user approved that exact change in chat. Approval for one change is not approval for the next. These skills may write, and only the thing named:

A saved sync list or update level is approval for a later "sync everything" or "update <level>" only for items already in that list, and only after this turn's diff is shown. Anything new still needs a yes.

Windows admin steps: the remote shell has no admin rights. When an approved step needs them, write a .ps1 that starts with Start-Transcript <log>, launch it with Start-Process pwsh -Verb RunAs -ArgumentList '-File','<script>', tell the user to click Yes on the UAC prompt, then poll the log until it shows done or an error. Don't ask the user to paste admin commands when this works.

T3 database

T3 Code keeps its state in <T3 home>/userdata. T3 home is T3CODE_HOME if set, else ~/.t3 (Windows %USERPROFILE%\.t3). The stable app and Nightly share that folder. Open statev2.sqlite there only read-only. Never INSERT, UPDATE, DELETE or VACUUM it, and never edit a copy. Writes into T3 go only through t3ctl.

Secrets

• Never open, list, print or copy T3's secrets/, clerk-tokens.json, cloud-auth-token.json, auth_sessions, or any *token*, *auth*, .env or credential file.
• From server-runtime.json, read only host, port and pid.
• The one token in use is the token file in the tools folder. Only t3ctl, t3listen, export.js and survey.js read it. Never print it.
• t3listen setup alone writes listen.json, which holds the webhook URL and key. Never open, print or copy it.
• If thread text contains a key, never repeat it.

Threads and settings

Never delete threads, and never change T3 settings. Archive or unarchive only a thread the user named, after their OK (t3-thread-actions). t3-update may update T3 Code, and t3-sync may copy the settings the user picked. Every thread action in the Writes table, and scheduled tasks (t3ctl tasks --upsert, --enable, --run, --delete), needs the user's OK for that exact action. The one exception is what delegated mode allows below.

Decisions

This section is the one source for who decides; other skills and AGENTS.md point here. A thread asks for two kinds of decision. A question (user_input) asks what to build. An approval asks permission to run a command or change files. Who decides depends on the mode the user set, which is saved in memory:

1. Default mode: show questions to the user as cards (or numbered options; see "Grok Bot only") and answer only with their exact pick for that question (t3-phone-answers "Answering"). Summarise approvals and leave them for the app, unless the user says yes to that request in chat. Offer thread actions such as resume-at-reset; don't run them.
2. Delegated mode starts when the user says something like "decide for me", "do whatever you need" or "I'm away, keep it moving". Record the scope and the end condition in memory. In this mode:
   • Answer routine questions yourself and tell the user afterwards what you picked and why.
   • Never accept an approval yourself. A thread asks for one only when a safety check flagged the command (for example a git hook on git reset --hard), even in full access. Decline it with t3ctl answer --thread <t> --request <id> --decision decline --redirect. That also tells the thread not to retry or work around it, to use a safer way or skip that step, and to carry on. Log it, and list every declined approval with its reason in your report.
   • Run the delegated-mode actions in the Writes table, and log each one.
   • Escalate questions about product direction, money, publishing, or anything the user said to keep for themselves.

The prompt T3 shows is often a short description ("Redo merges with PR names"), not the command itself. t3ctl pending prints why it asks: with the reason the safety check gave, and pending --json has it as approval.reason. Show the reason to the user on the card. Never judge an approval safe from its text.

t3ctl answer --decision accepts an approval only with --user-approved. Pass it only after the user's yes for that request. Otherwise it refuses with NEEDS_USER_APPROVAL and sends nothing. decline and cancel need neither. Always pass --request <id> with the id the user saw. When several approvals are open, or the id matches more than one, t3ctl stops with AMBIGUOUS instead of picking one.

Never invent the user's preferences. The thread decides how to do the work. The user decides what to build. Your prompts carry the user's context, not your design choices.

Sending into threads

• Before a follow-up, read the thread's recent history (t3ctl read --thread <t> --last 6) so you don't repeat or contradict it.
• t3ctl send steers into a running run by default and checks that the message arrived. Relay its notes:
  • DELIVERY_FIXED: the queue was stuck and t3ctl resumed it.
  • QUEUE_HELD: someone held the queue on purpose. Ask before t3ctl queue --thread <t> --resume.
  • SEND_STUCK: the message is waiting in the queue. Check t3ctl queue --thread <t>.
• Use --prompt-file <file> for any prompt over a few lines. new, send and tasks --upsert accept it, in UTF-8 or the UTF-16 that Windows PowerShell writes.
• Write prompt files to <tools folder>/out/prompts/<date>-<short name>.md, not /tmp. They survive a restart, and the user can see what was sent.
• Keep messages to a thread short and concrete. Say what the thread already did right, then the next step. Leave out check-ins ("how is it going?"), your own process, and these rules. The thread gets only what it needs to act.
• After answering a request, t3ctl lists the requests still open in that thread. Clear leftovers in T3 or tell the user.

Finding a thread

Many skills start from words the user typed. Run T3_Q='<words>' python3 t3q.py thread on every computer and take the best score overall. T3_Q also takes a thread id or an id prefix of 8 or more characters. Threads that agents spawned match only with T3_ALL=1. t3q.py exits 1 with AMBIGUOUS when the top two are within 0.1 and with NO_GOOD_MATCH when the best is under 0.6; list the closest ones it prints and ask. If you act on the best and another match scored 0.6 or more, name it in one line so the user can correct you. If worktreePath is empty and the messages name another working folder, use that folder and say which one. A thread lives on one computer: search all, act only on the owner. With a token, t3ctl search --query '<words>' also finds a thread by content. t3ctl --thread takes a full id, an id prefix of 8 or more characters, an exact title, or words found in exactly one title. More than one match exits 1 with AMBIGUOUS and the candidates, so pass the full id.

Grok Bot only

These steps need tools only Grok Bot has. A skill that uses them points here in one line. Any other agent (Claude Code, Codex, Cursor and so on) runs on one computer and does this instead:

Computers

Grok Bot only (see "Grok Bot only"). Call ListMachines every run. Never hard-code machine ids or home paths. The default scope is every connected computer with T3 data, run in parallel and labelled by name. Narrow it only when the user names one ("mac only"). To create things, use the computer the user names, else the one their message came from. Say which computers were offline, once per outage, then check quietly until each is back. Keep a Mac awake (caffeinate -dimsu -w <pid> tied to the job, or ask the user to change the setting) when a watch or delegated run must last overnight.

Shells

macOS zsh: wrap commands in a function, f(){ ...; }; f, and use quoted heredocs. Windows: PowerShell. Linux: bash. Examples in skills are POSIX. On Windows, translate them:

An $env: setting stays for the rest of the session, so clear it after use: $env:T3_Q='x'; py -3 t3q.py thread; Remove-Item Env:T3_Q.

Tools on each computer

The tools folder is the one saved in memory at setup. If memory has none, use ~/t3-tots (Windows %USERPROFILE%\t3-tots) if it exists, else ask, and save the answer to memory. A new install defaults to ~/t3-tots. Every script works from wherever it lives and reads the token file next to it. t3ctl and t3listen also need thread-match.js next to them.

Run scripts from the tools folder. Use python3 on macOS and Linux. On Windows use py -3, else python, and never the bare python3 Store alias. Run Node scripts as node <file>. On Windows always run node t3ctl and node t3listen, never the .cmd wrappers, which drop double quotes. A value that starts with -- goes in as --key=value, for example --text=--force. Minimum versions: Python 3.8 (3.9 for report.py), Node 22 for t3ctl and t3listen, Node 18 for export.js and survey.js.

t3q.py

Read-only database queries. It needs no token. Commands: overview, waiting, thread, projects, health, usage. Settings: T3_DAYS, T3_ALL=1, T3_Q (thread words or id), T3_LAST, T3_WEEK=1.

t3ctl

Uses T3's local API and needs the token, except skills. Running it with no arguments prints usage. This is the full command list for this release; other skills use these names. If a command prints the usage line instead of running, that computer has older tools: say so once and offer t3-install-tools "Updating". Don't retry other spellings.

--project takes a project id, its folder, an exact title, then the one title containing the words. Several matches print AMBIGUOUS with the candidates (never the first one); an empty value is a usage error.

status --json adds queued (messages waiting in the queue) and queueHeld (the queue was held on purpose); threads and status show a held queue as queue held and settled threads as (settled). threads --main hides threads that agents spawned (reviewers, sub-tasks), the same split t3q.py uses. A PM's or a thread's sub-task threads are listed by subtasks --thread t. models lists the models already used in T3, with the name of each provider's effort setting; skip the <synthetic> entry. limits prints reset times in local time and marks a reset that already passed with (passed).

The default token scopes don't cover usage or cost totals, T3 settings (including "Auto-resume limited threads"), managing or removing worktrees, file writes or terminals. Starting a thread in a new worktree with new --worktree works with the default token.

t3ctl watch prints only what changed since its last run, so an empty output means nothing changed, with or without --json. Its state lives in the file given with --state, relative to the folder it runs from (default watch-state.json in the tools folder). Events:

t3listen

Optional. It needs the token and listen.json. It follows T3's live events and POSTs question and finish events to the user's webhook routine (t3-phone-answers). Commands: setup, test, install [--approvals], uninstall, status, preview-finish --thread id|title (same thread rules as t3ctl: full id, an 8+ character prefix, an exact title or one title match, else AMBIGUOUS); --dry-run prints instead of sending. It sends approvals too when listen.json has "approvals": true or the service was installed with --approvals; status prints which. Running install again keeps the listen.json setting and drops the flag unless you pass it again. When a main thread stops on a usage limit, t3listen arms T3's Resume at reset if the project is listed in autoresume.json ({"enabled":true,"projects":[...]}) or t3ctl new started the thread (recorded in started-here.json for 60 days).

Other scripts and data files

• export.js writes a redacted JSON export for reports. Options work like t3ctl (--project Foo or --project=Foo; an unknown option is USAGE). --project is a filter: an exact id, else a folder, else an exact title (case ignored) picks that project, and two exact matches stop with AMBIGUOUS listing them; otherwise every project whose title contains the words is exported, and it prints a note naming them. No --project means all. survey.js lists activity and stale threads.
• t3ui and ui-*.applescript are a macOS-only UI fallback. They use the running T3 Code app, or T3_APP.
• Data files the skills create in the tools folder: templates.md, trackers/, update-prefs.json, sync-prefs.json, sync-backups/, out/, README.md, watch-state.json, watch-<name>.json, autoresume.json. t3ctl new writes started-here.json. t3listen writes listen.json (private), listen-state.json, answered-here.json and listen.log.
• Don't leave scratch files (CSVs, .bak copies, screenshots) in the tools folder. Put scratch files in out/. On Grok Bot, pages are built on the box (/workspace).

Master copy

The reference copy lives on the box at /workspace/t3-tots-tools/, installed and sha256-verified by t3-install-tools. Its manifest.json is the reference for every computer. Skill folders don't carry their own copies of the scripts. If the master copy is missing, run t3-install-tools "Box copy". If a computer lacks a script or a hash differs from manifest.json, say so and offer to reinstall.

Status words

Scripts print these words. Relay them in plain words, not as errors. This is the one list; AGENTS.md and other skills point here.

The T3 CLI is ~/.t3/bin/t3 (Windows %USERPROFILE%\.t3\bin\t3.cmd, or under T3CODE_HOME/bin). T3 Code writes it when the app starts.

Token

The token gives write access to T3. Issue or reissue it only after the user's yes. Run from the tools folder, never echo it, and write it straight to the file:

• macOS and Linux: (umask 077; ~/.t3/bin/t3 auth session issue --scope orchestration:read --scope orchestration:operate --ttl 90d --label t3-tots --subject t3-tots --token-only > token)
• Windows PowerShell: & "$env:USERPROFILE\.t3\bin\t3.cmd" auth session issue --scope orchestration:read --scope orchestration:operate --ttl 90d --label t3-tots --subject t3-tots --token-only | Out-File -Encoding ascii token; icacls token /inheritance:r /grant:r "$($env:USERNAME):(R,W)" | Out-Null. Plain > in Windows PowerShell writes UTF-16 and breaks the token.

Check the token only by running t3ctl projects. Record the issue date and the 90-day expiry in README.md, with how to revoke it: t3 auth session list, then t3 auth session revoke <id>.

Opt-in features

Digests, the recurring cleanup scan, stale-thread lists, watches and phone answers run only after the user turns them on. Leave out usage and cost figures unless the user asks (t3-usage). The shipped routines (t3-getting-started section 6) stay paused until the user turns them on. Turning one on counts as asking for what it reports. Turning on T3 Tots weekly update also counts as the yes for its runs to install a newer T3 Tots release (t3-install-tools "Weekly update run"). "Update T3 Tots" in chat still shows the plan and asks. To turn one on, resume the shipped routine and update the "Routines on" memory note. Never create a duplicate.

Memory

• Save decisions, modes and preferences, not activity. A check where nothing changed is not worth a memory entry or a journal line.
• Keep personal facts (names, machines, projects, model picks) in the user's memory, never in a skill.
• When the user corrects you, save the correction in their memory so it holds next time.
• A follow-up you promise for later ("I'll check when the run ends") goes into a watch or a routine, not only into memory, so it happens.

Output

• Give times in the user's timezone with a label, sizes in decimal GB, and home paths shortened to ~.
• Answer first, in short plain words. Say what you couldn't check.
• Send one message per event. If a watch and t3listen both report the same finish, say it once.
• Send files with SendToUser rather than pasting them. Pass box_path to CopyToBox when the file must land somewhere other than uploads.
• Don't present the user's own rules back to them as blockers. Follow the rule and say what you did.
• Grok Bot: when you start a cloud agent, leave fast mode off.