Repository navigation
Home

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),usemodules,plan/apply/undo out[n], leash filesystem enforcement (Landlock on Linux, Seatbelt on macOS), 42 adapters, ajump/jfrecencycdwith apushd/popd/dirsdirectory stack andcd -, an opt-in REPL output pager, and theshoal-promptrenderer are real and tested (see the 1,200+-case conformance corpus). Honestly still open (seedocs/ROADMAP.mdfor 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.
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.
-
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/withscoping. -
Reef — content-addressed tool resolution: why
PATHis a fossil, scoped manifests, the lockfile, providers, the synthesized childPATH, 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.
cargo run -p shoal
cargo run -p shoal -- -c $'let answer = 6 * 7\nanswer'
cargo run -p shoal -- script.shllet 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