clai — command-line artifact interpreter

grammar-driven systems interface.

see it run →

systems work scatters across incompatible surfaces. compilation here. execution there. inspection elsewhere. handles ephemeral. context lost between operations.

clai consolidates: same @handle across forge → exec → inspect → evolve. one interface, composable by construction.

grammar

clai <lane>:<surface>.<verb> [subject] [options] [@context] [| next...]

@context — stable URI handles; immutable; replacements retain lineage · @A = handle name · @A/B = child context · ^ = parent

lanes (forces)

forge — create artifacts from source
exec — control process liveness
inspect — read runtime state
evolve — mutate code transactionally

surfaces (scales)

atom → frame → module → program → graph → mesh → meta
(+ snapshot for frozen-topology state)

atom — instruction/branch level
frame — coroutine/thread
module — .so/.dylib/.dll
program — process
graph — topology of programs
mesh — distributed nodes
meta — clai itself

snapshot is orthogonal to the scale ladder — it captures frozen-topology state across any surface

examples

clai forge:module.c src/main.c

compile c source to module

clai exec:program.spawn bin/app --as @A

spawn process with handle @A

clai inspect:mem.map @A --at program

inspect memory map of @A

clai evolve:function.swap @A/factorial swap.c

evolve lane: transactional code mutation

clai inspect:mem.map @A | inspect:graph.view @.

pipeline: map memory then visualize

parser demo

grammar validator · returns parse tree (not execution)

{ "nstages": 1, "stages": [ { "lane": "inspect", "surface": "mem", "verb": "map", "context": "@svc", "at": "program", "flags": { "down": 0, "up": 0, "all": false } } ] }

syntax validation (click to parse):

inspect:program.handles --all forge:module.c test.c --opt=2 pipeline example error example

source

c99 parser. no heap. single pass.

quickstart

curl -O https://clai.ink/kernel/clai_parse.c -O https://clai.ink/kernel/clai_parse.h \
     -O https://clai.ink/kernel/demo.c -O https://clai.ink/kernel/Makefile
make
./clai_parse_demo "inspect:mem.map @svc --at program"

clai_parse.h (92 lines)

loading...

view raw

clai_parse.c (284 lines)

loading...

view raw

demo.c (23 lines)

loading...

view raw

Makefile (20 lines)

loading...

view raw

LICENSE (mit)

loading...

view raw

design foundations

grammar as contract — syntax determines behavior, eliminating ambiguity
handle stability — @uris immutable; mutations preserve lineage
force isolation — lanes never interfere (inspect only reads, evolve only mutates)
compositional default — pipes work because purity is enforced by grammar

invariants

lane purity — inspect never mutates, evolve is transactional
deterministic dispatch — (lane, surface, verb) → unique target or error
stable handles — uris immutable; replacements have lineage
explaining machine — clai explain always works
capability security — verbs gated by mask, defaults least privilege
structural persistence — topology + lineage, not heap dumps