[docs] "Can I use tmux for coding?" has no correct answer in the docs — the architecture split is documented, the user-facing choice and its unmetered cost are not

[serge-ivo]

The docs are right about the architecture and silent about the choice — so "can I use tmux?" has no correct answer to look up

Filed after I gave the owner a wrong-in-effect answer twice in one session. Worth recording precisely, because the docs are not wrong — which is why this was hard to spot.

What the docs already get right (do not change these)

• platform-docs/browser-runtime.md:102 — Coder runs the CLI as a child process over stream-json; "It is not a tmux pane, and the terminal view is not a scraped TUI."
• platform-docs/browser-runtime.md:121 — "tmux is still used on this platform, but by a different family: the terminal connector… Those create real tmux sessions; Coder agents do not."
• platform-docs/coder-multi-machine.md:118 — the coding_sessions.tmux_session column keeps its old name but stores an engine label.
• platform-docs/connectors.md:42 — the tmux connector's tool list.

Every one of those is accurate. The architecture split is documented.

What is missing

1. Nowhere says a coding CLI can be driven through the terminal connector — which is the actual user-facing choice.

The docs say tmux "belongs to the terminal connector" and stop. They never state the thing that follows from it: a subscriber can point a tmux/kitty/iTerm2 Operator at a pane running Claude Code and drive it. That is a real, working, supported path — #348 exists because people do it — and the owner of this platform correctly remembered building it while the docs gave no way to confirm that.

So the question "is tmux available for coding?" has two true answers depending on which product you mean, and no document distinguishes them.

2. The single most decision-relevant fact is not in any doc.

grep -rn "unmetered" docs/ platform-docs/   →   no matches

A CLI driven through a pane produces no cost record at all. That is stated only in a source comment (packages/browser-runner/src/coding/terminal.ts:67-78):

"The platform cannot measure what an AI CLI inside a pane spends: a pane holds rendered text, not the stream-json result event headless.ts reads. So the cloud records the drive as UNMETERED… It is a name, never a number — no cost figure is ever parsed out of pane output, because a scraped dollar amount would be a guess dressed as a measurement."

This is exactly what a user weighing the two paths needs, and it is invisible unless you read the runner source. It also makes a whole class of question ("compare my tmux vs non-tmux spend") unanswerable — a fact worth stating once in a doc rather than rediscovering from a $0 row.

3. docs/coding-engines.md documents the engine presets and never mentions the alternative.

Its only tmux reference is a parenthetical about what "tmux used to provide" (:46). A reader choosing an engine has no pointer to the terminal-connector path, or to why they might want it (a real PTY, tmux attach from their own shell) or not (no metering, no structured turn boundary, scraped text).

4. #249 is an open decision no document references.

#249 — "Decide: should tmux return as a selectable Coder engine backend? (real PTY + attach)" is the ticket that would collapse the two paths into one. Nothing in the docs mentions that the current split is provisional, so a reader reasonably concludes it is settled.

What to write

A. A short section in docs/coding-engines.md: "Two ways to drive a CLI." A comparison table, because the differences are what matter:

	Coder engine (child process)	Terminal connector (tmux/kitty/iTerm2)
How it runs	child process, stream-json	a real pane on your machine
Turn boundary	a result event — a fact	inferred from rendered text
Cost recorded	yes, from the CLI's own total_cost_usd (#267)	no — unmetered by design (#348)
tmux attach from your shell	no session to attach to	yes
Which agents	Coder	tmux / kitty / iTerm2 Operators

B. One line in platform-docs/browser-runtime.md:121, after "Coder agents do not": say that terminal-operator agents can be pointed at a pane running a coding CLI, and link to (A).

C. State the metering consequence where cost is discussed, not only in terminal.ts. The Usage page's own docs are the right home: a total that silently excludes pane-driven work is misleading without the note.

D. Reference #249 from (A) so the split reads as a live decision rather than a settled boundary.

Evidence that this is a real doc defect and not just my error

