Always isolated
A normal thread never edits the current checkout and never inherits the active thread’s workspace mode.
The product promise
Safe by default. Explicit by exception.
A user should be able to press “New thread,” start typing, and trust the environment without checking their terminal, current branch, or last pull.
Always current
The base is fetched from the primary remote at send time—not whatever a local branch happened to contain.
Always legible
Before sending, the composer says exactly where work will happen and what ref it will start from.
The ordinary flow
One click, one trustworthy contract.
The draft records intent. The connected environment turns that intent into a pinned, reproducible workspace only when the first message is sent.
User
New thread
No branch or workspace prompt interrupts the common path.
Draft
Shows intent
“Fresh worktree · latest origin/main” is visible beside the composer.
Environment
Fetches remote
The primary remote’s default branch is resolved at first send.
Git
Pins the SHA
A new branch and worktree are created from the fetched commit.
Agent
Starts work
Setup completes first; only then does the agent receive the task.
Workspace choices
Three modes. One real default.
The alternatives remain easy to reach, but choosing one changes only the current draft. It does not quietly retrain the next “New thread.”
Fresh worktree from latest default
Fetch the primary remote, resolve its default branch, pin the resulting commit, and create an isolated workspace.
Applies to every ordinary new thread
Current checkout
Use the environment’s existing directory exactly as it is, with a clear warning that changes are not isolated.
This draft only
Worktree from another ref
Choose a branch, tag, or commit, then create a fresh worktree pinned from that selected ref.
This draft only
Composer experience
The decision is visible where it matters.
Workspace intent belongs beside the message—not buried in global settings and not inferred from whichever thread was previously open.
Untitled draftConnected · Julius’s Mac mini
Start a new task.
The workspace will be prepared on first send.
The workspace will be prepared on first send.
Ask T3 Code to build something…
“Change…” opens the two exceptional paths. The primary label remains descriptive—not a toggle whose state must be remembered.
Hard invariants
Behavior users can build trust around.
These should be product-level rules shared by every entry point: sidebar button, keyboard shortcut, command palette, URL, desktop app, and mobile client.
✓
No accidental inheritance
An ordinary new thread does not copy the active thread’s branch, workspace mode, or draft exception.
✓
No manual pull ritual
Freshness comes from fetching the remote ref during workspace creation, not updating a user’s local main.
✓
No silent fallback
If a fresh worktree cannot be created, the task does not quietly run in CWD or on stale state.
✓
No sticky exceptions
Choosing current checkout or another ref affects the current draft unless the user separately edits their default.
✓
One server-side authority
The connected environment validates, fetches, resolves, pins, creates, and reports the actual workspace.
✓
One meaning everywhere
“New thread” has the same semantics on the hosted site, installed app, and CLI-connected environment.
Settings architecture
One settings experience, clear ownership.
Centralization should mean one coherent control plane—not forcing every value into one database. Each setting lives where its authority naturally belongs and the UI explains that scope.
Account
New-thread policy, provider preferences, confirmations, favorites. Synced across clients.
Device
Theme, layout, notifications, and shortcuts that belong to this browser or app.
Environment
Provider binaries, project roots, shell behavior, credentials, and Git capabilities.
Project
Setup commands, remote choice, default-branch overrides, and repository-specific behavior.
account preference + device context + selected environment + project policy + draft override → effective behavior
The user sees one resolved answer—with provenance—while secrets and machine-specific configuration remain on the connected environment.
Settings UI
Never pretend a setting was saved.
Every control names its scope. Environment settings require an environment context. Writes show pending, success, or failure—there are no silent no-ops and no immediate snap-back to mystery defaults.
Account default
Workspace strategy
Used by every client unless this draft explicitly overrides it.
Fresh worktree from latest default⌄
Project · t3code
Primary remote
Used to resolve the repository’s latest default branch.
origin · main
Environment
Workspace root
Stored and validated on Julius’s Mac mini.
~/.t3/worktrees
System contract
Intent on the client. Truth on the environment.
The hosted site can be the front door without becoming the owner of machine state. It asks for a strategy; the connected environment safely executes and reports the result.
Client responsibilities
Capture and explain intent
- Resolve account defaults for the current project
- Display the effective workspace strategy
- Collect explicit, draft-only exceptions
- Show preparation progress and actionable failures
- Never claim success before the environment confirms it
Environment responsibilities
Establish and report truth
- Validate repository and Git capabilities
- Fetch and resolve the remote default ref
- Pin a concrete commit before creating the worktree
- Create the branch, workspace, and setup environment
- Return the actual path, ref, SHA, and readiness state
Failure behavior
Fail closed, then offer informed choices.
A reliability feature is only real if it survives failure. The product must preserve the user’s isolation and freshness intent instead of optimizing for “something started.”
Couldn’t prepare a fresh worktree from origin/main.
The remote could not be reached. Nothing has started and your current checkout was not modified.
- Retry fetch
- Inspect connection details
- Use the last known remote commit — explicit confirmation required
- Use current checkout — explicit confirmation required
Definition of done
The experience is right when…
These are behavioral acceptance criteria, independent of a particular storage model or migration path.