tb-agent

tb-agent runs Tether Brain tasks on a local machine using the authenticated Codex CLI. Tether Brain coordinates runs and persists their results, but it never executes local commands.

OAuth is the default authentication method. The browser authenticates the user and records explicit workspace and local-execution consent, then the server gives the daemon a separate installation-scoped rotating credential. The daemon never retains a broad user OAuth token. PAT remains available as an advanced fallback.

Install

Install the published package with uv:

uv tool install tb-agent

For a repository checkout, install the local package instead:

uv tool install .

The source is maintained at github.com/duelistraj/tb-agent.

The package installs only the tb-agent executable. Releases before 0.6.0 also installed a tether-agent compatibility alias. After upgrading from an older release, use uv tool upgrade tb-agent and update scripts to invoke tb-agent.

The Codex CLI must already be installed and authenticated. Verify it with codex login status before initialization.

Initialize

Initialize the default local profile:

tb-agent init \
  --server https://tetherbrain.net \
  --path .

The CLI opens the guided Tether Brain setup page for sign-in, repository mapping, derived workspace access, capability approval, model selection, and final readiness. Optional board workflow configuration is available after the installation is connected. For OAuth setup, the server resolves the normalized Git remote to exactly one accessible logical project, so the user does not copy a project ID. If the browser cannot be opened, the CLI prints the authorization URL without printing authorization codes or credentials. Initialization validates the Git worktree, resolves its canonical root, discovers and normalizes its remote, checks Codex authentication, registers or reuses the stored installation identity, and reports whether capability approval is pending. Initialization never installs a background service. Running the same command again is safe. For a healthy profile it reports that the repository is already configured, and for a browser-revoked installation it opens fresh-installation replacement through the same guided OAuth flow. The browser provides the explicit replacement approval, so the CLI does not ask for a duplicate terminal confirmation. The replacement keeps repository mappings, immutable review records, retained worktrees, and completed Codex thread state. Any still-active lease is cancelled locally only after the replacement credential is validated. Profiles left in an unclassified reauthentication state by an older release perform one bounded refresh reconciliation before choosing reauthorization or replacement. Terminal credential failures are persisted so the daemon and later status commands do not repeatedly retry them.

Use PAT fallback only when browser OAuth is unavailable or the server does not support it:

tb-agent init --auth pat --server https://tetherbrain.net --path .

PAT input uses a hidden prompt and is never accepted as a command-line option.

Use --remote URL when the repository has ambiguous remotes. Use --allow-no-remote only when a repository intentionally has no remote.

Start the daemon in the foreground:

tb-agent run

Inspect local state without revealing credentials:

tb-agent status
tb-agent status --offline

Profiles

Every command accepts a global profile option before the command name. The profile defaults to default.

tb-agent --profile work init --server https://tetherbrain.net
tb-agent --profile work run
tb-agent --profile work status

Each profile has an independent configuration, credential, installation identity, daemon lock, and optional service. Only one daemon process may run for a profile. default is only the local profile name used when --profile is omitted. Do not create temporary profiles for parallel work. A single durable profile supervises multiple isolated run worktrees.

Configure one to four concurrent runs:

tb-agent concurrency status
tb-agent concurrency set 3

The default is one. Lowering capacity never cancels active work and affects only future claims. The server admits claims atomically from active, unexpired leases, while the daemon assigns a stable worker slot and a persisted collision-checked port range to each active run.

List or remove local profiles without manually finding platform-specific directories:

tb-agent profile list
tb-agent --profile work profile remove

Profile removal revokes the stored server credential when possible and removes the profile's local configuration, credentials, and service definition. Use --local-only only after browser revocation or when intentionally leaving server cleanup for later.

Workspaces

Add a workspace mapping without copying a new credential or editing JSON:

tb-agent workspace add \
  --path .

For OAuth profiles, the browser matches the normalized Git remote to the accessible logical projects and asks you to choose when more than one workspace uses that remote. Workspace access is derived from the confirmed repository instead of being selected independently. You can also generate this command from workspace Agent execution settings to include a single-use setup reference that identifies the logical project without exposing a credential. The reference expires quickly, is bound to the selected installation and workspace, and is consumed once. Direct --project-id remains available for advanced and recovery workflows.

List and remove mappings:

tb-agent workspace list
tb-agent workspace remove 00000000-0000-0000-0000-000000000001

OAuth-backed workspace changes reopen browser authorization so workspace expansion always receives explicit user consent. Workspace mutations coordinate maintenance mode with a running daemon, reject active executions, write the new revision atomically, and trigger live capability re-registration. The daemon pauses task claims until the changed capability manifest is approved. PAT-backed profiles retain the Phase 1 manual workspace-grant behavior.

Codex skill

Install the bundled Codex skill:

tb-agent codex skill install

Inspect or remove it with:

tb-agent codex skill status
tb-agent codex skill uninstall

The skill distinguishes interactive Codex MCP access from persistent board-task execution, detects the current Git repository, and uses the supported tb-agent commands. It never requests, reads, prints, stores, or places PATs or OAuth credentials in prompts or shell history. Start a new Codex session if a newly installed skill or MCP server is not yet available.

Authentication

Start or repeat OAuth onboarding:

tb-agent auth login

Migrate an existing PAT installation without changing its installation identity, Agent Profile, mappings, leases, revisions, or Codex threads:

tb-agent auth migrate

Refresh or revoke an OAuth installation credential explicitly:

tb-agent auth refresh
tb-agent auth revoke

auth revoke requires the daemon to be stopped, revokes the installation credential server-side, and removes it locally. Use auth revoke --purge only when the profile configuration and state should also be removed.

