tclaude¶
tclaude is a self-hosted agentic dev environment: a Go CLI plus daemon that
wraps vendor coding CLIs ("harnesses") in tmux and adds the operations layer
for running many agents seriously — durable sessions, conversation history
and search, an operations dashboard, agent-to-agent mail, teams, identity and
permissions with audit, sandboxing, and automation.

The operations dashboard watching a mixed-harness fleet
Six harnesses are supported behind one workflow: Claude Code, OpenAI Codex CLI, OpenCode, GitHub Copilot CLI, Google Gemini CLI, and pi. Gemini CLI and pi support is beta: it is new and less battle-tested than the others (see Gemini CLI and pi). tclaude records the harness on every conversation, so listings, resume, lifecycle operations, and the dashboard route through the correct CLI automatically. Where harnesses expose different primitives, tclaude reports the difference instead of pretending the capability exists — see Harnesses for the capability matrix.
Everything beyond solo sessions routes through one daemon, agentd: identity,
permissions, audit, spawning, and mail. The daemon is fail-closed — there is
no path around it. For the mental model behind sessions, conversations,
agents, and the daemon, read Architecture.
New here?
Follow the Learn path: short hands-on tutorials from your first session onward. The rest of these docs are reference.
Start with the workflow you need¶
| Goal | Start here |
|---|---|
| Understand the moving parts | Architecture |
| Pick and configure a harness | Harnesses |
| Keep coding sessions alive and move between them | Sessions |
| Find or resume past work from any harness | Conversations |
| Ask a quick, resumable question from the shell | Ask |
| Work on branches in parallel | Worktrees |
| Get alerted when an agent needs you | Notifications |
| Form agent teams that talk to each other | Agents and groups |
| Keep a short list of what each group does next | Task boards |
| Spawn agents and manage their lifecycle | Spawning and lifecycle |
| Control what agents may do, and see what they did | Permissions and audit |
| Deploy whole rosters from templates, on a schedule | Teams at scale |
| Watch the whole fleet from a browser | Dashboard |
| Operate away from the host machine | Remote |
| Link your instance with colleagues' or your other machines | Federation |
| Export, snapshot, share or archive an agent's state | Portable Agent Format |
| Confine what agents can touch | Sandboxing and network filtering |
| Give tokenless agents git/GitHub/Linear access | Proxies |
| Run enforced multi-step workflows | Processes |
| Share a workflow as a file | Portable Workflow Format |
| Status bars, usage reports, DB inspection | Utilities |
Platform support¶
| Platform | Support |
|---|---|
| Linux | Supported |
| macOS | Supported |
| WSL | Supported as Linux, with some window-focus limitations |
| Native Windows | Not supported |
tmux is required for session management. You also need at least one harness
CLI installed and authenticated: Claude Code, Codex CLI, OpenCode, Copilot
CLI, Gemini CLI (beta), or pi. On Linux, tclaude's sandbox, the default for new
installs, also needs bubblewrap.
Installation¶
Installing tclaude has two parts: install the binary, then run setup. Setup is required because hooks provide live status and notifications, and because the local protocol and statusline integration is not part of the binary itself.
1. Install the binary¶
There are three ways to install tclaude. They differ mostly in how it is updated later; Keep tclaude updated covers that.
Requires Go 1.27+ and tmux:
The daemon is built into that binary as tclaude agentd serve. It also
ships as a standalone tclaude-agentd binary, which is a separate
package path and therefore a separate install:
From a source checkout, go install . ./cmd/... installs both at once,
plus the tclaude-hub federation relay.
Updates: tclaude's own updater, once you opt in. go_install
rebuilds a go install build at the new release. source_checkout
fetches your checkout and rebuilds it, at the release tag or following a
branch such as main.
Download a Linux amd64/arm64 or macOS arm64 archive from the
Releases page, extract
it, and move tclaude onto your PATH. Each binary and platform gets
its own archive, named after the build that produced it: take a
tclaude-no-cgo_linux_* or tclaude-darwin_* archive for the CLI, and
the matching tclaude-agentd-* one if you also want the standalone
daemon. The two are never packed together, so put both binaries on your
PATH — that is how the daemon finds tclaude.
Updates: tclaude's own updater, once you opt in. release downloads
the new archives and checks them against the release's SHA-256
checksums.
On macOS or Linux:
The formula installs tmux and builds tclaude from source. It builds only
the tclaude binary; if you also want the standalone tclaude-agentd
daemon, add it through the Go or prebuilt path.
Updates: brew upgrade tofutools/tap/tclaude. tclaude never writes
into Homebrew's Cellar. It can tell you when a release is out, or run
brew upgrade for you if you allow it.
Other methods. tclaude also recognizes installs owned by Nix, mise, asdf, dpkg (apt) or rpm (dnf). Like Homebrew, the package manager updates those.
2. Run setup¶
For the standard integration plus the coordination skills and permissions most users want:
The baseline setup (always runs):
- checks for tmux;
- installs Claude Code hooks in
~/.claude/settings.jsonand offers the command-backed Claude Code status bar; - when Codex is on
PATH, offers Codex hooks and a curated Codex status line — no flag needed on a machine that has Codex; - when Copilot CLI is present, offers enabling its copy-on-select clipboard bridging;
- when Gemini CLI is on
PATH, installs its hooks in~/.gemini/settings.jsonand offers its alternate-screen renderer so the mouse wheel scrolls; - registers the
tclaude://protocol handler on WSL for clickable notifications; and - asks once, on first run only, whether desktop notifications should be enabled.
tclaude setup --harness codex installs or repairs Codex hooks explicitly
(useful for scripted installs); the flag accepts any harness with a hook
installer (claude, codex, copilot, gemini). OpenCode has no hook
installer, pi needs none (tclaude loads its own extension per launch), and the baseline already installs hooks for every hook-capable
harness found on PATH. See Harnesses for per-harness setup details.
Optional extras are additive and idempotent:
| Flag | Adds |
|---|---|
--install-agent-skills |
Bundled skills (agent-*, human-*, process-templates, process-runs, taskboard, present-pr-to-operator, reincarnate, tclaude-setup, tclaude-fleet) for every coding harness through Claude Code, shared ~/.agents/skills, and Codex home directories |
--install-proxy-skills |
Skills for the configured credential proxies (proxy-git, proxy-linear, proxy-awb and proxy-http); not included by --install-all |
--install-utility-skills |
Optional utility skills from the repo's skills/ directory, such as demo-recording (record a narrated demo video of a feature built end to end and send it to the operator); not included by --install-all |
--install-default-agent-permissions |
Low-risk permission slugs the bundled skills exercise, as agent defaults in ~/.tclaude/data/config.json |
--install-sandbox-hardening |
Append-only sandbox and deny entries in ~/.claude/settings.json that protect agentd's private state |
--install-resume-threshold-override |
A claude_resume.threshold_minutes override that suppresses Claude Code's interactive resume-from-summary prompt for scripted resumes |
--install-all |
All standard extras above, excluding --install-proxy-skills and --install-utility-skills |
Proxy skills require explicit opt-in even under --install-all, so agents
are not shown proxy capabilities on installations where those services are
not configured. Utility skills are opt-in too: they are workflows you choose
to give your agents, not part of the baseline.
To prepare hooks before installing the harness CLIs, add --all-harnesses.
It creates missing configuration directories for every harness with a hook
installer (Claude Code, Codex, Copilot and Gemini CLI); --install-all alone
keeps the usual harness detection. Codex hook trust still needs its CLI:
after installing Codex, rerun tclaude setup --harness codex -y to grant it.
Skills do not start the daemon
The extras install skills and permissions. To use tclaude agent, also
start the daemon; see Run the daemon.
Verify the installation whenever you upgrade or change harness versions:
3. Run the daemon¶
Everything beyond solo sessions goes through the daemon, agentd. Start it
in a terminal outside any sandbox. There are four ways to keep it running:
- In a terminal.
tclaude agentd serveruns in the foreground and stops when you close the terminal or log out. Good for trying tclaude out. - Start on login. Config › Installation › Start automatically in the
dashboard has Start on login…, or run
tclaude service installwhile agentd is running. It writes a systemd user unit (Linux) or a LaunchAgent (macOS) that runs agentd with the flags it runs with now, and takes effect at your next login. Agents keep running when the unit restarts agentd. On Linux, agentd also stops at logout unless lingering is on, which needs root;tclaude service installprints thesudo loginctl enable-lingercommand to run. See systemd and launchd. - App launcher.
tclaude service launcher installadds tclaude to your desktop's app menu (a.desktopentry on Linux,~/Applications/tclaude.appon macOS). Picking it starts agentd if it is not running, through the login unit when there is one, and opens the dashboard. Without a unit it runstclaude agentd servewith the launch profile's flags, or by default--persist-operator-token --dashboard-port=<port> --no-print-human-token(the running daemon's fixed port, or 7878);install --serve-args "…"sets your own. To sign you in, it needs a persisted operator token, in the file or the keychain (see The operator token).tclaude service launcher statusandinstallwarn when the running daemon's token is not persisted, or when the launcher's flags lack--persist-operator-token. See App launcher. - A service on a server. For a headless machine, see Running tclaude on a server.
Recommended flags. For a daemon that starts on its own, use a fixed port and a persisted token:
| Flag | Config key | What it does |
|---|---|---|
--dashboard-port 7878 |
agent.dashboard_port |
A fixed dashboard port, so bookmarks and SSH tunnels keep working. The default picks a new free port each start. A port already in use fails startup. |
--persist-operator-token (-p) |
agent.persist_operator_token |
Keeps the same operator token across restarts, in a 0600 file the CLI reads itself. The default mints a new one each start. |
--persist-operator-token-keychain |
agent.persist_operator_token_keychain |
Keeps it in the OS keychain instead of the file. Terminal commands do not read the keychain; only the app launcher does. |
--no-print-human-token |
Does not print the token at startup. It is still minted and accepted. The default, --print-human-token=auto, prints it only when stdout and stderr are terminals. Never use always under a supervisor: it writes the token to the journal or log file. |
|
--no-tray (-n) |
agent.disable_tray |
No system tray icon, for headless hosts. On a desktop, the tray's Open dashboard is a way in that needs no token. |
--dashboard-bind <host> |
agent.dashboard_bind |
Also serves the dashboard on another interface. The default is loopback only. Its only gate is a cookie plus the operator token, so bind only to a network you trust; see Operating remotely. |
The config keys are set in Config › Daemon & network and apply however
agentd is started. To pin the flags and environment that the login unit and
the app launcher start agentd with, set a launch profile in Config ›
Installation (Use what's running now fills it from the running daemon),
or with tclaude service launch. See
Launch profile.
4. The operator token¶
The operator token (tclo_…) is how agentd knows that a command comes from
you, the operator, and not from an agent. The daemon mints it at startup.
Sandboxed agents cannot read your environment or ~/.tclaude/data, and a
caller running under a harness is never treated as you, even if it has the
token.
When you need it:
- for
tclaude agent dashboardand every other operator command you run in a terminal, such as granting permissions,tclaude serviceandtclaude update; - to sign in in a browser without a one-time link: a bookmark, another browser, or an expired link shows a sign-in page that asks for it;
- for the TUI dashboard against a running
daemon (
tclaude agent tui-dashboard --connect-to …), which takes--operator-token, reads it over ssh with--remote-operator-token, or uses the local one; - for the dashboard on another machine, over
--dashboard-bindor an SSH tunnel.
You don't need it for the tray's Open dashboard, for
--auto-launch-dashboard, or for tclaude agentd serve --tui, which shows it
inside the UI.
How to get it:
- From the startup banner. In a terminal,
tclaude agentd serveprintsexport TCLAUDE_HUMAN_TOKEN="tclo_…". Run that line in the shell you work in. The CLI usesTCLAUDE_HUMAN_TOKENbefore anything else. - From the file. With
--persist-operator-token, the token is in~/.tclaude/data/operator_token(mode 0600). The CLI reads it there whenTCLAUDE_HUMAN_TOKENis not set, so you need not export anything.cat ~/.tclaude/data/operator_tokenprints it for a browser sign-in. -
From the keychain. With
--persist-operator-token-keychain, it is stored under servicetclaude, accountoperator_token. Export it yourself:# macOS: the entry holds "go-keyring-base64:" plus the token in base64 export TCLAUDE_HUMAN_TOKEN="$(security find-generic-password -s tclaude -a operator_token -w \ | sed 's/^go-keyring-base64://' | base64 -D)" # Linux (Secret Service) export TCLAUDE_HUMAN_TOKEN="$(secret-tool lookup service tclaude username operator_token)"If the keychain cannot be reached, agentd logs an error and uses a fresh token for that run.
Once the CLI has the token, tclaude agent dashboard opens the dashboard
already signed in, through a one-time link that expires in about a minute.
--print prints the link instead.
Rotating it. Without persistence, restarting agentd mints a new token.
With the file, delete ~/.tclaude/data/operator_token and restart agentd;
with the keychain, delete the tclaude / operator_token entry and restart.
Then export the new token wherever you exported the old one.
5. Keep tclaude updated¶
tclaude's updater is opt-in. Nothing updates on its own until you choose an update method and turn on a schedule or updating when agentd starts. Set it in Config › Installation › Updates, or with the CLI:
tclaude update config show # how tclaude was installed, and the method it recommends
tclaude update config set method release # or go_install, source_checkout, …
tclaude update config set schedule daily # or weekly, with weekday and window
tclaude update config set update-on-start true
tclaude update config set post-setup on # rerun tclaude setup with the new version
tclaude update --dry-run # test the saved method; installs nothing
tclaude update --apply # update now
The Updates part has the same Check now, Test method and Update now buttons.
An update replaces the binaries, checks that they report the expected
version, and restarts agentd gracefully. Agents keep running in tmux.
tclaude update checks for a release by hand, --apply installs it, and
--rollback restores the previous binaries. With a schedule, Wait while
agents are working (defer-while-working) holds a run until your agents
are idle.
Package-manager installs. tclaude never writes into a package manager's
tree (/usr, /nix, a Homebrew Cellar, mise and asdf installs). For those
installs you can:
- update with the package manager yourself, and pick
manualto have tclaude tell you when a release is out; - let tclaude run the package manager's command (
homebrew,nix_profile,mise,apt,dnf), which you confirm with--confirm-package-manager;aptanddnfneed passwordlesssudo -n; - install tclaude's own build next to it, in
~/.local/binby default, after acknowledging that the package manager still owns its copy. Untrack that copy, or put~/.local/binfirst onPATH.
How tclaude updates itself covers detection, every method, the schedule and rollback.
First session¶
Run bare tclaude in a project directory to start your default harness in a
session (tclaude --harness codex picks another). Sessions covers starting, detaching, watching and
reattaching. To work from the dashboard instead, follow the
Learn path.
Quick questions from the shell¶
tclaude ask runs a harness in the foreground — no tmux session — prints
the answer, and returns control to your shell. The thread continues per terminal
and working directory, and piped input is attached as context:
tclaude ask "explain the data flow in this package"
git diff | tclaude ask "what correctness risks do you see?"
tclaude ask --new "start a fresh topic"
tclaude ask -i "help me refactor this interactively"
All six agent harnesses support ask. The Ask guide covers continuity, capture safety, and how the harness is chosen.
Operate a fleet¶
Solo sessions work without the daemon. For anything multi-agent (groups,
messaging, spawning, permissions, the dashboard), run tclaude agentd serve
in a non-sandboxed terminal. The tutorial
Run a team through a lead walks through it step by step.
The reference starts at Agents and groups.
Use tclaude <command> --help for the live flag reference; these guides
focus on workflows and the behavior that is easy to miss from help text.