Harnesses¶
A harness is the vendor coding CLI that actually runs the model inside a
tclaude-managed tmux pane. tclaude is harness-agnostic: sessions,
conversations, ask, agent groups, lifecycle, and the dashboard all work
across every harness, and a group can freely mix them.
Six coding harnesses and one shell pseudo-harness are supported:
--harness |
Harness | Binary in the pane |
|---|---|---|
claude (default) |
Claude Code | claude |
codex |
OpenAI Codex CLI | codex |
opencode |
OpenCode | managed opencode serve + an attach client |
copilot |
GitHub Copilot CLI | copilot |
gemini |
Google Gemini CLI (beta) | gemini |
pi |
pi (beta) | pi |
shell |
ordinary shell (no model) | $SHELL or /bin/sh |
tclaude owns everything around the pane — the tmux session, status tracking, the conversation index, groups and messaging, the dashboard — while each harness contributes only what is genuinely harness-specific: how to launch it, where it stores conversations, and which in-pane commands it understands.
Shell has two launch forms
session new --shell (and the equivalent direct --harness shell form)
starts the lightweight standalone shell session described under
Sessions. agent spawn --harness shell
instead uses the managed agent pipeline: group enrollment, worktrees,
spawn profiles, and tclaude's OS sandbox are available, but model,
reasoning, hooks, and harness-native sandbox options are not.
How capabilities work¶
The harnesses are not equally capable, and tclaude does not pretend they are. Each harness declares a set of focused capability contracts — can it be asked a one-shot question, does it have a conversation store, a rename path, a sandbox catalog, an approval catalog, hooks, and so on. Every feature gates on the declared contract, not on the harness name:
- An absent capability is an honest refusal. Asking a harness for something it does not support produces a clear error or a graceful degradation with a message — never a silent no-op, and never a fake success.
- Unknown names fail closed. An unrecognized
--harnessvalue is an error naming the valid set; it never silently falls back to Claude Code. - Degradation is per-feature, not per-harness. Codex has no in-pane
/renamecommand, so renames go through its title store instead; OpenCode has no hooks, so its live status comes from its managed server instead. The rest of the surface is unaffected.
The capability matrix below is the user-level summary of those contracts. When a cell says no, the corresponding command tells you so too.
Choosing a harness¶
Every launch surface (tclaude, tclaude session new, tclaude agent spawn)
takes --harness. When the flag is omitted, resolution is:
- Explicit flag — always wins.
- Global default spawn profile — set from the dashboard or
tclaude agent profiles default set; its harness/model/effort apply to fresh terminal launches, each field overridable per launch. A profile for the launch's harness also supplies its launch posture (sandbox, sandbox implementation, approval, and the other per-launch knobs; see Sessions). - First installed harness — Claude Code is checked first; otherwise the
registry is walked in sorted order (codex, copilot, gemini, opencode, pi) and the first
harness whose binary is on
PATHwins. With nothing installed the launch reports the missingclaudeexecutable.
Agent and group spawns resolve through the fuller spawn-profile precedence described in Spawning and lifecycle.
tclaude session new --harness codex
tclaude agent spawn crew --name worker --harness opencode
tclaude session new --harness copilot --model gpt-5.4
tclaude agent spawn crew --non-interactive --harness shell \
--initial-message 'go test ./...'
Persistence and resume posture¶
The harness is persisted per conversation. conv resume, rename, stop,
compact, reincarnate, and clone all look up the recorded harness
automatically; you never re-specify it. (The lower-level
session new --resume is the exception: it searches one harness's store, so
pass --harness there or use conv resume.)
A resume also replays the recorded launch posture: every posture flag you
do not pass explicitly (--sandbox, --sandbox-impl, --ask-for-approval,
tool governance, timeouts, drives, and the rest) is refilled from the
conversation's recorded launch, and the carried flags are echoed so you can
see them. A recorded value the resuming harness cannot honor is dropped with a
warning. Model and effort are remembered by the harness itself.
Capability matrix¶
✅ yes · ⚠️ partial / with caveats · ❌ no
| Capability | Claude Code | Codex CLI | OpenCode | Copilot CLI | Gemini CLI | pi | Shell |
|---|---|---|---|---|---|---|---|
Federated model gateway (--model-proxy) |
Yes, ordinary workers | Yes, TUI and app-server | No: provider isolation | Yes, HTTP Responses BYOK | No: native Gemini dialect | No: not yet bound | No |
| Sessions: spawn / resume | ✅ | ✅ | ✅ managed server + attach | ✅ | ✅ | ✅ | ✅ spawn only |
One-shot ask |
✅ live-streamed | ✅ buffered | ✅ buffered | ✅ buffered | ✅ buffered | ✅ live-streamed | ❌ |
| Portable agent-bundle history | ✅ JSONL | ✅ rollout JSONL | ✅ native export/import | ✅ native event log | ✅ native chat JSONL | ✅ native session JSONL | ❌ |
| Clone with conversation copy | ✅ native copy | ✅ rollout JSONL; app-server forks the thread | ✅ native export/import | ✅ native event log | ✅ native chat JSONL | ✅ native session JSONL | ❌ |
| Cross-harness history translation | ✅ | ✅ | ✅ | ✅ images by path | ✅ | ✅ | ❌ |
| Conversation list & search | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| Agent groups & messaging | ✅ | ✅ | ✅ | ⚠️ one launch topology only | ⚠️ send-keys only, not yet exercised against a live pane | ⚠️ send-keys; experimental --pi-drive |
⚠️ durable inbox only; never injected into the shell |
| Automatic prompt-based name refinement | ✅ contained one-shot | ✅ read-only one-shot | ❌ generated name retained; no tested unattended sandbox posture | ❌ generated name retained; no tested unattended sandbox posture | ❌ generated name retained; no tested unattended sandbox posture | ✅ read-only-tools ephemeral one-shot | ❌ no model |
| Standing-order native hook selectors | ✅ inline or next-turn | ✅ inline or next-turn | ✅ observed events, next-turn | ⚠️ installed baseline only, next-turn | ⚠️ installed baseline only, next-turn | ⚠️ next-turn | ❌ no hook source |
| Account quota spawn gate | ✅ cached quota windows | ✅ cached quota windows | ❌ no single account quota | ✅ cached quota windows | ❌ account quota is not captured in session logs | ❌ no single account quota | ❌ no model |
| Rename | ✅ in-pane /rename |
✅ title store | ✅ server API | ✅ in-pane /rename |
✅ tclaude title overlay | ✅ in-pane /name |
❌ |
| Compact / reincarnate | ✅ | ✅ | ✅ (server API, no keystrokes) | ✅ | ✅ in-pane /compress |
✅ in-pane /compact; pinned auto-compact window |
❌ |
| Startup-context re-injection after compaction | ✅ hooks | ✅ hooks | ✅ server events | ✅ session event log | ❌ no post-compaction event | ✅ extension events | ❌ |
| Séance (ask posture) replay | ✅ | ✅ | ❌ | ❌ | ✅ fork of a copy | ✅ continues a copy | ❌ |
| Remote control | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Status line | ✅ command-backed | ⚠️ curated built-in items | ⚠️ OpenCode's own TUI status | ❌ | ❌ | ⚠️ extension footer segment: tclaude's pinned-window context meter | ❌ |
| Task runner | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Native sandbox-profile path rules / reopen beneath deny | ✅ sandbox on; caveats | ✅ managed Linux profile + probe | ⚠️ soft tool permissions only | ❌ native command sandbox does not cover file tools; use tclaude-layer | ❌ fixed native sandbox profile; use tclaude-layer | ❌ no native sandbox | ❌ use tclaude-layer |
| Global OS filesystem rules in profile editor | ✅ settings + managed baseline | ✅ managed baseline | ❌ native config is soft tool control | ❌ native policy only confines commands | ❌ tools.sandbox selects posture, not path rules | ❌ no native policy | ❌ no native policy |
| Activated proxy destination filtering | ✅ Linux/macOS | ✅ Linux/macOS | ✅ Linux/macOS | ❌ private routed posture does not enforce destination rules | ⚠️ Linux only; no Darwin carriage smoke | ⚠️ Linux only; no Darwin carriage smoke | ❌ no shell carriage smoke |
| Built-in OS sandbox | ✅ | ✅ | ❌ command filter only | ❌ asserted off | ⚠️ macOS only (seatbelt) |
❌ | ❌ |
| tclaude’s built-in sandbox | ✅ | ✅ | ✅ (wraps the server) | ✅ | ✅ | ✅ the only boundary | ✅ |
| Usage / cost reporting | ✅ real + what-if cost | ✅ what-if cost | ✅ native pricing what-if | ⚠️ Copilot AIU units, derived virtual USD | ✅ what-if cost; real spend on API-key or Vertex | ✅ pi's catalog price; what-if under a subscription login | ❌ |
Bundled skills via setup --install-agent-skills |
✅ ~/.claude/skills |
✅ shared ~/.agents/skills + $CODEX_HOME/skills |
✅ shared roots; external skills must be enabled | ✅ shared ~/.agents/skills |
✅ shared ~/.agents/skills |
✅ shared ~/.agents/skills |
❌ |
Hooks via tclaude setup |
✅ | ✅ | ❌ (server liveness instead) | ✅ | ✅ settings.json hooks | — per-launch extension, no setup | ❌ |
Directory pre-trust (--trust-dir) |
✅ | ✅ | — no trust dialog | ✅ | ✅ | ✅ | — |
Tool governance (--tools) |
❌ | ❌ | ✅ | ❌ | ❌ | ⚠️ approval posture picks the tool set | ❌ |
| Fast mode | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| API/RPC drive | — n/a | ⚠️ experimental --codex-app-server |
✅ inherent | ⚠️ experimental --copilot-api |
— | ⚠️ experimental --pi-drive |
— n/a |
Cross-harness history translation¶
An agent that changes harness (cross-harness morph) keeps its conversation: tclaude decodes the source harness's native history into a neutral transcript and installs it as a native conversation of the target harness, which then resumes it like any of its own. The install goes through the same import path as portable agent-bundle history, so the target's identity reminting, cwd remapping and indexing apply unchanged. The source history is only read.
Only the effective model context is carried: the active branch, from the last compaction on (the compaction summary stands in for what came before), without scaffolding the target harness injects itself (system and developer prompts, environment and instruction-file blocks, hook context). Translation is explicit about what does not map 1:1:
- Reasoning never crosses vendors. Signatures and encrypted reasoning are only valid for the provider that issued them.
- Tool calls and results are history, not executable calls. Older than the
last three human turns, they become one-line stubs (name, short arguments,
status and output preview) pointing to numbered entries in the saved full
transcript. Recent results retain up to 4 KiB each, or a smaller configured
agent.morph.tool_result_clip_bytescap. Without a saved transcript, existing clipping remains (default 16384 bytes). Attachments keep their normal handling. The CLI and launch preview show approximate source and carried token counts; these are estimates, not a provider tokenizer. The notice tells the successor to read full tool output only when needed and avoid repeating skills or environment checks unless something looks wrong. - Images stay inline where the target's user turns accept them. Copilot references them by a saved path instead.
- Context budget. The carried history fills at most
agent.morph.history_budget_percent(default 60) of the target model's context window. The preview shows the window, its source, and the history budget. It uses fresh local Codex/OpenCode model metadata, Copilot prompt limits, or the known Claude/Gemini model limits; it does not fetch metadata. Unknown or automatic models show unknown model, assumed 32k.agent morph --history-window-tokens Noverrides that assumption (1024 to 10000000); a verified smaller destination limit still wins. A Copilot profile's explicit context limit and a Claude auto-compact ceiling also bound the budget. This option persists when the morph waits for idle and changes only the carried-history budget, not the model's native capacity. The estimate charges three tokens per four UTF-8 bytes plus message/media overhead. Calibration covers prose, code, logs, JSON, Unicode and identifiers; it is a conservative safety estimate, not a provider billing count.
Local near-budget resume verification is opt-in, skips by default, and
spends one cheap Codex model call:
TCLAUDE_MORPH_RESUME_SMOKE=1 TCLAUDE_MORPH_NEAR_BUDGET=1 scripts/test.sh ./pkg/claude/agentd/ -run TestMorphResumeRealCLI -v -count=1.
Do not enable it in CI or copy provider credentials to CI.
The original task and latest user instructions stay pinned,
followed by the newest complete turns that fit. A giant pinned turn stays
in the full transcript with a clear read-before-continuing pointer instead
of overflowing the native window. The preview shows kept/dropped entry
percentages and explains the selection. A cut of at least 10% warns; at
25% the operator must confirm --confirm-history-loss (or the launch
dialog checkbox). The source then writes one summary of the earlier work,
carried with the pins and whatever native tail fits. No model call runs
behind the operator's back. The dialog shows the source name, deadline
and cancellation while waiting, and restores that state when reopened.
Timeout, cancellation or a refusal leave the source unchanged. During a
provider outage, an explicit --proceed-without-summary or the dialog's
loss-confirmation checkbox instead carries readable history with its full
transcript pointer. The destination is warned that earlier context may be
missing. The fallback never runs without that confirmation. The budget is checked again before applying the morph.
- Carry-over overrides. When the operator knows better than the detected
limits, the morph can be told how to carry the history (CLI flags, the
history_* and target_window_tokens request fields, and the dashboard's
History carry-over section):
- --target-window N states the destination's window. It replaces the
detected window instead of being capped by it; the preview shows both.
When a Claude profile pins an auto-compact window above a model without
[1m], the detected window says that the pin has no effect.
- --history-budget auto|all|N sets how much is carried: 60% of the window,
a token count, or all: every turn, and every tool record whole rather
than stubbed (unless --keep names a share). A single over-long tool
record is still clipped, with a pointer to its full text.
- --keep tool-output=25,tool-calls=50,chat=100 keeps that share of each
category whole, newest first; the older rest becomes one-line stubs
pointing at numbered entries in the full transcript. A category not named
keeps the automatic rule (tool records of the last three turns, all chat).
Under a share, a record whose stub would be larger stays whole. The
original task and the latest instructions are never shortened.
Reasoning and harness-injected context have no share: they are never
carried.
- --cut-first tool-output|tool-calls|chat makes that category give way
before whole turns are omitted: its share becomes the largest with which
the rest fits the budget. The default, oldest, omits the oldest turns.
- --history summary always asks the source for a summary first;
--history truncate cuts without one, whatever the size of the cut.
The preview reports each category's estimated tokens before and after, and
warns (never blocks) when the carried history exceeds the window or leaves
less than the usual headroom. A carry-all morph is delivered natively even
then. The carried notice tells the receiving agent what the conversion
shortened or omitted, per category, with rough token counts and the path of
the full transcript.
- Resets and rewinds carry only the active native history. Gemini compression
snapshots are labelled as summaries; clear/checkpoint, OpenCode revert and
Codex/Copilot rewind boundaries are applied before carrying turns. Removed
history is counted in the loss report. A Copilot truncation event has only
counts, not the identities of retained messages, so it requires the existing
agent-written handoff path instead of guessing which history survived.
- Codex compaction summaries are encrypted in current Codex releases. A
Cross-harness morph asks the source for a handoff of its remembered context
and carries that alongside the readable tail. The existing pending dialog
shows the source and deadline; timeout or cancellation leaves it unchanged.
During a provider outage, explicitly confirm --proceed-without-summary or
the dashboard loss checkbox to continue with readable history, the saved
transcript pointer and a clear warning about the unreadable summary.
The neutral transcript and loss report are the context of the Portable Agent Format, which specifies their file form.
Every translation produces a loss report (counts and categories only, never
transcript content) and keeps the full, unclipped transcript as a Markdown
file beside it. Clipping and omission markers point the target agent at that
file. The same full transcript is also kept as transcript.jsonl, a PAF
context file. Inline images and documents it references are the translation's
own saved attachments, or, for those the translation dropped, files under
context-media/. This copy is best effort: if it cannot be written, the
translation goes ahead without it.
If the translated history cannot be installed natively, the target instead
gets a native conversation of one turn that points the agent at the history
saved as files: briefing.md (the budgeted history as plain text) and the full
transcript. A third rung, the handoff, replaces the history with a handoff the
agent writes for its successor before the switch. It is used on request, and
automatically when the source history cannot be read. The loss report records
which rung was used.
A morph keeps these files in a per-agent directory under
~/.tclaude/api/morph/. The agent must be able to read them, and tclaude's
private data directory is walled off from a sandboxed agent. Under tclaude's
sandbox the parent is hidden and each launch reopens only its own agent's
directory, the same way spawn attachments are granted.
The rest of this page walks each harness: setup, maturity, models, sandbox and approval knobs, and the extras only that harness has.
Claude Code¶
The default harness and the reference implementation of every contract. First-class throughout.
Setup. tclaude setup installs the hooks that power live status tracking
into ~/.claude/settings.json, and offers the command-backed
status line. Hooks are idempotent; re-running
setup repairs them.
Models and effort. --model accepts the aliases fable, opus,
sonnet, haiku, opusplan — fable, opus, and sonnet also take the
[1m] long-context suffix, e.g. sonnet[1m] — or any full claude-* model
ID. --effort is
low/medium/high/xhigh/max. Empty means "let the harness decide".
Haiku 5.5 uses the pinned API ID claude-haiku-5-5 and a native 1M-token
window; no [1m] suffix is needed. With Claude Code v2.1.293 or later,
haiku resolves to 5.5 on the Anthropic API and to 4.5 on some other
providers. tclaude forwards the alias unchanged and displays the model,
window, and cost Claude Code reports. See Claude Code model configuration.
Haiku 5.5's API rates increase for prompts over 100K tokens; OpenCode uses
its runtime provider catalog for these tiers, so its cost reporting requires
that catalog to include the model (tclaude supplies the rates when the
catalog has none; see OpenCode below). Copilot's claude-haiku-5.5
suggestion is prepared ahead of its pinned CLI catalog; Copilot determines
availability and reports cost in native usage credits.
Fable 5.2 (claude-fable-5-2, and claude-mythos-5-2 for verified
organizations) needs nothing special in Claude Code: the fable alias
resolves to whatever Claude Code ships, the full ID passes through unchanged,
and Claude Code reports its own cost. Where tclaude prices tokens itself (the
model gateway, and OpenCode's fallback below), both use Anthropic's published
5.2 rates. Copilot's claude-fable-5.2 suggestion is prepared ahead of its
pinned CLI catalog.
Sandbox. Claude Code's own OS sandbox is configured in settings.json,
not a launch flag, so tclaude's --sandbox delivers a per-session settings
override with three modes:
inherit(default) — no override; the agent runs under whatever yoursettings.jsonconfigures.on— forces the sandbox on for this session, with the agentd socket reachable and~/.tclaude/dataand~/.claude/sessionshidden.off— forces Claude Code's own sandbox off. Under--sandbox-impl tclaude-layerthis is what tclaude itself sets, because its own wall is enforcing — see Sandboxing for the two-axis model.
Approvals. The approval axis is Claude Code's permission mode
(--ask-for-approval, rendered as --permission-mode): inherit,
default, plan, acceptEdits, auto, dontAsk, bypassPermissions.
Daemon-spawned agents default to auto, where a supervisor model approves
safe actions and blocks unsafe ones — the most autonomous mode that keeps
guardrails, suited to a detached pane. A direct session new applies no
default; your own configuration rules.
Claude-only extras:
- Auto memory is off by default. tclaude launches Claude Code with
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1so agents sharing a checkout do not cross-pollute the per-project memory store. Opt back in per launch with--auto-memoryor a spawn profile'sauto_memory.CLAUDE.mdis unaffected. See memory-files for inspecting the store. - The agent view is off by default. tclaude launches Claude Code with
CLAUDE_CODE_DISABLE_AGENT_VIEW=1, so left arrow in a managed pane is a plain cursor key. The view forks a conversation into a background daemon outside tmux, where tclaude cannot track it, deliver messages to it, or attach to it, and quitting the view ends the pane. Opt back in per launch with--context-features agent-view=onif you accept that.tclaude task runandtclaude agent spawn --non-interactivehave no opt-in; the flag is rejected for the latter.clauderun outside tclaude is unaffected. - Cross-session messaging is off by default. Claude Code ships its own
agent-to-agent mesh (the
ListAgentsandSendMessagetools over a per-session socket). That is a second coordination channel with none of tclaude's group membership, permission slugs, or audit trail, so tclaude closes it and leavestclaude agent sendas the way agents coordinate. Opt back in per launch with--peer-messagingor a spawn profile'speer_messaging. In-harness subagents are unaffected either way — the deny namesListAgents, neverSendMessage. See Peer messaging. - Startup-context trimming (
--context-features) removes bundled skills, unused tool schemas, and system-prompt blocks from an agent's startup context, per spawn or per profile. Nothing is trimmed unless you ask. See Utilities. - Auto-compaction window (
--auto-compact-window) pins the token capacity Claude Code's auto-compaction (and tclaude's context meters) reason from — useful to make a long-lived agent on a 1M-window model compact while it is still sharp. See Utilities. - AskUserQuestion timeout (
--ask-user-question-timeoutinherit/never/60s/5m/10m) makes an unattended agent auto-continue instead of stalling forever on a clarifying question. - Remote control (
--remote-control, or toggled later) arms Claude Code's built-in Remote Access so the session is reachable from claude.ai/code and the Claude mobile app. Claude Code only. See Remote. The three profile toggles resolve the same way on every spawn path, trigger and process workers included; see Default resolution. - Background shells and monitors are tracked per task, so an agent waiting
on one shows
⚙+N/👁+Ninstead ofidlein the dashboard.
Relocated config, and what that means for claude mcp¶
Every tclaude-launched Claude pane runs with CLAUDE_CONFIG_DIR pinned to the
harness state root, so it reads ~/.claude/.claude.json — not the ambient
~/.claude.json that a bare claude in your terminal opens. That keeps
account, onboarding and per-project trust state inside the one directory every
sandbox posture keeps writable; without it a constructed-root launch cannot see
the top-level file and parks on the login wizard. The relocated file is copied
from the ambient one once, at the first tclaude Claude launch on the
machine, and the two evolve independently from then on.
Almost nothing in that file is configuration you maintain by hand — it is
account state, per-project records, caches and counters, all of which should
diverge per launch context. The settings you do edit (settings.json,
settings.local.json, plugins/) already live under ~/.claude/, the state
root both launch kinds share, so they need no special handling.
The one exception is MCP registrations, which Claude Code stores in the config
file rather than in settings — under mcpServers for --scope user, and under
projects.<dir>.mcpServers for --scope local, the default. So a bare
claude mcp add configures your ambient config only, and the server will not
appear in a tclaude pane's /mcp list. Plugin-provided servers still appear,
because plugin registration lives under the shared state root — which is why
the failure looks selective rather than total.
Set the config dir on any claude mcp command whose result you want tclaude
panes to see:
CLAUDE_CONFIG_DIR=~/.claude claude mcp add --transport http my-server http://localhost:4001/mcp/http
CLAUDE_CONFIG_DIR=~/.claude claude mcp list
CLAUDE_CONFIG_DIR=~/.claude claude mcp remove my-server
Panes read the config at launch, so restart or resume the session to pick up a change. To configure both your terminal and your agents, run the command twice — once with the prefix and once without.
If you have servers that predate this and want them carried over in bulk, merge
mcpServers from ~/.claude.json into ~/.claude/.claude.json by hand; there
is deliberately no automatic sync, so that tclaude never writes MCP entries
into a config file a running pane is concurrently updating.
Codex CLI¶
First-class: the common contracts — sessions, conversations, ask, groups, lifecycle, hooks, dashboard — are production paths for Codex.
Setup. A plain tclaude setup detects codex on PATH and offers to
install its hooks into ~/.codex/hooks.json (or run
tclaude setup --harness codex explicitly). The install is surgical and
idempotent, and it atomically trusts only the absolute-path tclaude hooks it
just installed — Codex requires command hooks to be trusted, and unrelated
user or repository hooks stay on Codex's normal review path. Trust fails
closed on Codex versions tclaude has not verified. Setup also curates Codex's
built-in status line items.
Models and effort. --model offers a suggestion list of current OpenAI
IDs and accepts any custom OpenAI ID; Claude slugs are rejected with a clear
error. --effort uses the same five levels as Claude Code, with max mapped
to xhigh for models without a max tier.
Sandbox. Codex has a real native OS sandbox, selected per launch:
tclaude-agent(daemon default) — not a raw Codex mode but a tclaude-managed permission profile (codex -p tclaude-agent-<launch>), givingworkspace-writecontainment plus an allow-listed agentd socket so the sandboxed agent can still runtclaude agent …, while~/.tclaude/datais denied. When launched inside a Git repo it also grants the minimal repository root needed to create and commit in sibling worktrees.workspace-write/read-only— raw confined Codex modes, passed through. No agentd-socket grant, so agents under these cannot reachtclaude agent.danger-full-access— Codex's sandbox off; also what--sandbox-impl tclaude-layersets, since tclaude’s sandbox then enforces.
Approvals. --ask-for-approval maps to Codex's policy set: never
(daemon default — an unattended pane must not deadlock on a prompt),
untrusted, on-failure (deprecated), on-request. A direct session new
injects no default and respects your config.toml. The -p /
--permission-profile flag runs the pane under a named Codex permission
profile (codex -p <name>) instead; it is mutually exclusive with
--sandbox.
Codex-only extras:
- Fast mode —
--fast-mode inherit|on|offtoggles Codex's fast mode at launch; it can also be flipped in-pane. --auto-review(experimental) — routes approval prompts to Codex's guardian subagent, which decides in your place, fail-closed. Off by default; the underlying Codex key is experimental. It has no effect under approval policynever, which creates no approval requests.- App-server drive (experimental) — by default tclaude drives Codex via
tmux send-keys.
--codex-app-server(or thecodex_app_serverprofile field, or the dashboard control) opts a spawn into Codex's authenticated app-server API instead: durable message delivery, rename, compaction, and interrupt as typed calls. Requires Codex CLI 0.147.0 or newer; an explicitly selected drive fails closed rather than silently falling back to send-keys. The drive carries over to resume, reincarnate, and clone;tclaude agent codex-app-server statusdiagnoses it, andtclaude agent resume <agent> --send-keysdurably rolls a stopped agent back. - Reincarnation guidance — Codex agents should normally run to full context and let Codex's native automatic compaction work, rather than reincarnating for context pressure (that pattern is for Claude Code).
OpenCode¶
Supported via a managed, server-authoritative path: agentd starts and
authenticates a per-session opencode serve, mints the conversation on the
server, supervises and reaps it, and the tmux pane is only an
opencode attach client. A bare session new --harness opencode without the
daemon is refused — the pane is never allowed to start its own server. Full
status/SSE mapping is intentionally capability-gated and still partial.
Setup. No hooks: tclaude setup has nothing to install for OpenCode.
Liveness and status come from the managed server's event stream.
Models. The catalog is fetched from OpenCode itself and cached with
background refresh, so it may briefly report empty rather than guess.
Cost comes from that catalog's rates. When the openai or anthropic
provider reports all-zero rates (a subscription sign-in) or no rates at all
(a model newer than the catalog), tclaude falls back to its own API rate
table and records the result as what-if cost.
Tool governance. OpenCode gets an axis no other harness has:
--tools allow|ask|deny applies one permission action uniformly to its
built-in bash, glob, grep, LSP, and skill tools. allow (default) runs
them without prompting; ask prompts (and can stall a detached agent);
deny blocks them. It is independent of the approval selector below and is
preserved across clone, resume, and reincarnate.
Sub-agents are off, unless you pick all. Under allow, ask and
deny, OpenCode's task tool, which hands work to a sub-agent such as
explore or general, is always denied, and OpenCode hides it, so the main
agent reads and searches files itself. The reason: those policies are a
per-session rule list that starts by denying everything and then allows what
the launch may do. When OpenCode (1.18.6) creates a sub-agent session it copies
only the parent's deny rules into it, so a sub-agent would get the deny-all and
none of the allows and could not read a single file.
--tools all allows every OpenCode tool, the ones tclaude has never
audited included: MCP and plugin tools, tools a later OpenCode adds, the
question tool, plan mode, and sub-agents. There is no deny-all baseline, so a
sub-agent works and has what the agent has. What tclaude still applies is only
what you chose, and each is an allow or a deny, which OpenCode does pass on to
sub-agents:
- the approval setting for edits and for leaving the worktree;
- a closed network for the web tools (they are allowed otherwise);
- the per-tool entries, written after
all:
| Entry | Default | Effect |
|---|---|---|
question=deny |
allowed | OpenCode's question tool waits for your answer; a detached agent that asks shows as needing you. |
plan=deny |
allowed | plan mode (plan_enter, plan_exit). |
env=allow |
denied | reading .env files. Denied by default because the usual "ask" cannot reach a sub-agent, and OpenCode's explore sub-agent would otherwise read them without asking. |
For example --tools all,question=deny,plan=deny. The spawn dialog and the
spawn-profile editor show these as checkboxes under Tool governance when it
is all, and profiles store the same value, so it echoes and relaunches like
the others. all is refused with approval ask (a sub-agent cannot inherit an
ask, so it would act without your OK) and with the access-control sandbox mode
(its path rules depend on the deny-all baseline); use --sandbox-impl
tclaude-layer or off, and approval deny or allow-tools.
Sandbox — read this caveat. OpenCode's access-control mode (the
--sandbox default) compiles tclaude's path and permission rules into
per-session OpenCode tool rules. It is a command filter, not OS
confinement: shell redirection, symlinks, and subprocess binaries bypass its
lexical command/path checks. Because it reads like a sandbox without confining
like one, every spawn surface warns when it is the only boundary. For a real
wall, use --sandbox-impl tclaude-layer, which puts tclaude's own OS sandbox
(bubblewrap on Linux, Seatbelt on macOS) around the tool-executing server.
The explicit off mode removes path scoping but keeps approval and tool
governance active.
Approvals. --ask-for-approval is a tclaude-compiled per-session
permission policy: deny (default — edits and web tools denied), ask
(a present human approves representable edits), allow-tools
(auto-accepts scoped edits and explicitly enabled web tools).
OpenCode under a filtered network¶
OpenCode reads its provider from its own config, and tclaude cannot read OpenCode's effective config for every provider. So, under a filtered network (an allow list, or default-allow with deny rules):
- tclaude checks the model endpoint only for one config shape: a
provider/modellaunch model and a profile environment entryOPENCODE_CONFIG_CONTENTthat defines exactly that one@ai-sdk/openai-compatibleprovider with a concreteoptions.baseURL,enabled_providersset to it, and the model whitelisted. The endpoint must then be covered by the network rules, or the launch is refused naming it. - Any other provider launches unchecked. That includes OpenCode's built-in providers, a provider set in your own OpenCode config, and no launch model. tclaude adds no model access. The launch notes say the endpoint was not checked, and why resolution stopped. If OpenCode then cannot reach its model (requests hang or fail inside OpenCode, not at launch), the network policy is blocking it.
- The fix is in the network policy: allow the provider's API host on port 443 in every tier that has an allow list (they intersect), remove the deny rule that matches it, or use network open. Find the host in your OpenCode provider config, or in OpenCode's documentation for a built-in provider.
tclaude agent sandbox-profiles plan -g <group> -f tclaude-layer/opencode
shows the composed network rules a launch in that group would get.
Other gaps, stated plainly: no séance replay for ask threads, no
directory-trust dialog (so nothing to pre-trust), no status line
installation, and no remote control.
Copilot CLI¶
An evidence-driven adapter: each capability was promoted only after being
proven against a pinned real binary (1.0.77/1.0.78), which is why the gaps
below are named rather than papered over. What it has today: spawn, resume,
model/effort, in-pane rename/compact, hooks, a cold conversation store,
ask, directory pre-trust, usage/context telemetry, and a measured approval
posture.
Setup. tclaude installs its hooks as a tclaude-owned drop-in file,
<COPILOT_HOME>/hooks/tclaude.json, merged by Copilot with your own hooks —
no trust step, no config edits. tclaude setup also offers enabling
Copilot's copy-on-select when the binary is present.
Models and effort. Copilot brokers models from several vendors
(claude-*, gpt-*, gemini-*, mai-*) and exposes no machine-readable
catalog, so tclaude's list is a suggestion list, not an allow-list: any
single bounded token is forwarded verbatim (case preserved, for BYOK IDs) and
Copilot does the authoritative validation. --effort accepts
none/minimal/low/medium/high/xhigh/max; Copilot's docs describe
max as an Anthropic-model tier, so pair it with a model that has it.
Sandbox. Copilot owns a real experimental OS sandbox (MXC), but it has no
per-launch lever tclaude can safely use, so tclaude's catalog is an
assertion, not a switch: inherit (default) leaves Copilot's own
configuration alone, and off — what --sandbox-impl tclaude-layer resolves
to — verifies the inner sandbox is not engaged and refuses the launch when
it cannot prove that (including when --experimental would let the pane
re-enable it mid-session). There is no on. The supported confined posture
is therefore tclaude’s sandbox with Copilot's sandbox asserted down.
Approvals. Three measured tokens:
allow-tools(default for daemon spawns) — renders--allow-all-tools --no-ask-userplus one--add-dirper directory the sandbox profile grants.inherit— no permission flags at all; Copilot's own defaults and your configuration decide.yolo— Copilot's widest posture; also opens the directory axis. Without--sandbox-impl tclaude-layerthis leaves the agent with no file boundary at all, and tclaude warns at spawn.
Folder trust is a separate gate no approval flag can clear: Copilot's trust
modal blocks before any provider contact, so an untrusted detached pane
never reaches its first turn. --trust-dir seeds the entry in
<COPILOT_HOME>/config.json ahead of launch.
Copilot-only specifics:
- API drive (experimental) — the default drive is tmux send-keys.
--copilot-api(or thecopilot_apiprofile field / dashboard checkbox) drivescopilot --ui-server's embedded JSON-RPC endpoint instead: message delivery, rename, and compaction as typed calls, plus live context and usage read over RPC rather than from the durable log. The endpoint is an unauthenticated host loopback listener, a pre-trusted launch directory is mandatory (an untrusted dir is refused, not parked), and soft exit deliberately stays on keystrokes. Off unless you ask. - Detached-topology restriction. Copilot agents are usable as detached
group agents in exactly one launch topology:
--sandbox-impl tclaude-layerwith sandbox modeoff— tclaude's wall enforcing, Copilot's own sandbox asserted down, so the launch has exactly one claimed boundary. Agents spawning any other spelling are refused withsandbox_restricted. Spawns started by a human are not restricted this way. - Usage in AI credits. Cost is carried in the nano-AI-credit units Copilot emits; the dashboard derives a virtual USD value from the fixed 1 credit = $0.01 gross subscription rate (labeled as derived, not billed). The dashboard also samples premium-request quota for metered plans.
- No status line, no remote control, no tool governance, no streaming
ask— each an honest absence, refused or degraded with a message.
Gemini CLI¶
Beta
Gemini CLI support is new and has seen far less real-world use than the other harnesses. Expect rough edges, especially in the interactive pane, and please report problems you hit.
The Gemini CLI adapter, pinned to 0.62.0, covers:
- Spawn and exact resume, with a pre-minted conversation id, so daemon spawns are enrolled before the pane starts.
- The launch briefing as Gemini's
-ifirst turn. - Model selection.
- Conversation listing and search.
- Buffered
askand séance. - Rename, in-pane compaction and soft exit.
- Live status through hooks, and directory pre-trust.
- Gemini's approval modes, and its own sandbox modes.
- tclaude's sandbox, with both Linux network engines and the separate filesystem root.
- Usage with a what-if cost.
It was written from the CLI's source without a Gemini account. CI runs the real pinned binary in two places: - Against a local mock model: session files, resume, the séance fork, hook firing, folder trust and every approval mode. - Behind the proxy network engine: its model egress.
What is not machine-checked is the interactive pane: typed lifecycle commands, dialogs, and how it reacts to keystrokes.
Models. --model offers Gemini's own aliases (auto, pro, flash,
flash-lite) and current concrete ids as suggestions; any other single
Gemini model token is forwarded and Gemini validates it. Claude and OpenAI
slugs are rejected with a clear error. Gemini CLI has no reasoning-effort
launch option, so --effort is refused rather than silently dropped.
Thinking budgets live only in settings files. The only settings paths a
launch can redirect are Gemini's system settings files, and Gemini ignores
those unless the file and its directories are owned by root. So tclaude
cannot set a budget for a single launch without editing your settings.
Lifecycle. Compaction types /compress; soft exit sends Escape and a
double Ctrl+C (Gemini quits on the second press inside a 3 s window), with
/quit as the typed form. Gemini has no rename command and no title of its
own, so rename writes a title into tclaude's conversation index, which the
conversation listing shows over Gemini's generated summary. Nothing is typed
into the pane.
Conversation ids. Every fresh Gemini launch is given its conversation id
up front (gemini --session-id), including a plain interactive
session new, so it is resumable and tracked from the first moment even
without hooks. A launch --name is kept in tclaude's conversation index,
since Gemini has nowhere to store one.
Conversations. tclaude reads Gemini's own chat files under
~/.gemini/tmp/<project>/chats/ (or $GEMINI_CLI_HOME/.gemini), replaying
the JSONL record stream the way the CLI does — rewinds, metadata updates and
legacy whole-file .json sessions included. A session counts as a
conversation exactly when Gemini's own --resume would offer it: it has real
content and is not a subagent session. Resume is scoped to the project
directory, as in the CLI.
Portable history. Gemini portable history preserves native chat messages, metadata updates and rewind records. Import remints session and message IDs, maps the receiver project, and resumes through Gemini’s own session store. Legacy JSON sessions are converted to JSONL. Settings, trust decisions, credentials and filesystem checkpoints do not travel.
Ask. tclaude ask, with a Gemini ask.profile, runs headless gemini --prompt and
returns the buffered answer. In headless mode Gemini denies any tool call
that would need approval. Live streaming is not supported.
Séance and non-interactive runs. A séance replays the predecessor's
recorded posture: its Gemini sandbox mode, its --approval-mode, and, for a
generation that ran under tclaude's sandbox, that sandbox again. Gemini has no
flag that keeps a headless --resume out of the conversation, so the turn
runs on a fork:
- tclaude copies the predecessor's session file and starts
gemini --session-file <copy>, which imports the copy into a new session.
- The predecessor's own file is only read.
- After the answer, tclaude deletes the copy and the new session Gemini wrote
for it.
--print-cmd shows the copy as <copy-of-…>. Non-interactive spawns use the
same posture replay.
Setup and live status. tclaude setup installs the tclaude callback
into the hooks section of ~/.gemini/settings.json (or
$GEMINI_CLI_HOME/.gemini/settings.json). It installs for SessionStart,
BeforeAgent, BeforeTool, AfterTool, AfterAgent, Notification and
SessionEnd,
and the callback maps them onto tclaude's turn states: working, idle, and
awaiting permission while Gemini shows a tool-confirmation dialog. The
installed command discards its output and always exits 0, so it can never
block, retry or comment on a Gemini turn. A settings.json with comments
is left alone, and setup asks you to add the hooks by hand. Gemini runs
settings hooks only in trusted folders, so live status needs the
project directory trusted. One known gap: Gemini fires no hook when a turn
ends because every pending tool was declined or cancelled (Esc, or "No" on
the confirmation). Such a row keeps showing working or awaiting permission
until the next prompt.
Renderer and mouse wheel. By default Gemini CLI renders inline and leaves
its history in the terminal's scroll-back. Inside tclaude's tmux pane, and in
the dashboard terminal, the mouse wheel then arrives as Up/Down keys, which
Gemini reads as prompt history. Gemini's alternate-screen renderer
(ui.useAlternateBuffer) handles the mouse itself, so the wheel scrolls the
conversation, as in Claude Code's fullscreen TUI. tclaude setup offers to
enable it in ~/.gemini/settings.json; an existing value is left alone.
Directory trust. Folder trust is on by default in Gemini CLI. In an
untrusted folder the pane stops on a trust dialog, hooks are off, and
headless ask fails. --trust-dir (or the dashboard's spawn option)
records the launch directory as TRUST_FOLDER in
~/.gemini/trustedFolders.json, or wherever
GEMINI_CLI_TRUSTED_FOLDERS_PATH points. It never overrides an explicit
DO_NOT_TRUST for the same directory, and it refuses to rewrite a file
it cannot parse strictly. Gemini treats a malformed trust file as a fatal
startup error.
Pass-through arguments. Arguments after -- that would make the pane
disagree with what tclaude recorded — --resume, --session-id, -i/-p,
--model, --worktree, the approval and trust options, --sandbox, --acp,
one-shot listing options — are refused with the dedicated tclaude option to
use instead. So are bare positional arguments (Gemini would read them as the
initial prompt, replacing the briefing, or as a subcommand) other than the
values of Gemini's list options such as --include-directories.
Sandbox. tclaude's built-in sandbox (--sandbox-impl tclaude-layer) wraps
the Gemini pane like any other harness. Gemini's own sandbox mode has these
values:
- inherit (the default) leaves your Gemini sandbox settings alone.
- off exports GEMINI_SANDBOX=false, which outranks --sandbox and
settings.json tools.sandbox, and exports an empty SANDBOX (so a workspace .env cannot refill it).
- seatbelt (macOS only, with --sandbox-impl harness-builtin) runs Gemini
under its own Seatbelt sandbox. It exports GEMINI_SANDBOX=sandbox-exec
and SEATBELT_PROFILE=permissive-open, plus the same empty SANDBOX. In
this mode:
- Writes are confined to the project, temp and cache directories.
- ~/.gemini and the credential files are write-protected.
- Outbound network stays open.
Gemini runs its hooks inside that profile, where tclaude's database is
read-only, so tclaude brokers the hook callbacks through agentd, as it does
under tclaude-layer. The profile also hides Gemini's own credentials and
trust store from the sandboxed CLI, which has these effects:
- The mode is refused for a Google sign-in. Use an API key or Vertex AI.
- tclaude exports GEMINI_CLI_TRUST_WORKSPACE=true for a folder your trust
store (or --trust-dir) trusts.
- Sandbox-profile filesystem rules are refused, because the profile is
Gemini's, not tclaude's.
Weaker than tclaude-layer in several ways:
- Unix sockets are unrestricted, so the agent can reach tclaude's tmux
server and run commands outside the sandbox through it.
- It can read ~/.tclaude.
- Git writes to a linked worktree's main repository are denied.
- Gemini refuses to start in a sensitive directory such as $HOME.
- Under inherit, an operator's own tools.sandbox: true selects this
sandbox without tclaude knowing, so hook callbacks are not brokered. Gemini also keeps this mode's chats under
~/.cache/.gemini. tclaude lists conversations from both places, but Gemini
can resume a conversation only in the mode that created it. Agents cannot
spawn Seatbelt-mode Gemini children; a human can.
tclaude-layer launches always use off. A container sandbox would re-run
Gemini outside tclaude's wall and out of reach of its hooks. Inside the
wall, ~/.gemini stays writable for chats and credentials. Its policy and
code surface is floored read-only (see
the harness-config floor). Agents
may spawn Gemini children only in this walled topology, the same rule as
Copilot. A filtered network list is enforced by the Linux packet gateway.
tclaude checks it against the route of Gemini's selected auth type, using the
net-google-gemini-api and net-google-gemini-login packs (see
Network filtering).
Approvals. --ask-for-approval renders Gemini's --approval-mode. The
semantics below come from Gemini's built-in policy files, not from a live pane:
yolo(default for daemon spawns): every tool call runs without confirmation, shell commands included. Gemini's own file tools stay inside the workspace; its shell commands are confined only by tclaude's sandbox. Gemini'sask_usertool still asks a human, since it is a question rather than a permission.auto_edit: workspace edits and web fetches run unattended, but shell commands still ask.default: edits, shell commands, web fetches and skills all ask.plan: read-only, so every mutating tool is denied.inherit: no flag; settings.jsongeneral.defaultApprovalModedecides.
Gemini drops yolo and auto_edit back to default in a folder it does not
trust, which is one more reason to pass --trust-dir. If your settings set
security.disableYoloMode or admin.secureModeEnabled, Gemini refuses
--approval-mode=yolo at startup. Pick another mode for those launches, or
make it the profile's default. For agent spawn
lineage, yolo counts as unattended command execution (the same weight as
Copilot allow-tools or Codex never), and an inherit child counts as the
broadest posture. The policy engine (--policy, --allowed-tools) is not
modeled, so those options are refused as pass-through arguments.
Known gap: the lineage classes assume the workspace's own Gemini
configuration is untouched. An agent that can edit files (Gemini auto_edit,
or an edits-capable agent of another harness) can write
<cwd>/.gemini/settings.json, including MCP server commands. In a trusted
folder, the next Gemini launch there loads that file. The same holds for
other harnesses' project config files. It is a sandbox-axis concern: a
profile can deny writes to .gemini/.
Usage. Gemini stamps each model message in its session file with that call's token usage. tclaude reads that back on every dashboard and agent-API read, the same read-through pattern Copilot uses: - The context meter shows the latest call's prompt size against Gemini's own per-model limit (1,048,576 tokens, or 256k for Gemma 4), the same figure the pane's footer shows. - Output tokens (thinking included) are summed over the conversation.
Gemini records no price, so tclaude prices each model call itself at Gemini
API pay-per-token rates. Whether that estimate counts as real spend or a
what-if cost follows cost.gemini_billing (Config › Usage & costs › Cost display › Gemini billing):
under the default auto, a session whose Gemini settings select an API key
(security.auth.selectedType gemini-api-key) or Vertex AI is shown as real
API spend, while a Google sign-in, or no readable selection, stays a what-if
estimate behind the same opt-in Codex uses (cost.show_on_subscription).
api and subscription force either side, for example when a Google sign-in
uses a paid Cloud project. Either way the figure is tclaude's estimate, not
Google's invoice. The classification is applied while a session runs and
covers its whole conversation: a running or resumed conversation moves to
the current side, while an exited one keeps the side it was recorded under. Cached prompt tokens get the cached rate,
thinking tokens are priced as output, and Pro models switch to the long-context
rate for prompts over 200k tokens. Calls dropped by a rewind or a /compress
still count, because they were made. A model without a published rate, such as
an older preview, adds nothing rather than borrowing another model's price.
The output total
covers only the turns that survive in the file, so it can go down after a
rewind or a /compress. After a compression, the context reading keeps its
old value until the next model call reports usage.
Not yet: - The proxy network engine on macOS (it works on Linux).
Gemini's own sandbox is offered only as Seatbelt on macOS. On Linux it is a container that would run the agent outside tclaude's hooks, so use tclaude's sandbox there.
Gemini has no counterpart for remote control, fast mode, a command-backed status line, or tclaude's task runner.
pi¶
pi (@earendil-works/pi-coding-agent,
1.1.0 or newer) is the open-source coding agent from earendil-works.
What works. Spawn and resume (--session-id, and resume by session file
so a pane never stops on pi's fork prompt), model and thinking level
(--model provider/id, --effort as pi's --thinking), /name, /compact
and a soft /quit, and directory pre-trust in pi's own trust.json. pi uses
your own ~/.pi/agent: its providers, logins, settings and telemetry choice.
tclaude passes no credentials into pi.
Live status needs no setup. pi has no hook configuration, so tclaude ships
a small pi extension inside its binary, writes it read-only under
~/.tclaude/pi-extension (checked byte for byte before every launch, and
mounted read-only inside tclaude's sandbox), and loads it per launch with
--extension. It reports turns, tools,
dialogs, compaction, /clone//new session switches and exit to tclaude the
way other harnesses' hooks do. Nothing is written to ~/.pi, and a slow or
missing tclaude never stalls pi.
Approval and sandboxing. pi has no approval prompts and no sandbox of its
own. auto (the default) runs every tool, including shell commands,
unattended. ask loads a second tclaude extension, written read-only beside
the status one, that asks you in the pane before every tool call that is not
read-only: pi's read, grep, find and ls, and MCP tools whose server
marks them read-only, run unasked; shell commands, edits and everything else
open a confirmation showing the call's arguments (control characters shown, never obeyed). The pane shows as awaiting
permission until you answer, in the pane or the dashboard's terminal. A
declined call is blocked, and the model is told so. With no one to ask (pi's
print mode), such a call is blocked. ask gates tool calls, not code pi
itself loads: an extension in the workspace's .pi/extensions runs when pi
starts, so approve a write there as you would approve running it. ask is a
human-gated posture: an agent that itself asks a human (Claude default,
Codex on-request) may spawn a pi child in it. read-only exposes only
read, grep, find and ls. Because nothing else confines auto, a fresh auto
launch is refused unless tclaude's own sandbox wraps it (--sandbox-impl
tclaude-layer, which spawn profiles for pi recommend) or the human ticks
Allow launch with unenforced rules in the dashboard spawn dialog.
One-shots. tclaude ask runs pi --print (streamed through
pi --mode json on a terminal) limited to pi's read-only tools, and an
interactive ask loads the permission extension. A fresh thread is
--session-id, a follow-up resumes the same session file. Automatic session
naming is an unpersisted (--no-session) read-only one-shot. A séance
continues a copy of the predecessor's session file under its recorded
posture, inside tclaude's sandbox when the generation ran there, and
removes the copy afterwards.
Inside tclaude's sandbox pi runs against a walled copy of its agent
directory, not your own ($PI_CODING_AGENT_DIR, else ~/.pi/agent). pi runs
an API key that starts with ! as a shell command, and models.json and
settings.json can name commands and code too, so your agent directory is
read-only inside the wall, files that exist and files that do not, apart
from its session store: a sandboxed agent cannot change what the next,
possibly unsandboxed, pi runs. Each conversation has its own walled copy,
under ~/.tclaude/pi-agent, so no two sandboxed agents share one. It is
rebuilt from yours before every walled launch and removed once its
conversation has no session left:
- every entry pi reads (
settings.json,models.json,extensions/,skills/, the prompt files, and so on) is a link to yours, so pi sees your configuration, and a write through a link fails; sessionsis a link to your session store, which stays writable, so conversations land where tclaude and your own pi find them (a session directory your settings move elsewhere is granted too);auth.jsonis a writable copy of yours, so an OAuth login (ChatGPT, say) refreshes inside the wall. Only a genuine refresh of your ChatGPT (openai-codex) login travels back to yourauth.json: newer, with a rotated refresh token, for the same ChatGPT account, and only its tokens and expiry (capped at 60 days). Nothing else does: no API key, no other field, no provider you are not logged in to, and no other provider's login, since pi trusts more of some logins than their tokens (Copilot's API host comes from its token). tclaude carries the refresh back before every walled launch and every 30 seconds while the daemon runs, and carries your own newer login into the copy the same way. A provider whose refresh tokens rotate, other than ChatGPT, keeps your original login, which a walled refresh may leave stale, so pi outside the wall may ask you to log in again. A/logininside the wall stays in the copy until the next walled launch rebuilds it.
pi cannot install its managed fd and rg from inside the wall; install them
on the host (or run pi once outside it) and find/grep use them. Other
harnesses' homes are not visible. In a constructed root (such as a filtered
network on Linux) tclaude starts pi's CLI by absolute path and mounts the pi
package and its Node runtime read-only. That works for an npm install (global,
local, nvm, mise) and for pi's own installer:
- With pi's installer,
pion PATH is a#!/bin/shlauncher (~/.pi/agent/bin/pi). tclaude starts the release~/.pi/agent/install/current-versionnames instead, with the installer's Node (${XDG_DATA_HOME:-~/.local/share}/pi-node/current), elsenodefrom PATH. It setsPI_MANAGED_INSTALL_ROOTas the launcher does. The release is resolved at launch, so api updateapplies to the next launch. - Any other shell shim on PATH (asdf, pnpm) is refused there. Put the Node
install's own
bindirectory on PATH instead.
Filtered network. A filtered launch checks the model's route against
your network rules and refuses, with the missing destination, when they do not
allow it. tclaude reads the provider from --model provider/id (or, without
one, the defaultProvider in pi's settings.json; a resume uses the model the
session records) and maps it to the provider's host: anthropic
(net-anthropic), openai (net-openai-codex), openai-codex (ChatGPT,
net-openai-chatgpt), google (net-google-gemini-api), and openrouter,
xai, groq, mistral, deepseek, cerebras, together, fireworks,
zai, moonshotai and huggingface, which need an allow row for their API
host. A provider with a baseUrl in models.json (a local Ollama, say) needs
that endpoint. Anything else, such as a provider an extension registers,
Bedrock, Vertex, Azure or GitHub Copilot, refuses the filtered launch rather
than guessing, as does an httpProxy in pi's settings. The launch also runs pi
offline (PI_OFFLINE=1, PI_SKIP_VERSION_CHECK=1, PI_TELEMETRY=0): no
version check, catalog refresh, install telemetry or tool download. Outside a
filtered network tclaude sets none of these and your pi settings decide.
Filtered pi launches use the packet gateway by default; the proxy engine is
activated on Linux only.
Conversations. tclaude lists and searches pi's session files wherever pi
keeps them (~/.pi/agent/sessions, or the sessionDir your settings name),
titles them by pi's session name, and follows the session tree the way pi does:
the current branch, from the newest compaction on. Clone, agent bundles and
federation carry the session file as is under a new id; a cross-harness morph
translates it, and a morph to pi needs a provider/model, since pi resumes
with the model its history names. The translation is budgeted to the model's
context window: the window models.json declares for a custom model, else the
one pi last reported for it, else an assumed 32k; history that does not fit
needs the same confirmation as any other morph.
For pi, tclaude reads version 3 session files. Reopen older version 1/2 files
in pi first so pi migrates them; tclaude refuses unsupported versions rather
than silently dropping their history. A live extension-backed pane that sends
no status hooks within 30 seconds shows ⚠ status missing in the dashboard.
Check the loaded tclaude extension, extension API compatibility and configured
hook executable (for pi, TCLAUDE_PI_HOOK_BIN). The warning clears when a valid
hook arrives; the daemon logs it once per launch.
Context meter and cost. The extension reports pi's own context usage and
what the session has spent, priced from pi's model catalog, on every event.
Under a subscription login (ChatGPT, GitHub Copilot) that price is only what
the tokens would have cost, so it is recorded as what-if cost. A pinned
auto-compaction window (--auto-compact-window) makes the extension compact
between runs once the context reaches it; pi's own threshold near the model's
full window stays the backstop. A cost factor for pi can be set under
cost.harness_factors.
Extension drive (experimental). tclaude agent spawn --pi-drive (or
pi_drive in the spawn request) takes the new agent off tmux send-keys. The
same tclaude extension holds a long poll on the agent socket
(POST /v1/whoami/pi-drive) and runs what the daemon sends through pi's own
API: inbox messages and reminders as user turns (steered into a running turn,
as a typed message would be), compaction with its follow-up, rename
(setSessionName) and the soft stop. As with the other API drives, an
opted-in agent is channel-only: while the extension is not polling, messages
stay in the inbox and are delivered when it reconnects, and a rename,
compaction or soft stop fails instead of being typed (a stop still ends the
pane). Only the pi process itself can hold the channel: a process pi started
(a tool's shell or script) is refused. The choice is per launch, recorded with
the agent and kept on resume; a launch without it is told so, and its extension
stops asking.
tclaude ask and prompt-based name refinement are supported; see
Asking questions for pi's one-shot behavior.
Related pages¶
- Sessions — launching, attaching, and the shell hack.
- Sandboxing — the two sandbox axes and profile model.
- Network filtering — filtered launches per harness.
- Spawning and lifecycle — spawn profiles, lifecycle verbs, séance.
- Utilities — status line, context trimming, usage tooling.
- Adding a harness — the contributor recipe.
Federated model gateway¶
Claude Code, Codex and Copilot workers support --model-proxy <name>@<peer>
through a session-bound loopback gateway. Claude Code uses Anthropic Messages;
Codex uses OpenAI Responses through a launch-only custom provider, covering its
TUI and app-server drive. Copilot CLI 1.0.91 or newer uses HTTP Responses BYOK
with COPILOT_OFFLINE=true, covering its TUI and embedded API drive. Copilot
requires an explicit model (auto is refused); offline mode disables GitHub
login, telemetry, GitHub MCP and web tools. Provider headers, key commands,
registry inputs and ambient authentication cannot replace the launch bearer.
Explicit off overrides profile defaults. Saved provider logins cannot replace
the pinned gateway route; conflicting overrides refuse the launch. See
Model gateways for permissions,
limits, usage and shutdown controls.
OpenCode remains unsupported even though it supports custom provider URLs and already carries named HTTP proxies. Its managed server loads persistent account/org and managed configuration after inline provider config; plugin hooks can also change provider settings. The existing filtered-launch guards do not prove gateway isolation across ordinary launches and resumes. A future binding must establish that invariant for the authoritative server and all primary, small-model and subagent choices. See the pinned upstream config merge order and provider hooks.
Gemini CLI remains unsupported. GOOGLE_GEMINI_BASE_URL redirects only its
native Gemini API-key route, which uses GenerateContent rather than Anthropic
Messages or Responses. A binding needs native path/model authorization,
streaming usage accounting and output reservations, plus forced API-key auth
that cannot fall back to saved Google OAuth, Vertex settings or .env inputs.
See Gemini configuration.
Both harnesses refuse a gateway request with the reason before launching.
Non-interactive one-shot runs also refuse a proxy choice.
Startup-context re-injection¶
Every harness that reports a compaction gets the same queued message; see
Agents and groups. Copilot has no post-compaction hook,
so the daemon reads compactions from session.compaction_complete and /clear
from session.context_cleared in the session event log. It notices within a
few seconds, and the message can take up to about 30 seconds more to arrive. A
failed compaction, or a subagent's, queues nothing. What is already in a resumed
conversation's log is not answered again.
Gemini CLI is the gap: PreCompress is advisory and fires before the
compression, and no event follows it, so tclaude cannot tell whether a
compression happened and queues nothing. A Gemini agent keeps only what the
compression summary kept.
tclaude-managed instructions¶
Group/user managed rules and skills are scoped to each managed agent launch, never installed into the user's harness HOME. Rules use the startup briefing and are re-injected after compaction/clear from the frozen launch snapshot.
| Harness | Managed skill loading |
|---|---|
| Claude Code | Per-launch --plugin-dir when the installed CLI advertises it; briefing paths otherwise |
| Codex | Agent-private SKILL.md paths in the briefing |
| OpenCode | Agent-private SKILL.md paths in the briefing |
| Copilot | Agent-private SKILL.md paths in the briefing |
| Gemini | Agent-private SKILL.md paths in the briefing |
| pi | Native per launch: the launch directory as a command-line package (--extension), so a managed skill shadows a same-named ambient one; rules appended to the system prompt by tclaude's pi extension every turn, so they survive compaction and pi still loads the operator's APPEND_SYSTEM.md |
The fallback lists instructions to read on demand; it does not claim native slash-command registration. See Managed skills and rules.