Metadata-Version: 2.4
Name: tb-agent
Version: 0.5.0
Summary: Local execution daemon for Tether Brain agent installations
Project-URL: Homepage, https://tetherbrain.net
Project-URL: Documentation, https://github.com/duelistraj/tb-agent#readme
Project-URL: Source, https://github.com/duelistraj/tb-agent
Project-URL: Issues, https://github.com/duelistraj/tb-agent/issues
Author: Tether Brain
License-Expression: AGPL-3.0-only
License-File: LICENSE
Keywords: agent,codex,daemon,tether-brain
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Requires-Dist: httpx<1,>=0.28
Requires-Dist: openai-codex<1,>=0.1
Requires-Dist: pydantic-settings<3,>=2.12
Requires-Dist: pydantic<3,>=2.12
Description-Content-Type: text/markdown

# 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`:

```bash
uv tool install tb-agent
```

For a repository checkout, install the local package instead:

```bash
uv tool install .
```

The source is maintained at [github.com/duelistraj/tb-agent](https://github.com/duelistraj/tb-agent).

The former `tether-agent` executable remains as a deprecated alias in the 0.5.x release line so existing scripts and service definitions continue to work.
Run new commands with `tb-agent`.
The alias will be removed in 0.6.0.

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

## Initialize

Initialize the default local profile:

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

The CLI opens the guided Tether Brain setup page for sign-in, repository confirmation, workspace execution configuration, capability approval, model selection, and final readiness.
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.

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

```bash
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:

```bash
tb-agent run
```

Inspect local state without revealing credentials:

```bash
tb-agent status
```

## Profiles

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

```bash
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.

## Workspaces

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

```bash
tb-agent workspace add \
  --path .
```

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:

```bash
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:

```bash
tb-agent codex skill install
```

Inspect or remove it with:

```bash
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:

```bash
tb-agent auth login
```

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

```bash
tb-agent auth migrate
```

Refresh or revoke an OAuth installation credential explicitly:

```bash
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:

```bash
tb-agent auth set-pat
```

Inspect or remove local authentication:

```bash
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:

```bash
tb-agent migrate env --dry-run
```

Perform the migration:

```bash
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.

```bash
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, run `tb-agent service install` once to rewrite an older service definition that still invokes the deprecated alias.

## 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.
