agsh, Aegis Shell, is a modern POSIX-style shell written from scratch in Rust for developers and AI coding agents. It is bundled as the default shell of Agents UI and runs standalone in any terminal.

Does agsh replace normal command behavior?

No. agsh runs external commands normally and preserves byte-exact pipes and redirects. Agent-oriented output modes are display and observation layers, never byte transforms.

v0.2.0 — the resilience release The default shell of Agents UI

The shell that never loses your work — and speaks fluent agent.

Q: How do I install agsh?

Install the prebuilt binary with curl -fsSL https://raw.githubusercontent.com/FusionbaseHQ/agsh/main/install.sh | sh, or build from source with cargo build --release.

A modern POSIX-style shell, written from scratch in Rust, for humans and AI coding agents. Your commands run unchanged, your sessions survive closed laptops, and your agents burn fewer tokens.

curl -fsSL https://raw.githubusercontent.com/FusionbaseHQ/agsh/main/install.sh | sh

macOS arm64 / x86_64 · Linux x86_64 / arm64 · checksummed · no sudo · installs to ~/.local/bin

Install agsh View source on GitHub

agsh — ~/api

~/api main ❯ keep -- npm run dev kept job [k1] — closing this terminal only detaches it ~/api main ❯ semantic cargo test { "status": "failed", "headline": "exit 1: 2 failure-like line(s)", "raw_stdout": "trace://cmd_42/stdout" } ~/api main ❯ confine read-only -- python analyze.py read + run only — writes, network, secret reads denied ~/api main ❯ agenv restore API_* restored API_URL=https://api.internal restored API_REGION=eu-central-1

Real prompt, real commands — keep, semantic, confine, agenv, and durable reattachment.

~6 MBstatic binary, stripped

0 unsafeforbidden in every first-party crate

674 testsplus golden, differential & PTY suites

198/200bash parity · sh 43/43, every commit

14 cratesRust workspace, 61 dependencies

AGPL-3.0open source, by Fusionbase

Proof by command

Three commands explain why agents need their own shell.

Every other shell welds three lifetimes together: the terminal, the shell state, and the processes. Close the window and all three die. agsh separates them — and adds the observation layer agents have been missing.

Durable work

Close the window. Keep the process.

~/api main ❯ keep -- npm run dev
kept job [k1] — survives this terminal
~/api main ❯ keep attach k1
attached — scrollback replayed · Ctrl-] detaches

A per-user broker (agshd) owns kept PTYs, so a dev server or a three-hour agent run is not tied to the window that launched it. agsh --keep keeps the whole session.

Agent output

Give the agent signal, not a wall of text.

~/api main ❯ semantic cargo test
{
  "status": "failed",
  "headline": "exit 1: 2 failure-like line(s)",
  "raw_stdout": "trace://cmd_42/stdout"
}

Family-aware compactors for git, cargo, docker, package managers, and compilers reduce context waste — while every raw byte stays recoverable behind trace://.

Hard boundary

Put a kernel under risky commands.

~/api main ❯ confine read-only -- python analyze.py
read + run only — writes, network, secrets denied
~/api main ❯ confine offline -- npm test
network off — everything else normal

confine uses kernel enforcement (macOS Seatbelt today, Linux Landlock planned) and fails closed instead of running a payload it cannot restrict. No LLM judgment calls.

Token economy

One command. You choose how much of it your agent sees.

Seven output modes — per command (semantic cargo test), per invocation (agsh --output compact -c …), or as a session default (mode:output compact). Pipes and redirects always get exact bytes.

cargo test — raw

~/api main ❯ cargo test
   Compiling api v0.4.2 (/Users/dev/api)
    Finished `test` profile in 4.82s
     Running unittests src/lib.rs
running 212 tests
test auth::login ... ok
test auth::logout ... ok
test auth::refresh ... ok
test billing::invoice ... ok
test keep::attach ... FAILED
test keep::detach ... ok
test keep::replay ... FAILED
test sessions::discover ... ok
… 199 more lines …
test result: FAILED. 210 passed; 2 failed

Everything, byte for byte — 212 lines land in the agent’s context.

~/api main ❯ compact cargo test
test result: FAILED. 210 passed; 2 failed; finished in 4.82s
  ✗ keep::attach — assertion failed: replay.len() > 0
  ✗ keep::replay — broken pipe talking to broker
