AgenTerm

AgenTerm is a Rust-native terminal and local AI fleet controller for Windows, macOS, and Linux (x86_64 and aarch64). It combines hierarchical tabs, per-tab composers and environments, a native automation client, and a deliberately bounded tmux/RMUX frontend.

Why AgenTerm

• Lightweight native core — Rust with platform-native rendering (Win32/GDI, winit). No Electron shell. Public releases enforce binary budgets: 4 MiB for the GUI and Control Center, 2 MiB each for CLI, mux, and MCP.
• Stable fleet semantics — Detach-first close keeps live PTYs running; exited processes stay readable until you explicitly close the tab; normal restarts restore the workspace tree, names, notes, and drafts.
• Open and auditable — Source on GitHub under MIT OR Apache-2.0. Read the code, run the gates, and inspect every release artifact yourself.
• Supply-chain evidence — Public releases ship SHA-256 checksums, SPDX SBOM, and provenance metadata. Unix installs verify checksums before extraction.
• Local-first control plane — IPC listens on loopback only (127.0.0.0/8 / ::1). The MCP sidecar is read-only stdio with no network listener in its first shipped slice.
• Verifiable automation — Structured snapshots, event positions, deterministic waits, and control receipts. Unsupported operations fail explicitly instead of returning false success.
• Portable on six targets — Windows, macOS, and Linux on x86_64 and aarch64. Portable zip on Windows; one-line user-scope install on Unix.

Current highlights

