Skip to content

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/--detached starts the session without attaching.
  • --trust-dir pre-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-limit waits 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 from tclaude agent ls.
  • --resume-last relaunches the newest conversation in the current directory, skipping retired and archived ones. Claude Code only. tclaude -- --continue does the same, and tclaude -- --resume <id> is the same as -r <id>. A bare tclaude -- --resume opens 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-last never picks one.
  • -l/--label names the tmux session; -n/--name sets 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:

cd /path/to/project
tclaude          # joins the project's group automatically

Controls:

  • --auto-join-group — the directory matching described above. Default on; config key session.auto_join_group (tclaude config get shows it, tclaude config set session.auto_join_group false turns it off).
  • --auto-join-or-create-group — additionally creates a group when nothing matches, named after the directory basename (repo, then repo-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 when agentd is 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:

tclaude --shell
tclaude session new --shell -C /path/to/project --label scratch

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

Watch mode: every session across harnesses, with live working/idle/blocked status and what each agent is really running

  • ↑/↓ (or j/k) navigate; Enter attaches.
  • / searches; Esc clears.
  • x/Del kills the selected session (with confirmation).
  • f opens the status filter menu; 1–5 pick a sort column (press again to toggle direction).
  • n opens a new-session prompt; its harness field cycles through the coding harnesses and shell.
  • d detaches clients, c chooses columns, r refreshes, and q quits.
  • 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_guard config block installs a PreCompact hook 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-override configures claude_resume.threshold_minutes / token_threshold so the chooser never appears for tclaude-spawned panes; your manual claude runs are untouched.
  • Transcript retention — Claude Code deletes transcripts inactive longer than its cleanupPeriodDays setting (30 days by default). Set claude_cleanup_period_days in tclaude's config to keep conversations resumable longer; tclaude syncs the value into ~/.claude/settings.json on session start.

Direct tmux access

Everything runs in a dedicated tmux server, so plain tmux works too:

tmux -L tclaude ls              # list tclaude sessions
tmux -L tclaude attach -t abc1  # manual attach

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-server and 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 tclaude commands still run tmux directly. The connection attaches to the hidden __tclaude-control session. 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. A kill-server ends 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.

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.