[210 passing lines elided · raw → trace://cmd_42/stdout]

The cargo-aware compactor keeps failures and the verdict — 4 lines.

~/api main ❯ semantic cargo test
{
  "command": "cargo test",
  "exit_code": 1,
  "status": "failed",
  "headline": "exit 1: 2 failure-like line(s)",
  "failures": ["test keep::attach ... FAILED", "…"],
  "raw_stdout": "trace://cmd_42/stdout"
}

A structured observation an agent can parse — with the raw bytes one trace:// away.

~/api main ❯ lossless-ref cargo test
[exit 1 · 212 lines · 14.8 KB] trace://cmd_42/stdout

One line now, every byte later — agtrace or cat the reference on demand.

~/api main ❯ silent cargo test
~/api main ❯

Exit code only — the prompt turns red, the output waits in the trace store.

Also: clean strips ANSI and progress noise, rich renders markdown, JSON, diffs & images for humans. Reducers are display layers — never byte transforms.

Daily driver

A prompt that reports, and an editor that keeps up.

Syntax highlighting as you type, a completion dropdown, ghost-text autosuggestions, reverse search, multi-line editing — and a prompt where every segment earns its place.

~/apicwd main*git + dirty ⇡2ahead (venv:api)python venv 1.5sif ≥ 2s ✗1last exit ❯red on failure

Git status comes from a time-bounded probe — the prompt never blocks on a big repo. Truecolor, 256 and 16-color aware; NO_COLOR honored.

keep -- npm run devDev server that survives terminal close and SSH drops.

agsh --keep / agsh --attachKeep the whole session; terminal death only detaches it.

resumeCrashed or rebooted? Restore cwd, env, aliases, functions — without re-running commands.

sessionsFind and resume Claude Code and Codex sessions started in this folder.

agview README.mdMarkdown, JSON, CSV, diffs, syntax-highlighted code and inline images in the terminal.

history --todayA search-first, syntax-highlighted history workbench with date filters.

agenv history API_* agenv restore API_* Find the newest matching exports in command history, then reapply them without hunting down or retyping values.

Install

Install agsh in 60 seconds.

Prebuilt binaries for macOS arm64/x86_64 and Linux x86_64/arm64 (static musl). The installer verifies checksums, needs no sudo, and installs to ~/.local/bin by default.

macOS arm64 macOS x86_64 Linux x86_64 Linux arm64

Pin a version with AGSH_VERSION=v0.2.0, change the target with AGSH_INSTALL_DIR. Or use it with zero setup inside Agents UI — it’s the bundled default shell.

Prebuilt binary

curl -fsSL https://raw.githubusercontent.com/FusionbaseHQ/agsh/main/install.sh | sh

Read first, then run

curl -fsSLO https://raw.githubusercontent.com/FusionbaseHQ/agsh/main/install.sh
less install.sh
sh install.sh

From source

git clone https://github.com/FusionbaseHQ/agsh.git && cd agsh
cargo build --release
install -m755 target/release/agsh ~/.local/bin/agsh

Trust model

A shell has to earn the right to sit in your PATH.

agsh is explicit about what it changes, what it never touches, and where enforcement happens.

Normal commands stay normal.

No silent replacement of ls, git, or python. Pipes and redirects receive exact bytes. agsh’s own tools are ag-prefixed only where a bare name would shadow a real CLI.

Observations are not transformations.

Compact, semantic, and lossless-ref modes describe output for humans and agents while raw streams remain recoverable behind trace:// references.

Compatibility is tested directly.

Differential parity against bash (198/200) and sh (43/43) on every commit, plus golden checks and PTY suites for the editor, completion, and rendering.

Sandboxing fails closed.

confine uses kernel-backed restrictions (macOS Seatbelt today; Linux Landlock planned). Where the real sandbox path is unavailable, agsh refuses the unsafe fallback.

Why not just tmux?

Not a multiplexer. The shell contract, with agent primitives built in.

Use it when the thing you need to make durable, observable, and confineable is the command itself — not another window layout.

Need Traditional shell tmux or screen agsh

Keep work alive Dies with the terminal Window survives if configured PTY broker owns jobs and whole sessions

Recover from a crash Gone Gone with the server resume replays journaled state — no re-running commands

Agent-readable output Raw stream only Raw stream in a pane Semantic observations with trace:// recovery

Command safety Trust the caller Trust the pane confine enforces kernel policy below the prompt

Shell compatibility Native Native shell inside pane POSIX-style parser, expansions, pipes, redirects, jobs

Under the hood

Built from scratch. Tested against real shells.

A 14-crate Rust workspace with unsafe forbidden in every first-party crate, split so compatibility, durability, output reduction, confinement, and trace storage are tested independently.

Parselexer, POSIX-style grammar, command-graph IR

Executebuiltins, expansions, jobs, byte-exact pipes

Observeraw · clean · compact · semantic · lossless-ref

PersistPTY broker, traces, scrollback, state journals

Constrainconfine policy below the prompt

Every commit, Linux + macOS

✓cargo clippy --workspace -- -D warnings

✓cargo test --workspace674 tests

✓golden checks36 .agsh files

✓differential vs bash198/200

✓differential vs sh43/43

✓interactive PTY suiteeditor · completion · render

0 panics across a 2,000-input adversarial fuzz of the parser.

agsh-core parser & IR agsh-exec state & executor agsh-broker kept PTYs agsh-output compactors agsh-policy confine agsh-store traces & journals agsh-tty editor & prompt + 7 more

Better together

The default shell of Agents UI.

Agents UI bundles agsh as its default shell. Because agsh emits OSC 133 command marks and OSC 7 directory reports natively, the app gets structured command blocks, live cwd tracking, and idle/running status for every session — no injected shims, no config.

Get Agents UI

Command timelineEvery command becomes a block with exit code and timing in the app’s session timeline.

Live cwd + statusThe sidebar and MCP API always know each session’s directory and whether it’s idle or running.

Standalone tooagsh is a normal shell — run it in any terminal, or non-interactively with agsh -c '…'.

FAQ

Questions before making it your default shell.

Is agsh only for Agents UI?

No. Agents UI bundles agsh as its default shell, but agsh runs standalone from any terminal with agsh, or non-interactively with agsh -c 'echo hello'.

Will it change what my commands do?

No. The design contract is that normal commands run normally. Output compaction, rich rendering, and semantic observations are opt-in display layers — never byte transforms for pipes, redirects, or files.

What survives a closed terminal — or a crash?

Commands under keep -- and sessions under agsh --keep stay alive under the broker; closing the window only detaches. If the host or broker itself dies, the interactive journal lets resume restore cwd, env, aliases, and functions without re-running commands.

How strong is confine?

Kernel-enforced where supported: on macOS agsh uses Seatbelt via sandbox-exec. Linux Landlock support is planned; until then the real sandbox path fails closed instead of running unconfined.

Start here

Make agsh the shell your agents inherit.

curl -fsSL https://raw.githubusercontent.com/FusionbaseHQ/agsh/main/install.sh | sh

Star on GitHub Get Agents UI