• Native Win32/GDI UI with hierarchical team tabs on the left.
• Compact, scrollable tree-first sidebar with two-line names/notes and a draggable width boundary.
• Terminal toolbar keeps <Tabs/>Tabs and New at the left while anchoring an isolated Control Center in the middle and Settings at the right.
• agenterm-cc is the replaceable Control Center projection for Cockpit, Workflows, Extensions, and InfoHub. Its offline snapshot reports unavailable providers truthfully; closing or crashing it does not own terminal state.
• Terminal-scoped bottom status surface is ready for metrics and agent context providers without consuming the full-height Tabs column.
• Branded Windows icon and a persistent terminal font/size settings panel.
• cmd.exe is the default shell.
• Two-line tabs separate program/terminal TITLE from a user-maintained note.
• Tabs can be nested as agent/program teams without coupling process lifetimes.
• Normal app restarts restore the tab tree, names, notes, drafts, commands, and active tab; PTY commands restart as new processes.
• Exited processes leave a [dead] tab until the user explicitly closes it.
• Every tab owns a composer text box and Send button.
• New opens a configuration surface for shell profile and initial command; retained HTTP(S) proxy drafts are temporarily inert pending a later design.
• Local CLI can create, select, rename, inspect, capture, and drive tabs.
• Mouse-wheel history, a draggable scrollbar, and highlighted terminal text selection share the same viewport; selected text copies to the Windows clipboard.
• Snapshot-positioned bounded event reads and waits expose explicit restart, gap, and timeout results.
• agenterm cli script is the task and worker face for repository automation (.qjs under scripts/qjs/), observable Fleet tools, and versioned named tasks. The rh engine and its scripts/rh/*.rh corpus moved out to partnernetsoftware/rh on 2026-08-29; archived Rhai sources live under scripts/archive/rhai/. agenterm rh and agenterm qjs answer with where their verbs went.
• agenterm cli acu [--timeout-ms N] [ARGS...] is the Bun-free compatibility entry for typed computer use. Its qjswasm source is built into AgenTerm, so it works outside the source checkout and never falls back to the archived MCU runtime. The worker envelope defaults to 650 seconds so CU's narrower provider-owned deadlines remain authoritative. Put --timeout-ms N before the legacy verb to tighten that envelope or admit an operation longer than 650 seconds; a same-named option after the verb remains that verb's option.
• agenterm cli mcp is the on-demand read-only MCP surface (no separate agenterm-mcp PE). Its first v0.1.10 slice serves four metadata-only Fleet resources and one bounded agenterm_wait tool over stdio; it exposes no mutation tool or network listener.
• agenterm server proves the headless workspace/PTY/parser/event authority required for replaceable GUI work.
• new-agent launches Codex in a named fleet tab with stable AgenTerm context.
• Tab-scoped environment and proxy values apply only to the child process and are not written to the persistent workspace.
• agenterm cli mux provides the supported tmux/RMUX session/window surface (no separate agenterm-mux PE); unsupported operations fail explicitly.
• Whole-window and per-pane PNG screenshots support visual feedback testing.
• PTY process management uses rmux-pty.

Install

macOS & Linux

One line — no sudo, checksum-verified, commands linked into ~/.local/bin:

curl -fsSL https://raw.githubusercontent.com/partnernetsoftware/agenterm/main/install.sh | bash

The installer resolves the latest GitHub Release, verifies SHA-256 before extraction, keeps versioned payloads under ~/.local/share/agenterm, and starts the GUI when a graphical session is available. On macOS it also creates ~/Applications/AgenTerm.app.

Pin a version or install without launching:

curl -fsSL https://raw.githubusercontent.com/partnernetsoftware/agenterm/main/install.sh \
  | AGENTERM_VERSION=v0.1.14 AGENTERM_NO_LAUNCH=1 bash

macOS developer preview

v0.1.14 ships macOS as a labeled unsigned developer preview. The installer never selects it silently. Read the unsigned-preview security notes, then opt in:

curl -fsSL https://raw.githubusercontent.com/partnernetsoftware/agenterm/main/install.sh \
  | AGENTERM_ALLOW_UNSIGNED_PREVIEW=1 bash

Windows

Download the portable zip for your CPU architecture from GitHub Releases, extract it anywhere, and run agenterm.exe. All four client binaries plus build metadata ship in the same folder — no installer and no admin rights required.

Architecture	Asset
x86_64	agenterm-<version>-windows-x86_64.zip
arm64	agenterm-<version>-windows-aarch64.zip

The installer exits without changing the active installation when the selected release has no package for the current platform. List all installer overrides with:

curl -fsSL https://raw.githubusercontent.com/partnernetsoftware/agenterm/main/install.sh \
  | bash -s -- --help

Build and run

.\build.bat
.\dist\agenterm.exe

On macOS, build and install local binaries as a real application bundle:

./build.sh
./install.sh --local-build target/debug
open ~/Applications/AgenTerm.app

Pin AgenTerm.app, not target/debug/agenterm, in the Dock. Finder launches a bare executable through Terminal, which produces a Last login shell window before AgenTerm starts. The local installer copies the build into the versioned user installation, refreshes ~/.local/bin, and creates the stable ~/Applications/AgenTerm.app Dock entry. This explicit local path does not weaken signature verification for downloaded Release packages.

The default build is release-fast: optimized PE staged into dist/ (no LTO, parallel codegen, incremental under target/release-fast/). Debug PE stays in target/debug/ (cargo build or .\build.bat dev). Use .\build.bat release only for a distributable build; it applies the size-focused profile in an isolated target-release/ scratch directory, stages the finished artifacts in dist/, and then clears only that scratch cache while preserving the incremental development target/. All modes stage the ignored executable set, runtime library, and build metadata under dist/:

The thin build.bat / build.sh stage-0 reuses a content-validated, last-known-good copy of the main agenterm outside Cargo output and runs the real build as agenterm cli script task run build. A clean machine or CI runner seeds that cache with cargo build --bin agenterm. When source identity changes, stage-0 attempts a compatible refresh but retains the prior verified copy if that seed fails, so broken product source cannot destroy the recovery runtime. There is no second shell-owned build policy. The build/check/lint/ release tasks themselves are dark since rh moved out (2026-08-29) until their .qjs ports land; see prd/PRD_02_10_rhai_scripting.md.

• dist/agenterm.exe — GUI application and agenterm cli entry; agenterm server starts the headless authority as a separate process of the same PE. agenterm cli script is the script face; agenterm lua|sql are the remaining engines' dev CLIs (the standalone per-engine binaries were retired 2026-08-09, and rh moved out 2026-08-29).
• dist/agenterm-cc.exe — isolated Control Center projection; informational commands include --help, --version, capabilities --json, and snapshot --json.
• dist/agenterm.com — synchronous CUI and TUI forwarder to agenterm.exe: a minimal Windows Console-subsystem PE. Windows command resolution selects it for extensionless agenterm cli and agenterm tui, while all behavior remains implemented by agenterm.exe.
• dist/agenterm-cu.exe — computer-use CLI and Windows notification-area host. It is the sole computer-use executable; CLI, menu, and global placement shortcuts share one command executor.
• dist/agenterm.dll — shared native mechanism ABI loaded by agenterm-cu for window, input, screenshot, and accessibility operations.
• dist/agenterm.json — version, UTC build time, Git state, Rust target, size, and SHA-256 metadata.

Run the complete quality gate:

.\check.cmd

Smoke tests inherit AGENTERM_NO_ACTIVATE=1, so their isolated GUI windows do not interrupt the foreground application. .\check.cmd --release omits the 4,128-write event-journal load test; the clean GitHub release runner adds --include-stress.

The machine-readable platform contract is available without starting a server:

.\dist\agenterm cli protocol-info

Its platform block reports the native adapter, contract revision, and typed Window/Input/IME/Clipboard/Font/Screenshot/Activation/Integration status. Missing behavior is reported as unsupported or failed, never silently relabeled as available.

Linux GUI

Native Linux agenterm and agenterm-cc use winit. Control clients (agenterm cli) do not need display libraries.

Release tarballs ship a small lib/ directory plus agenterm and agenterm-cc launchers that set LD_LIBRARY_PATH before starting their hidden native binaries, so end users do not need sudo apt install for X11/Wayland keyboard libraries.

Slim X11 desktops (hosts with libxkbcommon0 but without libxkbcommon-x11-0 / libxcb-xkb1) are supported without a full tarball: the Linux GUI binary embeds those two runtime-only libraries and stages them on first X11 launch when the host omits them.

Six-cell delivery (build all {win,lnx,osx} × {x86_64,aarch64} from one host, package native archives with .sha256 sidecars, optional experimental agenterm-ape.com launcher):

AGENTERM_BOOTSTRAP_TASK=client-build-all ./scripts/bootstrap.sh release-fast
AGENTERM_BOOTSTRAP_TASK=six-cell-qualify ./scripts/bootstrap.sh release-fast
AGENTERM_BOOTSTRAP_TASK=package-six-cell-delivery ./scripts/bootstrap.sh release-fast

Receipt: target/qualification/six-cell/delivery-manifest.json. APE packer: research/agenterm-com-loader/.

Building from source on a minimal host still needs the same libraries available to the linker/runtime (CI installs them automatically):

sudo apt-get install -y \
  libxkbcommon0 libxkbcommon-x11-0 libwayland-client0 \
  libx11-6 libxcb1 libxcb-xkb1
./scripts/build-linux-clients.sh
DISPLAY=:1 ./target/x86_64-unknown-linux-gnu/debug/agenterm

The Unix GUI rasterizes a platform system monospace font with anti-aliasing and uses a system CJK fallback when available; the built-in bitmap-8x8 remains a startup-safe fallback. terminal.font-size is a logical point size that scales both glyphs and grid density, while Retina backing pixels are handled separately. On HiDPI displays the terminal content layer is rasterized again at the native framebuffer resolution instead of enlarging 1× glyph pixels. The configured terminal.font-family remains stored for Windows parity; the Unix Settings panel reports the resolved system renderer as read-only. New macOS profiles default to 14 pt; other platforms retain the 12 pt default. macOS and Linux input-method events are enabled explicitly: composed Unicode text is committed only after candidate selection, with visible preedit feedback anchored to the active terminal or editor field. The Unix renderer also honors DECSCUSR cursor shape and blink requests for block, underline, and bar cursors, including steady variants. Terminal colors preserve theme-aware defaults, all 256 indexed xterm colors, and 24-bit SGR foreground/background values. SGR bold, dim, italic, and underline attributes remain compact in the terminal grid and render consistently with Unicode sequences and truecolor output.

Examples

$r = ".\dist\agenterm"

& $r cli new-window -d -n build
& $r cli set-composer -t build "cargo check"
& $r cli send-composer -t build
& $r cli wait-pane -t build --contains "Finished" --timeout-ms 30000
& $r cli capture-pane -p -t build
& $r cli scroll-pane -t build page-up
& $r cli screenshot-pane -t build -o build.png

# Discover and run the bounded scripting surface.
& $r cli script api --json
& $r cli script eval "40 + 2"
& $r cli script eval "fleet.ui.snapshot().event_position.sequence" --profile observe

# Discover every registered server, then target one explicitly.
& $r cli server-list
& $r cli --address 127.0.0.1:48915 ui-snapshot

# Proxy flags are temporarily inert; configure proxy variables in the shell.
& $r cli new-agent -n reviewer -- --full-auto

# Explicit opt-in convenience for Codex's unsafe bypass mode; omitted by default.
& $r cli new-agent -n scratch --yolo

# Inspect the honest mux compatibility matrix.
.\dist\agenterm cli mux compatibility --json

IPC listens and connects only on numeric loopback addresses (127.0.0.0/8 or ::1), including explicit agenterm cli mux --address overrides.

Release

Keep Cargo.toml's version current, commit the release state on main, then run the local validation/rehearsal:

.\lint.cmd
.\release.cmd --rehearse

Public delivery is an exact-SHA two-stage GitHub Actions flow:

1. Release Candidate qualifies one explicit commit once and seals all six platform archives, hashes, SBOM, provenance, and the Windows qualification receipt into an immutable Candidate artifact.
2. After explicit release approval, Release verifies and promotes those same bytes without rebuilding, retesting, repackaging, or overwriting an existing tag/Release.

release.cmd is validation/rehearsal only and intentionally refuses local publication. Candidate dispatch may be automated by an authenticated GitHub Actions client; public Promotion remains a separate human approval boundary. Git/GCM authentication used by git push is not GitHub Actions API authentication.

Inspect a Windows PE or the Console-subsystem agenterm.com with Windows' own trust policy and machine-readable output:

For a quick visual check, right-click the file and open Properties → Digital Signatures → Details → View Certificate. If the Digital Signatures tab is absent, the file has no embedded Authenticode signature. Use the command below for the machine-readable release verdict:

.\scripts\inspect-authenticode.ps1 .\agenterm.exe `
  -ExpectedProductName AgenTerm -ExpectedProductVersion '<VERSION>'

Exit 0 means a valid PARTNERNET SOFTWARE PTY LTD signature, trusted timestamp, and matching requested VERSIONINFO; 2 means unsigned. On macOS/Linux, scripts/inspect-authenticode.sh ./agenterm.exe provides a portable certificate/timestamp diagnostic through osslsigncode: exit 2 means no extractable signature, while 3 means a signature exists but portable verification failed (which may be a local CA-chain gap). Windows remains authoritative. When using an independently verified Microsoft Artifact Signing root-plus-timestamp-CA PEM bundle on a host whose CA bundle lacks it, pass --ca-file ./trust.pem; create it with scripts/fetch-microsoft-trust-bundle.sh ./trust.pem. This does not modify system trust. The public v0.1.16 files are unsigned; a qualification artifact is not a signed Release unless its exact bytes are later sealed and promoted under the checked-in signing policy.

Publisher authority, signed-file scope, receipt privacy and Candidate/Promotion boundaries are defined in Code signing policy.

Documentation

• Product tree and requirements
• Code signing policy
• Coding-agent guide
• Build and install a local macOS app

agenterm-dyn library cache bound

Each Dyn environment retains at most 32 distinct dlcall library names. Entries are never evicted or unloaded while that environment lives, so an already cached exact name remains usable at capacity. A 33rd distinct name returns a library error before its argument expressions run and before a loader call is attempted; create a fresh Dyn environment to use a different library set.

agenterm-dyn binding bound

Each Dyn environment retains at most 4,096 distinct bindings, whether introduced through Rust bind or S-expression set. Replacing an existing name remains valid at capacity. A new name returns DynError::StateLimit { resource: "bindings", limit: 4096 }; set reports that error before evaluating its right-hand side, so a rejected assignment cannot run nested side effects.

agenterm-dyn name and symbol bounds

All Dyn binding, interned-symbol, library, and native-symbol names accept at most 255 UTF-8 bytes and reject interior NUL. Each environment retains at most 4,096 distinct interned symbols; Dyn::intern returns a Result and reports a name or state-limit error for a new rejected name, while existing symbols remain reusable at capacity. bind reports the same name errors; script NUL fails parsing, and set rejects an overlong target before its right-hand side runs.

Placeholder TUI

Run agenterm tui to open the initial terminal interface. It currently shows an intentionally small placeholder workspace; press q or Enter to return. On interactive cmd.exe, run agenterm tui; agenterm.com keeps the shell waiting so it does not compete with the TUI for console input. Explicit agenterm.exe tui retains the Windows GUI-subsystem waiting limitation.