I gave the owner two answers in this session that the docs did not prevent:

1. "There's nothing to test — Coder does not use tmux." True, and useless: they had four Operator instances doing the thing they were asking about.
2. "tmux is not available as an option." Wrong as stated. It is available, via a different agent family.

The owner's own recollection — "we even built a connector and an agent, I thought!" — was correct, and there was no document that would have confirmed it. When the person who commissioned the feature cannot look it up, the gap is in the docs, not in their memory.

Alternatives considered and rejected

• Rewrite browser-runtime.md to be less emphatic about "NOT tmux". Rejected — that emphasis exists because Coding sessions no longer use tmux, but the names, diagnostics, kill-tmux control and docs all still say they do #247 found the names, diagnostics and docs all still claiming tmux after it was removed. Weakening it re-opens that. The fix is to add the second path, not soften the first.
• Put it all in pags/CLAUDE.md. That file already carries the distinction and is agent-facing; this needs to be in the published docs, where a subscriber can read it.
• Wait for Decide: should tmux return as a selectable Coder engine backend? (real PTY + attach) #249 and document whatever it decides. Rejected — the two paths both exist today and the metering difference bites today.

Acceptance criteria

• A reader can answer "can I use tmux to run a coding CLI?" from the published docs, with the trade-offs, without reading source.
• The word "unmetered" (or its plain-English equivalent) appears where cost and where engine choice are documented.
• docs/coding-engines.md links to the terminal-connector path, and browser-runtime.md links back.
• Decide: should tmux return as a selectable Coder engine backend? (real PTY + attach) #249 is referenced as the open decision that would merge the two.
• Nothing in the existing "Coder is not tmux" statements is weakened.

Related: #247 (removed tmux from Coder — the change these docs describe), #249 (the open decision), #348 (the unmetered finding that belongs in a doc), #267 (engine metering, the other half of the comparison).

[serge-ivo]

Measured, from an account actually running the comparison this doc would inform

A live tmux Operator instance ("Heartfull (tmux)", cda75e28-…) exists specifically to be the tmux
half of a cost comparison against a Repo Coder on the same repository, same objectives, different
driver — its Special Instructions say so, and they also say, correctly:

"You cannot see token counts or cost — the platform does not meter what happens inside a tmux
pane. Never estimate, guess, or report a dollar figure for the CLI's work."

Here is what the platform reports for those two paths over the same 7 days (usage_summary, range
7d; every figure is tokens × list price, not a bill):

	notional cost	calls
agent_coder_repo (Repo Coder — engine spend lands here)	2,649,248,931 µ$ ≈ $2,649	997
cda75e28-… (the tmux Operator instance)	2,692 µ$ ≈ $0.0027	54

By kind: engine = 2,634,475,688 µ$ over 189 calls — 98.7% of the account's entire notional total
is engine spend that only the Coder path records. The tmux instance's $0.0027 is its orchestrator
chat and nothing else; the Claude Code turns it drove are not in any row.

This is the sentence §2 of this issue asks for, made concrete: the two paths do not differ by a
factor, they differ by a category. A reader comparing "$2,649" against "$0.0027" without the
doc in front of them will draw exactly the wrong conclusion, and the numbers are right there on the
Usage page.

Suggested addition to the comparison table proposed in §A — a row and a footnote:

	Coder engine (child process)	Terminal connector (tmux/kitty/iTerm2)
What Usage shows	the CLI's own total_cost_usd	a drive count, no cost — and a smaller cost figure here means less was measured, not less was spent

Two more facts the choice turns on, found in the same session

1. The tmux path has no cloud route to GitHub. Filed as #493. The Operator's only GitHub access
is gh inside the pane, so when the machine is off it can answer nothing — the Repo Coder, cloud-
side, can still list issues and PRs. That is a second axis of the choice this doc does not mention,
and it is the one the owner actually hit.

