Skip to content
Allie Coleman edited this page Jul 16, 2026 · 6 revisions

shoal

shoal

shoal is an agent-first, structured shell. It replaces the pipe with a dot-chain over typed values, replaces PATH with content-addressed tool resolution (Reef), replaces ambient capability with an explicit sandbox (Leash-and-Security), and exposes every session over an MCP-native wire protocol so an AI agent never has to scrape a wall of bytes to know what happened (Agent-Surface). One kernel evaluates one typed value graph; a human terminal, an agent over JSON-RPC/MCP, and a committed .shl script are three renderings of the same session, never three different languages.

Status: early, under active development. shoal is a v0.1 implementation of the contract in docs/TDD.md. The language core, command runner, interactive REPL, journal/CAS + undo, reactive streams and in-language channels (bridged onto the kernel's own wire event bus), interpreter blocks, the agent surface (elision, resources, events, MCP tools), data namespaces (json/yaml/toml/csv/math/ http/os/config), use modules, plan/apply/undo out[n], leash filesystem enforcement (Landlock on Linux, Seatbelt on macOS), 42 adapters, a jump/j frecency cd with a pushd/popd/dirs directory stack and cd -, an opt-in REPL output pager, and the shoal-prompt renderer are real and tested (see the 1,200+-case conformance corpus). Honestly still open (see docs/ROADMAP.md for the full, current list): binary-content-hash spawn-identity pinning is designed and unit-tested but not yet wired into the real spawn path (filesystem/network confinement above is real and separate from this); bare-path runner ergonomics beyond .shl. Pages below say so explicitly where it matters. It is not ready to replace your login shell yet.

Why leave the box

The Unix shell is a text-stream router between processes: bytes on a pipe, PATH as a flat mutable global, heredocs to smuggle a program into stdin, and a bash tool that dumps a wall of text into an agent's context for it to re-parse by regex. shoal rips each of these out at the root instead of shimming them:

The box (Unix) shoal
Byte streams, structure re-guessed Typed values, structure never lost
Pipe (untyped byte hose) Dot-chain over typed values (ls.where(.size > 1mb))
PATH (flat mutable global) Reef: scoped, content-addressed, locked resolution
Heredoc / -c "…" stdin smuggling Values as stdin (.feed), interpreter blocks (python { … })
tail -f / file-watch polling Reactive streams + kernel channels — subscribe, never poll
History = the text you typed Journal = what happened (AST, effects, resolution, hashes)
Bash tool dumps a wall of bytes Refs + shapes; payload pulled or pushed on purpose
Permission = who can read the FS [[Leash-and-Security

See docs/VISION.md for the full frame — every design decision in this wiki is an instance of it.

Documentation

  • Language-Reference — lexical structure, the CMD/EXPR two-mode dispatch, literals (including size/duration/time units), strings and interpolation, operators and the coercion matrix, control flow, functions-as-commands, lambdas, dot-chain composition, match, error handling, and the teaching diagnostics (no pipe, no $, no truthiness).
  • Execution-Model — the PTY position rule (statement vs. value position), outcomes, the value model, streams, tasks/spawn/jobs, and cwd/env/with scoping.
  • Reef — content-addressed tool resolution: why PATH is a fossil, scoped manifests, the lockfile, providers, the synthesized child PATH, and runners.
  • Agent-Surface — the MCP/wire contract for agents: the anti-bash-tool doctrine, refs, resources, events, channels, the elision rule, $-tag value encoding, and pair-shelling.
  • Kernel-and-Agents — the session kernel, client multiplexing, the journal/CAS, and the JSON-RPC socket protocol.
  • Leash-and-Security — the capability/effects model, plan → apply, and the honest enforcement tiers (Landlock/seccomp on Linux, Seatbelt on macOS).
  • Ecosystem-and-Tooling — declarative adapters, the reef provider pack, CI, and releases.
  • Developer-Guide — building from source, the crate map, running the conformance corpus, and contributing.

Try it

cargo run -p shoal
cargo run -p shoal -- -c $'let answer = 6 * 7\nanswer'
cargo run -p shoal -- script.shl
let names = ["ada", "grace", "linus"]
names.where(.len() > 3).map(.upper())

fn deploy(env: str, dry: bool = false) {
    echo deploying (env) --dry=(dry)
}

let result = sh { printf '{"ok":true}' }
result.out.ok

Clone this wiki locally