CodeTether Agent

CodeTether Agent is an A2A-native AI coding agent for terminal-first software work. It ships as one Rust binary, codetether, and combines an interactive TUI, one-shot prompts, persistent mux sessions, managed Git worktrees, provider-backed model routing, MCP, A2A workers, swarm execution, and a TetherScript plugin runtime.

What it is

CodeTether is built for developers who want an agent that can stay close to the repository and keep working across longer tasks:

• Interactive by default: running codetether starts the TUI.
• Scriptable when needed: use codetether run "..." for one-shot work.
• Session-oriented: mux sessions let you detach, reconnect, and steer work.
• Multi-agent capable: swarm, Ralph, Forage, and A2A cover autonomous and distributed workflows.
• Tool-aware: native tools, browser control, Windows automation, MCP, and TetherScript plugins run through the same agent runtime.
• Security-conscious: Vault-first provider secrets, mandatory server auth, audit logs, policy hooks, approvals, and managed worktree isolation are part of the normal operating model.

Install

Get current binaries from Forgejo releases. Linux x86_64, Apple Silicon macOS, Intel macOS, and Windows x86_64 packages are published with SHA-256 checksums. The Unix installer below downloads from Forgejo and includes development prereleases. Registry packages and the GitHub mirror can lag behind Forgejo.

Windows

For the Forgejo build, download the Windows MSI or setup ZIP from the release assets.

The existing PowerShell installer remains GitHub-backed. To use that separate installation path, open PowerShell normally, not as Administrator:

irm https://raw.githubusercontent.com/rileyseaburg/codetether-agent/main/install.ps1 | iex
codetether --version

If the command is not found or resolves to an old binary, use Windows installation and PATH checks. To update only an existing Vault token, see update Vault on Windows.

Linux (x86_64)

curl -fsSL https://forgejo.quantum-forge.io/riley/codetether-agent/raw/branch/main/install.sh | sh
command -v codetether
codetether --version

If the command is not found or resolves to an old binary, use Unix installation and PATH checks.

macOS (Apple Silicon and Intel)

Open Terminal and run as your normal user; no Rust toolchain or Xcode is required:

uname -m
curl -fsSL https://forgejo.quantum-forge.io/riley/codetether-agent/raw/branch/main/install.sh | sh
command -v codetether
codetether --version

The installer selects the correct Forgejo archive and verifies its SHA-256:

Mac	Release target
Apple Silicon (M-series, arm64)	aarch64-apple-darwin
Intel (x86_64)	x86_64-apple-darwin

On Apple Silicon, prefer a native Terminal rather than “Open using Rosetta.” The installer also detects Rosetta and selects the native ARM64 binary. Installation normally uses /usr/local/bin and may request sudo. For a no-sudo install to ~/.local/bin, pinned-version downloads, zsh PATH setup, and troubleshooting, see macOS-specific installation.

macOS packages are unsigned and not notarized. Do not disable Gatekeeper or remove quarantine blindly; see the guide before approving a downloaded binary.

Cargo

cargo install codetether-agent

From a checkout:

git clone https://forgejo.quantum-forge.io/riley/codetether-agent.git
cd codetether-agent
cargo install --path crates/codetether-agent

Optional features are explicit. The default feature set includes TetherScript. Local model, QUIC, and FIPS builds opt in separately:

cargo install --path crates/codetether-agent --features candle
cargo install --path crates/codetether-agent --features candle-cuda
cargo install --path crates/codetether-agent --features quic-transport
cargo install --path crates/codetether-agent --features fips

FIPS builds require CMake, Go, and a C compiler. See FIPS.

First run

Configure credentials before asking the agent to call a model. CodeTether loads provider secrets from HashiCorp Vault first; local environment fallbacks are for development convenience and can be disabled.

codetether vault --help
codetether auth --help
codetether models

Then start the interactive UI:

codetether
# or
codetether tui

For a single prompt:

codetether run "inspect this repository and summarize the main entry points"

For hardened deployments that must use Vault only:

export CODETETHER_DISABLE_ENV_FALLBACK=1
codetether serve

Credential guides:

• Vault CLI
• Unix Vault setup
• Windows Vault setup
• Vault token renewal

Common commands

codetether                  # start the TUI
codetether tui              # start the TUI explicitly
codetether run "..."        # one-shot prompt
codetether models           # list configured models
codetether mux --help       # manage persistent mux sessions
codetether worktree --help  # manage Git worktrees and editor integration
codetether serve --help     # authenticated HTTP API server
codetether worker --help    # A2A worker mode
codetether mcp --help       # Model Context Protocol server/client
codetether browserctl --help
codetether windows --help

Autonomous and analysis commands:

codetether swarm --help     # parallel sub-agent execution
codetether ralph --help     # PRD-driven autonomous loop
codetether forage --help    # OKR-guided opportunity scanner/executor
codetether okr --help       # objectives and key results
codetether rlm --help       # recursive large-content analysis
codetether search --help    # routed grep/glob/web/memory/RLM search
codetether benchmark --help

Setup and operations commands:

codetether config --help
codetether auth --help
codetether vault --help
codetether approval --help
codetether connect --help
codetether pr --help
codetether cleanup --help

Feature areas

TUI and sessions

The TUI is the default front door for day-to-day work. Mux sessions make agent and shell work durable so you can disconnect, return, and steer later.

Docs:

• Mux agent tasks
• Worktree lifecycle
• Runtime memory

Agents, A2A, MCP, and autonomy

CodeTether can run as an interactive local agent, an A2A worker, an MCP server/client, or an autonomous loop. Ralph works from PRDs; Forage selects work from OKRs; Swarm splits tasks across isolated workers.

Docs:

• A2A public agents
• A2A spawn
• Collaboration tools
• PRD

Tools and plugins

Native tools cover files, shell commands, browser control, Windows desktop/OCR, Git, worktrees, search, model calls, and approvals. TetherScript plugins add repeatable tools without changing or rebuilding Rust code.

Docs:

• Answer review during goals
• Plugin pattern
• Browser capability API
• Windows OCR and shadow input
• Computer-use safety

Local inference and specialized builds

Remote providers are the default path, but the crate also exposes opt-in local model features through Candle and Bonsai-oriented commands.

Docs:

• Native Bonsai
• FIPS

Security model

CodeTether assumes credentials and tool execution need explicit boundaries:

• Provider secrets are Vault-first.
• HTTP server auth is mandatory except for /health.
• Audit events are append-only JSON Lines records.
• Policy checks can be enforced through OPA.
• Tool execution supports approvals and runtime policy.
• Agent work is isolated with managed worktrees where appropriate.
• FIPS builds can require the AWS-LC FIPS module at startup.

Start with Vault CLI, FIPS, and computer-use safety for operational details.

Development

This repository is a Rust workspace. The main crate publishes the codetether binary and the codetether_agent library. Workspace crates include A2A worker core, browser support, and RLM support.

Useful local checks:

cargo fmt
cargo test --doc
cargo test <focused_filter> --lib
./check_file_limits.sh

Avoid assuming all optional features work on every workstation. CUDA, local model, QUIC, and FIPS feature sets may require extra system toolchains.

Repository shape:

crates/codetether-agent/  application composition, CLI and integration tests
crates/   workspace support crates
docs/     installation, security, plugin, transport, and operations guides
vendor/   vendored build dependencies used by selected workflows

Documentation map

• Unix install
• Windows install
• Vault CLI
• Plugin pattern
• First-party RustyRoad tools
• A2A public agents
• Native Bonsai
• FIPS
• Worktree lifecycle
• TUI rendering performance

License

MIT. See the package metadata in Cargo.toml.