Configure PAT fallback through a hidden prompt:

tb-agent auth set-pat

Inspect or remove local authentication:

tb-agent auth status
tb-agent auth logout

Logout removes local OAuth or PAT material without revoking server-side credentials. It preserves the installation identity, Agent Profile identity, configuration, leases, and Codex thread state.

Switching an OAuth installation back to PAT requires typing an explicit confirmation phrase. The CLI never silently reuses an older PAT.

Migrate an environment installation

Existing TETHER_AGENT_* configurations continue to run without migration. Environment variables and the current .env file remain higher-precedence runtime overrides.

Preview migration while the existing environment is still configured:

tb-agent migrate env --dry-run

Perform the migration:

tb-agent migrate env

Migration copies the PAT, project mappings, installation identity, Agent Profile identity, leases, configuration revision, worktree records, and Codex thread state. It backs up the legacy SQLite database, is idempotent, and preserves the previous state if any local mutation fails. It never edits shell startup files.

After successful migration, remove or unset the migrated overrides before using workspace or authentication mutation commands. The CLI refuses a stored mutation when a relevant environment value would shadow it.

Background service

Service installation is optional and must be requested explicitly. Linux uses a user-level systemd unit and macOS uses a LaunchAgent. Windows supports foreground execution only.

tb-agent service install
tb-agent service start
tb-agent service stop
tb-agent service restart
tb-agent service status
tb-agent service logs
tb-agent service uninstall

Service definitions contain only the resolved tb-agent executable, profile name, and service metadata. They never contain a PAT or repository path.

Existing systemd and LaunchAgent service identities are preserved during the executable rename. After upgrading from a release before 0.6.0, run tb-agent service install once to rewrite an older service definition that invokes the removed executable.

Review, accept, and publish local changes

Every writable run uses its own Git worktree. After execution, tb-agent creates one synthetic immutable commit under refs/tb-agent/runs/<run-id> whose parent is the captured run base. The snapshot tree hash is the reviewed content identity bound through acceptance, feature-branch handoff, and publication.

Inspect and validate retained results locally:

tb-agent changes list
tb-agent changes status <run-id>
tb-agent changes path <run-id>
tb-agent changes diff <run-id>
tb-agent changes test <run-id> -- npm test

changes test creates a temporary detached checkout of the immutable snapshot. It never tests later manual worktree edits, reports the validation revision to Tether Brain, and stores the local validation log. Any worktree modification after snapshot creation supersedes the current review revision.

Browser acceptance binds the run ID, snapshot commit, snapshot tree, validation revision, and change-set revision. Only that accepted binding may advance the run-owned feature branch. The execution worktree remains detached and the user's current checkout is never switched, committed, fast-forwarded, or cherry-picked by handoff. Run branches use feat/<agent>/<task>-<run-id> and are based on the fetched upstream default branch captured when the run starts. Ambiguous remotes or default branches block before execution and require explicit configuration.

If an explicitly accepted handoff is blocked, reconcile the owned run branch and retry it:

tb-agent changes apply <run-id>

This command cannot accept a result and refuses any revision that has not already been accepted in Tether Brain. Repository handoff locks are derived from the canonical Git common directory, so separate profiles and processes cannot mutate run refs in the same repository concurrently.

Pull request publication is a separate, explicitly approved browser action. It never force-pushes, verifies an existing remote branch and pull request against the exact accepted snapshot, and blocks on divergence. To reconcile an already approved publication immediately from the terminal, run:

tb-agent changes publication <run-id>

The task reaches Done only after Tether Brain records the exact published head and pull request URL. Merge confirmation affects cleanup eligibility only. Local run worktrees, feature refs, and snapshot refs are retained until the pull request is confirmed merged and worktrees.handoff_retention_days expires. Remote branch deletion remains a GitHub repository policy, and GitHub's Automatically delete head branches setting is recommended. Local feature-ref cleanup uses the accepted published head as a compare-and-swap guard and blocks if anyone modified the branch.

Dirty worktrees created by an older release are marked legacy_manual_review_required. They can be inspected or rerun, but tb-agent never turns their existing filesystem contents into an automatically accepted snapshot.

Local security and state

The CLI stores non-secret settings in a mode-0600 TOML file under the platform configuration directory. It stores PAT fallback, OAuth setup recovery, installation access and rotating refresh credentials, credential generations, limited refresh recovery state, and execution state in a mode-0600 SQLite database inside a mode-0700 profile directory under the platform state directory. SQLite uses WAL mode, transactions, and a busy timeout. TOML replacements are atomic.

Only one process may refresh a profile credential at a time. The daemon refreshes early, pauses new claims when refresh fails, and never falls back silently to an old PAT.

Repository mappings contain canonical absolute paths only on the local machine. Capability manifests use logical project IDs and one-way mapping revisions. Outbound progress, comments, errors, and completion payloads scrub configured repository and worktree paths before transmission.

Legacy environment reference

The current TETHER_AGENT_* variables remain supported for existing deployments, including TETHER_AGENT_ACCESS_TOKEN, TETHER_AGENT_SERVER_URL, TETHER_AGENT_INSTALLATION_ID, TETHER_AGENT_AGENT_PROFILE_ID, TETHER_AGENT_STATE_PATH, TETHER_AGENT_RUNTIME_ADAPTERS, TETHER_AGENT_PROJECT_MAPPINGS, and TETHER_AGENT_WORKTREES. An environment TETHER_AGENT_ACCESS_TOKEN remains the effective PAT when present and shadows stored OAuth credentials. OAuth commands report the shadow and print the exact unset TETHER_AGENT_ACCESS_TOKEN instruction. Profile configuration continues to accept only the codex_cli runtime.