For AI agents: the complete documentation index is available at https://a3s-lab.github.io/ash/en/llms.txt, the full documentation bundle is available at https://a3s-lab.github.io/ash/en/llms-full.txt, and this page is available as Markdown at https://a3s-lab.github.io/ash/en/index.md.
ash
  • English
  • next
      • OPEN SOURCE · RUST · CODING AGENT FIRST

      AI Native Shell.

      Typed requests for repository discovery, process execution, transactional edits, DAG parallelism, snapshots, and retrievable evidence.

      Read the docsWatch the command tour
      $ash run < .ash/task.ason
      ash / coding tasko:| / project
      ash run < .ash/07-project.ason
      06 / 06Project final evidence

      Keep full data at @7; retrieve only p/l/t

      Canonical request
      o:|
a:[@7,d,0,64,p,l,t]
      ✓ Result2 rows · retained=@7 · stable
      Task queue

      o:gSearch hitsdone

      o:rRead windowdone

      o:bParallel batchdone

      o:pDigest-guarded patchdone

      o:xRun regression testsdone

      o:|Project final evidencerunning

      Task complete6 operations · 1 compact evidence pack
      s:0
      ASH/1 · ASON/1 · PROJECT
      ASH/1 · 15 TYPED OPERATIONSPARALLEL RUN · STABLE MERGEASON · PROJECT ON DEMANDLINUX · MACOS · WINDOWS
      COMPLETE SURFACE

      One typed contract, from source reading to evidence

      ASH/1 separates discovery, execution, mutation, parallel work, state, and retrieval into budgeted, cancellable, auditable operations.

      01

      Workspace discovery

      Read explicit byte or line ranges, walk stable paths, and run bounded literal or regular-expression search.

      read · rlist · lsearch · g
      02

      Processes and cancellation

      Launch argv directly, capture both pipes, and clean up the owned process tree after timeout or cancellation.

      exec · xcancel · ktimeout
      03

      Guarded mutation

      Protect patches with BLAKE3 preimages; commit file create, copy, move, and remove as recoverable transactions.

      patch · pfs · fjournal
      04

      Parallel task graphs

      Run ready DAG nodes concurrently, skip failed descendants, drain independent work, and select errors by stable index.

      batch · bTokioRayon
      05

      Workspace state

      Capture a scoped manifest snapshot and compare the same scope as a deterministic delta.

      snapshot · sdeltaBLAKE3
      06

      Retrievable evidence

      Spill beyond a fixed memory ceiling; slice, search, project, materialize, or release with typed formulas.

      / · # · ?| · > · -spill
      07

      Model context

      ASON columns, path dictionaries, and explicit reductions save tokens while references preserve the full source.

      ASON×N · ×N#K⋯N
      08

      Trust and delivery

      Capability negotiation, one-time permits, transaction recovery, and signed updates span three systems and six native targets.

      capabilitiespermitsigned update
      Explore every capability and boundary
      CODING AGENT SKILL

      Teach a Coding Agent to use ash correctly

      The repository ships a reusable Agent Skill for exact ASON envelopes, operation selection, guarded edits, parallel workflows, and verification.

      Read the Agent integration guideView the Skill source
      AGENT SKILLProject skill
      .agents/skills/use-ash/SKILL.md
      1. 01Discover and read
      2. 02Digest-guarded mutation
      3. 03Tests and evidence retrieval
      Example invocationUse $use-ash to inspect this repository, make the requested change, and verify it.
      COMMAND WALKTHROUGH

      Watch ASH complete a coding task

      Scroll to move the terminal through each step. Every stage shows the real command, canonical request, compact result, and field-level notes.

      Scroll to select a step, or click any step to inspect it directly.
      Task execution windowStep 01 / 07
      ash run < .ash/01-search.ason

      Search for literal TODO; no shell process or free-form parsing

      Canonical request · .ash/01-search.ason
      t:1i:17o:ga{q,p,f}:TODO,[src],0u{tok,rec,ms}:256,64,30000
      Compact resultASON/1
      t:3i:17s:0p[1]{i,v}:1,src/lib.rsd[2]{p,l,c,t}:1,42,7,"TODO item"1,87,3,"FIXME item"z:0r:~
      Task execution windowStep 02 / 07
      ash run < .ash/02-read.ason

      Read the first 80 lines of src/lib.rs and retain its digest

      Canonical request · .ash/02-read.ason
      t:1i:19o:ra{p,m,o,n}:[src/lib.rs],1,1,80u{tok,rec,ms}:512,64,30000
      Compact resultASON/1
      t:3i:19s:0p[1]{i,v}:1,src/lib.rsd[1]{p,o,n,h,t,r}:1,1,15,aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa,"pub mod engine;",~z:0r:~
      Task execution windowStep 03 / 07
      ash run < .ash/03-batch.ason

      Node 1 searches; node 2 reads Cargo.toml after node 1 completes

      Canonical request · .ash/03-batch.ason
      t:1i:80o:ba[2]{i,d,o,a}:1,[],g,"a{q,p,f}:\nTODO,[src],0\n"2,[1],r,"a{p,m,o,n}:\n[Cargo.toml],0,0,32\n"u{tok,rec,ms}:64,16,30000
      Compact resultASON/1
      t:3i:80s:0d[2]{i,o,s,c,r}:1,g,0,0,@42,r,0,0,@5z:8r:~
      Task execution windowStep 04 / 07
      ash run < .ash/04-patch.ason

      Write pub only while src/lib.rs still matches the expected digest

      Canonical request · .ash/04-patch.ason
      t:1i:23o:pa{p,h,i,o,n,v,f}:[src/lib.rs],[aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa],[0],[4],[3],[pub],0u{tok,rec,ms}:512,64,30000
      Compact resultASON/1
      t:3i:23s:0p[1]{i,v}:1,src/lib.rsd[1]{p,s,h}:1,0,bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbz:0r:~
      Task execution windowStep 05 / 07
      ash run < .ash/05-test.ason

      Run cargo test --locked; a failure returns error windows and math omission markers

      Canonical request · .ash/05-test.ason
      t:1i:18o:xa{x,v,c,e,in,f}:cargo,[test,--locked],.,["RUST_BACKTRACE=1",-SECRET],~,0u{tok,rec,ms}:512,64,120000
      Compact resultASON/1
      t:3i:18s:5d{k,c,ms,o,e,ro,re}:0,101,842,~,"cargo test --locked\nrunning 200 tests\n⋯18\nerror[E0609]: no field `missing`\n --> src/lib.rs:42:9\ncompile crate-a\nlink crate-a\n×64#2\ndetail: field unavailable\nhelp: inspect schema\n⋯24\ntest result: FAILED\nfinished",~,@12e{c,q,p,x,a}:401,0,4,~,~z:11r:~
      Task execution windowStep 06 / 07
      ash run < .ash/06-snapshot.ason

      Capture the workspace; a later m:1 + r:@9 request returns only the delta

      Canonical request · .ash/06-snapshot.ason
      t:1i:24o:sa{p,d,m,r,f}:[.],64,0,~,0u{tok,rec,ms}:512,64,30000
      Compact resultASON/1
      t:3i:24s:0p[2]{i,v}:1,Cargo.toml2,src/lib.rsd[2]{p,c,k,z,h}:1,0,0,912,bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb2,0,0,244,ccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccz:8r:@9
      Task execution windowStep 07 / 07
      ash run < .ash/07-project.ason

      From @7, select table d, slice 0..64, and keep only p/l/t

      Canonical request · .ash/07-project.ason
      t:1i:44o:|a:[@7,d,0,64,p,l,t]u{tok,rec,ms}:256,64,30000
      Compact resultASON/1
      t:3i:44s:0d[2]{p,t}:src/a.rs,TODOsrc/b.rs,FIXMEz:10r:@7
      FORMULA SYNTAX

      The symbol is the operation

      Hover or focus a symbol for its note; tap to open on touch. Every operator has fixed operands and one canonical encoding.

      SIX FORMULAS · 126 B · 80 / 80 TOKENStiktoken-rs 0.12.0 · cl100k_base · o200k_base
      RUNTIME

      Tokio and Rayon share one budget

      Tokio handles processes, pipes, RPC, deadlines, and cancellation. Rayon handles search, hashing, diffs, and reduction. The governor bounds global, session, and request concurrency.

      Execution topologyLIVE / BOUNDED
      ASH/1 REQUEST
      HIERARCHICAL GOVERNOR
      IOTOKIO I/O PLANErpc · process · pipe · cancel
      CPURAYON CPU PLANEsearch · hash · diff · reduce
      STABLE MERGECANONICAL ASON
      HOST BUDGETSESSION BUDGETREQUEST BUDGETACTION PERMIT
      OUTPUT FORMAT

      ASON: compact, stable, retrievable

      Homogeneous records use columns, paths use dictionaries, and large values remain available by reference. Stable merge keeps output deterministic.

      ASON / CANONICALcolumns + refs
      s:0
a:search
d{p}:
0:"src/runtime.rs"
r{p,l,c}:
0,42,governor
0,88,stable_merge
z{shown,total}:
2,17
      CL100K / O200K0.62×compact row-object JSONRead the ASON format
      PERMISSIONS

      Risky actions require a one-time permit

      A permit binds the session, action, policy, and expiry. File transactions add digest checks, a journal, and rollback.

      SECURITY
      PLATFORMS

      Linux, macOS, and Windows

      x86-64 and ARM64 use the same protocol. Releases verify signatures, SBOM, provenance, installation, updates, and rollback.

      linuxmacoswindowsx86-64 + arm64
      INSTALL / LOCAL

      Choose a platform and copy the command

      This is a pre-release. Cargo can build from source; release installers exit until signed binaries are available.

      Read installation notesPRE-RELEASE · NO SIGNED BINARY
      RELEASE INSTALLERx86-64 · ARM64
      curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/A3S-Lab/ash/main/install.sh | sh

      Signed binaries are not published yet; the installer exits before download.

      DOCS AND SOURCE

      Start with the protocol, CLI, or source.

      Interfaces, architecture decisions, and implementation are public.

      Open documentationBrowse GitHub