Sessions¶
New to tclaude?
Start with the Learn path. This page covers sessions from the command line.
A session is a live tmux instance running a coding harness (or a plain
shell). tclaude launches the harness inside its own tmux server (-L
tclaude), tracks the session's status through harness hooks, and lets you
detach, reattach, watch, and kill sessions from anywhere. The durable
transcript behind a session is a conversation — it
outlives the tmux process and stays resumable after the session exits.
Launching a session¶
Bare tclaude starts a new coding session in the current directory. It takes
the same flags as the underlying tclaude session new:
# New session in the current directory
tclaude
# Pick the harness explicitly
tclaude --harness codex
tclaude session new --harness opencode
# In another directory, with a label
tclaude session new -C /path/to/project --label review
# Start detached (don't attach)
tclaude -d
--harness accepts claude, codex, opencode, copilot, gemini, pi,
and shell.
When unset, the harness (and model/effort) come from the global default spawn
profile (dashboard, or tclaude agent profiles default set); explicit
--harness, --model, or --effort flags win per field. When the profile
targets the launch's harness, its launch posture applies too: sandbox mode,
sandbox implementation, approval, AskUserQuestion timeout, auto-compact
window, context-window cap, auto-review, trust-dir, remote control, auto
memory, peer messaging, context features and fast mode. Every field yields to
an explicit flag. The Copilot API and Codex app-server drives exist only under
agentd and are not taken from the profile. Without a global
profile, tclaude picks an installed harness from PATH, preferring Claude
Code. Per-harness knobs — models, effort, sandbox and approval flags — are
covered in Harnesses.
Sessions attach immediately by default; detach with Ctrl+B D. Useful launch
flags beyond the basics:
-d/--detachedstarts the session without attaching.--trust-dirpre-trusts the launch directory so a detached pane doesn't freeze on the harness's trust-folder dialog. It edits that harness's own config (Claude Code's~/.claude/.claude.json, Codex's~/.codex/config.toml, Copilot's trusted-folders list, Gemini's~/.gemini/trustedFolders.json, pi's~/.pi/agent/trust.json), so it is opt-in. Applies to Claude Code, Codex, Copilot, Gemini CLI, and pi.-w/--wait-for-rate-limitwaits for the 5-hour and 7-day rate-limit windows to reset before starting — handy for queueing a session to launch when quota returns.-r/--resume <conv-id>relaunches an existing conversation (see resume posture below). It also takes the name or agent ID fromtclaude agent ls.--resume-lastrelaunches the newest conversation in the current directory, skipping retired and archived ones. Claude Code only.tclaude -- --continuedoes the same, andtclaude -- --resume <id>is the same as-r <id>. A baretclaude -- --resumeopens Claude Code's own picker. These launches stay out of automatic group joins.- Resuming a retired conversation by name reinstates it, also from the picker.
Its old groups and permissions don't come back. It refuses when the directory
is gone, or when an agent runs it.
--resume-lastnever picks one. -l/--labelnames the tmux session;-n/--namesets the display name (for Claude Code it becomes the conversation title).
Group auto-join on launch¶
A fresh terminal launch checks whether an active agent group's configured
default directory exactly matches the launch directory (both normalized and
symlink-resolved). If one does, tclaude spawns through the agentd daemon
into that group — with agent identity, permissions, and messaging — and
attaches. Setting a group's default directory in the dashboard makes this the
whole workflow:
Controls:
--auto-join-group— the directory matching described above. Default on; config keysession.auto_join_group(tclaude config getshows it,tclaude config set session.auto_join_group falseturns it off).--auto-join-or-create-group— additionally creates a group when nothing matches, named after the directory basename (repo, thenrepo-2, …). Default off.-j/--join-group <name>— join a named group explicitly (daemon required). The root command then accepts the daemon spawn controls:--profile,--name,--role,--descr,--owner,--initial-message/--file,--task,--worktree,--sandbox-profile, and friends. See Spawning.--no-daemon— solo session: skip group discovery and agent features entirely. It is also the required opt-in for non-interactive launches to fall back to a solo session whenagentdis down (interactive launches get an offer to continue solo instead).
Resume, managed daemon launches, and --shell never do directory discovery.
Some launch flags have no counterpart on a group spawn and keep a launch
solo: -l/--label, --session-id, --permission-profile,
-w/--wait-for-rate-limit, -g/--global, --send-keys. When the directory
has a group, tclaude says so instead of skipping it quietly:
--label keeps this session solo, so it won't join group "myrepo". To join with a custom name, use -n NAME instead of --label; to stay solo, pass --auto-join-group=false.
A group spawn has no tmux label of its own (agentd picks it), so -n NAME
is the way to name a joined agent; with config agent.spawn_label_from_name
on, the name also becomes its tmux session name.
A flag is never dropped without a word. A group-only flag (-i, --file,
--sandbox-profile, --profile, --worktree, --role, …) on a launch that
ends up solo is refused, with an error naming what kept it solo (that
includes --resume and --shell, which never join). A solo-only flag with
-j/--join-group is refused the same way. An explicit --auto-join-group
(or --auto-join-or-create-group) next to a solo-only flag is refused as a
contradiction.
--initial-prompt works on both kinds of launch. Solo, it is the harness's
own first-turn prompt. When the launch joins a group it becomes the agent's
startup brief, delivered with its welcome, exactly like -i and the
dashboard spawn dialog's initial message; pass only one of the two.
A resume keeps its recorded posture¶
tclaude session new --resume <id> (and tclaude conv resume, watch-mode
resume, and the daemon's resume/clone/reincarnate paths) relaunch a
conversation the way it was recorded, not the way a fresh session would
start. Every recorded posture flag — --sandbox, --ask-for-approval,
--auto-review, --tools, --ask-user-question-timeout,
--remote-control, --auto-memory, --context-features,
--auto-compact-window, --copilot-api, --codex-app-server — is carried
over from the record unless you pass that flag yourself. Passing it wins,
even when you pass the default value.
Because a resume can apply a posture you did not type, the carried flags are echoed on stderr:
Resuming with this conversation's recorded launch posture (--sandbox
--auto-compact-window). Pass a flag explicitly to override it.
A recorded value the relaunch cannot honour — a Claude-only posture on a
Codex resume, for example — is dropped rather than failing the resume. When
the drop leaves the launch less confined than the record (--sandbox,
--ask-for-approval), it is warned about on stderr rather than only logged.
A posture field the conversation never recorded (a conversation started
outside tclaude, or before that field was recorded) falls back to the global
default spawn profile, as on a fresh launch — explicit flag, then recorded
posture, then profile. A field recorded as "nothing pinned" is still the
conversation's own decision and is not refilled; very old conversations whose
posture lives only in the legacy session row cannot tell "nothing pinned" from
unknown, so their blank fields take the profile. Sandbox mode, sandbox
implementation and --permission-profile count as one decision: if any of
them is passed or recorded, the profile supplies none of them. The profile's
harness, model and effort never apply to a resume.
Model and effort are not on the carried list: the harness itself remembers which model a conversation runs on.
session new --resume needs --harness for non-Claude conversations;
tclaude conv resume <id> looks the harness up from the conversation index
and is usually what you want. See Conversations.
Shell sessions¶
Direct --shell (or session new --harness shell) uses the lightweight shell
session path and starts your $SHELL in managed tmux, so you get the same
detach/reattach, session ls visibility, and kill handling for a plain
terminal:
Shell sessions are ephemeral: no conversation, no hooks, none of the
model/sandbox/approval machinery. Besides selecting this path with --shell or
--harness shell, only -C/--dir, --label, and -d/--detached apply; any
other session new flag errors out. This direct path bypasses global default
spawn-profile resolution and does not accept model or effort settings. Its
status is running while the tmux session is alive and exited afterwards.
agent spawn --harness shell is the registered managed pseudo-harness form.
It adds agent identity, group enrollment, worktrees, profiles, environment,
and tclaude-layer sandbox support. Its inbox remains durable but messages are
never typed into the command interpreter; clone and reincarnate are unsupported.
Listing, attaching, and status¶
tclaude session ls # list active sessions
tclaude session ls -a # include exited ones
tclaude session ls -j # JSON
tclaude session attach <id> # reattach (Ctrl+B D detaches)
tclaude session kill <id> # kill one; --all, --idle also exist
tclaude session focus <id> # focus (or open) the session's terminal window
session ls supports --show/--hide <status> filters and -s/--sort
with --asc/--desc. Statuses, reported through the harness's hooks:
| Status | Meaning |
|---|---|
idle |
The harness is waiting for input |
working |
The harness is processing |
running |
A shell session is alive (no finer status) |
awaiting_permission |
Needs a permission approval |
awaiting_input |
The harness is asking a question |
error |
The last turn ended in an error |
exited |
The session has ended |
session goto next|prev cycles between alive attached sessions from inside
one, and session prune clears exited session state (--max-age 7d,
--dry-run).
Watch mode¶
tclaude session watch (alias for session ls -w; bare tclaude session
opens the same viewer) is an interactive table of sessions:

Watch mode: every session across harnesses, with live working/idle/blocked status and what each agent is really running
↑/↓(orj/k) navigate;Enterattaches./searches;Escclears.x/Delkills the selected session (with confirmation).fopens the status filter menu;1–5pick a sort column (press again to toggle direction).nopens a new-session prompt; its harness field cycles through the coding harnesses andshell.ddetaches clients,cchooses columns,rrefreshes, andqquits.h/?shows help.
Labels and names¶
The tmux session name is the first 8 characters of the session id, or your
--label verbatim (up to 32 characters from a restricted set; anything else is
rejected, not cleaned up). Setting session.tmux_name_style to "dir" in
~/.tclaude/data/config.json names unlabelled sessions after the working
directory's basename instead (sanitized, capped at 32 characters,
disambiguated with -2, -3, … suffixes).
A launch that reaches agentd is auto-enrolled as an agent and gets a
deterministic display name such as 20260728-1017-f3e10b1d (launch
timestamp plus a stable agent-id suffix). A solo launch — --no-daemon, or
no daemon running — stays a plain session with no agent identity, mail, or
permissions; it can be promoted later. The opt-in session.auto_name_from_prompt config setting
(default false, since it costs a model call) instead infers a short name from
the session's first prompt. An explicit rename always wins.
Claude Code session machinery¶
Three Claude-Code-specific behaviors ride along with sessions:
- Pre-compact guard — the
pre_compact_guardconfig block installs aPreCompacthook that blocks Claude Code's automatic compaction until used context passes a per-window-size floor. Fail-open: if the guard is off or the context snapshot is missing, compaction proceeds. It only ever delays an early compaction, never forces one. - Resume-from-summary suppression — Claude Code's interactive "resume
from summary" chooser would hang a scripted, send-keys-driven resume.
tclaude setup --install-resume-threshold-overrideconfiguresclaude_resume.threshold_minutes/token_thresholdso the chooser never appears for tclaude-spawned panes; your manualclauderuns are untouched. - Transcript retention — Claude Code deletes transcripts inactive longer
than its
cleanupPeriodDayssetting (30 days by default). Setclaude_cleanup_period_daysin tclaude's config to keep conversations resumable longer; tclaude syncs the value into~/.claude/settings.jsonon session start.
Direct tmux access¶
Everything runs in a dedicated tmux server, so plain tmux works too:
tmux -L tclaude ls also shows __tclaude-control while agentd runs and any
tclaude session exists. That is agentd's tmux control-mode client (see below);
tclaude hides it everywhere it lists sessions. Don't attach to it.
Control mode¶
agentd sends its tmux queries and commands (session liveness, pane state,
options, hooks, kills, keystrokes) over one long-lived tmux -C control-mode
connection instead of starting a tmux process for each one. Some commands still
start a tmux process:
- A command with no explicit target, because over control mode it would act on the control client's own session.
new-session, because it takes the caller's environment and directory.kill-serverand key bindings.- A query whose answer contains text a program in a pane can set (screen
captures, the pane title, the current directory). A reply in control mode is
framed only by marker lines, so text like that could be made to look like the
end of the reply. Terminals you attach are ordinary tmux clients,
as before, and short-lived
tclaudecommands still run tmux directly. The connection attaches to the hidden__tclaude-controlsession. It never starts a tmux server: it connects only after a tclaude session exists, and it leaves once its own session is the last one, so the server still exits when empty. Akill-serverends it, and it does not bring the server back. When the connection is down or a reply can't be read, a query falls back to its own tmux process, as before. A command that changes something (a kill, keystrokes) is not repeated if the connection drops after it was sent, because it may already have run; the caller sees the error instead.
Diagnostics › Doctor shows which path is in use (tmux control mode is
connected, idle, or can't connect, with the reason). State changes are logged
at INFO with module=tmuxctl. To turn control mode off, set
"tmux": {"control_mode": false} in the config or TCLAUDE_TMUX_CONTROL_MODE=0
in agentd's environment (the variable wins), then restart agentd.
For scrollback, either enable tmux mouse mode (set -g mouse on) or disable
the alternate screen to keep your terminal's native scrollbar
(set -ga terminal-overrides ',*256color*:smcup@:rmcup@') — one or the
other, not both.
Labelled links¶
Attaching from a terminal makes the labelled links a harness prints (visible
text with a hidden address, OSC 8) open with the terminal's own link gesture,
usually Ctrl-click. tclaude asks tmux for this per client on tmux 3.4 or newer
when TERM matches xterm*, alacritty*, foot*, wezterm*, ghostty*,
tmux*, or screen*. A client that is already attached keeps what it had, so
detach and attach again after upgrading. A plain tmux -L tclaude attach does
not go through tclaude; add -T hyperlinks before attach to get the same.