Harness Floating Terminal

An F7 floating shell beside Claude Code, Codex, or OpenCode, without wrapping your AI CLI. Run your AI command normally in a tmux pane.

Installation

Requires tmux 3.4+ and macOS or Linux. Install your AI CLI normally. Homebrew supplies tmux; other methods require you to install it separately.

Release note: Cargo v0.2.2 is published. The simplified Homebrew setup below requires the next release containing first-use registration; v0.2.2 still uses explicit setup. Homebrew/archive downloads also require public release assets. Choose one method; switching an existing installation requires the migration steps.

Homebrew

After the new stable release and tap formula are published:

brew tap vuongvm812/tap
brew install vuongvm812/tap/agent-float-term

No separate application installation is needed. The first agent-float-term bind or interactive agent-float-term start registers Homebrew's stable binary path without copying it or editing startup files. Homebrew owns binary updates. See platform limits, then activate.

Cargo

Using the default Cargo installation root:

cargo install agent-float-term --locked
aft="${CARGO_HOME:-$HOME/.cargo}/bin/agent-float-term"
"$aft" install --external-binary "$aft"
# Review the preview before applying:
"$aft" install --external-binary "$aft" --yes

Cargo compiles locally: Rust/Cargo and a native build toolchain are required. Rust 1.84.1 is the release toolchain. Cargo owns the executable and updates; see custom installation roots if your Cargo settings override the default.

Release Archives

After publication, download the archive for your OS/architecture from GitHub Releases, verify its entry in SHA256SUMS, then run the extracted binary's install preview and repeat with --yes. No Rust compiler is needed.

Follow the download and verification commands. The installer owns a local copy at ~/.local/bin/agent-float-term; do not copy a regular executable to that destination before running the installer.

Build From Source

git clone https://github.com/vuongvm812/agent-float-term.git
cd agent-float-term
cargo +1.84.1 build --locked --release
./target/release/agent-float-term install
# Review the preview before applying:
./target/release/agent-float-term install --yes
export PATH="$HOME/.local/bin:$PATH"

To build/install the managed application and patched tmux for status-bar clicking, use make install instead. make install DRY_RUN=1 previews the plan. It does not restart tmux; follow the printed separate-server launch command. See patched-server setup.

Activate

Ensure the selected binary directory is on PATH: Homebrew's bin, Cargo's installation-root bin, or ~/.local/bin for managed archive/source installs. Inside your existing tmux server:

agent-float-term bind
agent-float-term doctor
claude
# Or: codex / opencode

Press F7 to open or hide the float. Shell state survives hiding, but exiting the AI terminates its float and terminal jobs. The next AI run starts fresh.

Tmux shortcuts operate on the main terminal. Switching away leaves the float in its original AI pane; returning restores it unless you explicitly hid it with F7. Prompts and choosers temporarily take keyboard focus from the float. In the next release, Ctrl+h/j/k/l remain available to foreground Neovim inside the float; other tmux shortcuts still target main. The optional patched tmux server dismisses the float and switches sessions with one status-bar click; stock tmux requires hiding the popup first. See input behavior for details and limitations.

Fresh installation edits no startup files unless explicitly selected. Review key conflicts before using bind --replace-key. Outside tmux, agent-float-term start opens a dedicated tmux shell. See installation for automatic startup and operations for update, rollback, and uninstall.

Generated integration scripts live in ~/.local/share/agent-float-term/, not the config directory. Reinstalling migrates intact legacy scripts and managed references.

Configuration

Create ${XDG_CONFIG_HOME:-$HOME/.config}/agent-float-term/config.json if needed:

{
  "shortcut": "F7",
  "width": 80,
  "height": 80
}

These are the defaults. Dimensions are integer percentages from 10 to 100. Omitted fields use defaults; unknown fields, comments, and trailing commas are rejected. JSON only: an old config.toml is preserved but never loaded. If it exists without JSON, an error explains migration; {} explicitly uses defaults. Use shortcut, not key, and rebind the intended server after changing it. See configuration details for safe shortcuts, advanced shell/harness_paths, file permissions, and XDG rules.

Compatible Versions

See the validation matrix for platform coverage and test limits. This tool adds no telemetry or prompt logging; tmux is not a sandbox.

Contributing | Changelog | Publishing | Release checklist | MIT license

Maintainers: make release DRY_RUN=1 previews the coordinated release plan; make release requires explicit confirmation before publishing GitHub assets, the Homebrew formula, and a missing Cargo version. See release prerequisites.