Repository navigation
[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 #433
Description
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 overstream-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— thecoding_sessions.tmux_sessioncolumn keeps its old name but stores an engine label.platform-docs/connectors.md:42— thetmuxconnector'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
resulteventheadless.tsreads. 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:
- "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.
- "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.mdto 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.mdlinks to the terminal-connector path, andbrowser-runtime.mdlinks 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).
Activity
serge-ivo commentedon Aug 10, 2026
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 tmuxhalf 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:
Here is what the platform reports for those two paths over the same 7 days (
usage_summary, range7d; every figure is tokens × list price, not a bill):agent_coder_repo(Repo Coder — engine spend lands here)cda75e28-…(the tmux Operator instance)By kind:
engine= 2,634,475,688 µ$ over 189 calls — 98.7% of the account's entire notional totalis 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:
total_cost_usdTwo 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
ghinside 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), soisAiCliis false andaiCliDrivesreads 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.
docs(coding): "can I use tmux for coding?" gets an answer, and it nam…
serge-ivo commentedon Aug 18, 2026
Delivered. All five acceptance criteria are met on
main— recommend closingVerified 2026-08-18 against
origin/main@6ceec4f. Every item this issue asked for exists, and one of them turned into an ADR.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 attachand which agentsdocs/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$0there means not measured, not free."coding-engines.mdlinks to the terminal-connector path, andbrowser-runtime.mdlinks backbrowser-runtime.md:123links to bothdocs/coding-engines.md→ "Two ways to drive a CLI" and ADR 0003;coding-engines.md:28-34links to the ADRbrowser-runtime.md:121is intact verbatim; the new paragraph is additive at:123The 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: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:123andconnectors.md:56-59, so the substance is documented. The two facts that comment surfaced alongside it (#493's no-cloud-GitHub-route, #498'saiCliDrives: 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, notdocs:buildoutput.serge-ivo commentedon Aug 18, 2026
Delivered — all five acceptance criteria verified by audit on 2026-08-18:
docs/coding-engines.md:8-26carries 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:123links back, and the "Coder is not tmux" statements at:121are 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").