From 36b295b94a7bb925e8190620043ec35c9e940fef Mon Sep 17 00:00:00 2001 From: cstaszak <6634045+cstaszak@users.noreply.github.com> Date: Thu, 21 May 2026 18:14:39 -0700 Subject: [PATCH] =?UTF-8?q?ASH-221:=20expand=20README=20Why=20=E2=80=94=20?= =?UTF-8?q?measurability,=20safety,=20wall-time?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Why section argued ash mostly on token efficiency. Added three motivations that a single consistent entry point uniquely enables: - "No usage ledger" bullet — fragmented tools share no seam, so a concise performance-and-usage history of a session cannot be assembled at all. - "No safety chokepoint" bullet — every utility touches the filesystem directly; nowhere to interpose path validation or a soft jail. - The "ash is the response" paragraph now makes the wall-time point — one entry point is one place to optimize (warm daemon, no per-command process spawn, no environment re-probing) — and the ledger sentence covers latency so "is this faster?" is as answerable as "is this saving tokens?". Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 896a0eb..76293e0 100644 --- a/README.md +++ b/README.md @@ -14,9 +14,11 @@ Coding agents today drive bash. Bash was designed in 1989 for humans at terminal - **Platform variance.** `find` differs between macOS and GNU. `sed -i` takes different arguments. `grep -P` may or may not exist. Agents waste turns probing the environment. - **State traps.** `cd`, environment variables, subshells, and globbing all introduce silent state that agents lose track of across turns. - **Tool fragmentation.** Is `rg` installed? `fd`? `jq`? `bat`? Every project's agent has a different available toolset, and the agent has to discover it on every fresh start. +- **No usage ledger.** A loop of `rg`, `fd`, `jq`, and `git` is a dozen unrelated processes with no shared seam. There is no place to record what each call costs — tokens, latency, truncation, error class — so a concise performance-and-usage history of a session cannot be assembled from fragmented tools at all. +- **No safety chokepoint.** Every utility reads and writes the filesystem directly. There is nowhere to interpose — no single entry point where a path could be validated, scoped to a project, or denied before the operation runs. Guardrails like a soft project jail have nowhere to live. - **No semantic operations.** Agents repeatedly grep for symbols when they actually want callers, definitions, or references — semantic queries that no shell utility provides. -`ash` is the response: a shell where the primary user is a model with a token budget, no eyes, and no hands. The verb surface is small enough to fit in a tool description. Every result is structured, every operation is the same on every platform, and the wire format is chosen for tokenizer efficiency. Every call is recorded in a per-project SQLite ledger with real cl100k_base token counts, so "is this saving tokens?" is an answerable question. +`ash` is the response: a shell where the primary user is a model with a token budget, no eyes, and no hands. The verb surface is small enough to fit in a tool description. Every result is structured, every operation is the same on every platform, and the wire format is chosen for tokenizer efficiency. One consistent entry point is also one place to optimize — a warm daemon, no per-command process spawn, no environment to re-probe — so what ash cuts is wall-clock time, not just tokens. Every call is recorded in a per-project SQLite ledger with real cl100k_base token counts and latency, so both "is this saving tokens?" and "is this faster?" are answerable questions. ## Quick start