2. The drive count cannot currently say an AI CLI was in the pane. Filed as #498: tmux's
#{pane_current_command} returns Claude Code's rewritten process title (measured on the machine:
2.1.226), so isAiCli is false and aiCliDrives reads 0 for a week of driving Claude Code.
Until that is fixed, the Usage page's "N drives… with an AI coding CLI running" clause never
renders — worth knowing before the doc points a reader at it.

Nothing above changes this issue's diagnosis; it supplies the numbers §2 says are missing.

[serge-ivo]

Delivered. All five acceptance criteria are met on main — recommend closing

Verified 2026-08-18 against origin/main @ 6ceec4f. Every item this issue asked for exists, and one of them turned into an ADR.

AC	Evidence
A reader can answer "can I use tmux to run a coding CLI?" from the published docs, with the trade-offs	docs/coding-engines.md:8-26 — opens with "'Can I use tmux for coding?' has two true answers, because there are two products", then the comparison table proposed in §A, with the rows for turn boundary, cost, tmux attach and which agents
"unmetered" appears where cost and engine choice are documented	docs/coding-engines.md:21 (the table row), :278, :282; platform-docs/connectors.md:56-59; platform-docs/browser-runtime.md:123. §B's numbers landed too: "A $0 there means not measured, not free."
coding-engines.md links to the terminal-connector path, and browser-runtime.md links back	browser-runtime.md:123 links to both docs/coding-engines.md → "Two ways to drive a CLI" and ADR 0003; coding-engines.md:28-34 links to the ADR
#249 is referenced as the open decision	Referenced — and answered. See below
Nothing in the existing "Coder is not tmux" statements is weakened	browser-runtime.md:121 is intact verbatim; the new paragraph is additive at :123

The fourth criterion did better than asked

This issue asked for #249 to be referenced as an open decision. It was decided instead, and recorded as an ADR — docs/adr/0003-a-coder-engine-reports-its-own-turns.md, Status: Accepted (2026-08-08), Owner decision. docs/coding-engines.md:28-34:

"The split is settled, not provisional. #249 asked whether tmux should come back as a selectable Coder engine backend; the answer was no … the strongest argument for it (turns being cut off mid-work) was a timer bug, fixed in #391 without a terminal; a PTY is not tmux, and only tmux gives up measurement; and the three subsystems built on structured output — usage, the acts audit, merge authority — cannot be recovered from a screen buffer. If a real PTY is ever needed, ADR 0003 says it goes inside HeadlessSession (node-pty), not into a pane."

So this ticket's AC 4 is met in the stronger form, and #249 — which this issue cites as the open decision it depends on — is settled. I have commented there separately; that ticket's close belongs to the delivered-issues sweep, not here.

One thing that did not land, and it is not this issue's

§2's measured evidence (2026-08-10 comment) and the suggested extra table row — "a smaller cost figure here means less was measured, not less was spent" — is captured in prose at browser-runtime.md:123 and connectors.md:56-59, so the substance is documented. The two facts that comment surfaced alongside it (#493's no-cloud-GitHub-route, #498's aiCliDrives: 0) were filed as their own issues and both are closed.

Recommend closing this as delivered. It is the cleanest outcome on the old-issue sweep: a docs ticket that named exactly what to write, and the writing happened, plus an ADR that did not exist when it was filed.

Verified: every file path and line number above, read on origin/main. Not verified: how the pages render on the published docs site — I read the source, not docs:build output.

[serge-ivo]

Delivered — all five acceptance criteria verified by audit on 2026-08-18: docs/coding-engines.md:8-26 carries the "Can I use tmux for coding?" comparison table, "unmetered" now appears in four docs where it previously appeared nowhere, platform-docs/browser-runtime.md:123 links back, and the "Coder is not tmux" statements at :121 are intact and unweakened.

AC4 did better than it asked: it wanted #249 referenced as an open decision, and #249 was instead decided — see docs/adr/0003-a-coder-engine-reports-its-own-turns.md. The docs point at the ADR as a settled decision rather than at a live question, which #249's own item 4 anticipated ("once it closes, that line should invert").