OpenLang — Compact Agent-to-Agent Protocol

When communicating with other agents (via sessions_spawn, sessions_send, or announce), use OpenLang to compress messages 5-10x. Default to L2 for all agent-to-agent communication.

When to Use

• sessions_spawn task descriptions — compress the task prompt
• sessions_send messages — compress ping-pong exchanges
• Announce results — compress announce replies back to requester
• NOT for human-facing channels — use normal language for Telegram/Slack/user messages

Quick Start

Prefix any agent-to-agent message with ~openlang to signal the receiver should parse as OpenLang. If the receiver doesn't understand, it will still get the gist from the structural cues.

Compression Levels

Lvl	Name	Ratio	Use
~L1	Pidgin	3-5x	Fallback: compressed English for concepts grammar can't express
~L2	Glyph	5-10x	Default. Sigil-based structured communication
~L3	Bytecode	10-15x	Positional, period-delimited. Bulk ops only

Switch mid-message with ~L1:, ~L2:, ~L3:. Unspecified = L2.

Sigils

Sigil	Intent	Example
?	Query	?fnd @fs {p:"src/*.ts"}
!	Command	!del @fs {p:"tmp/"}
>	Result	>ok {n:3 paths:[...]}
#	State/Data	#ctx {lang:ts env:node}
~	Meta	~L2 ~ack ~err
^	Control Flow	^if {cond} {then} ^el {else}

Structure

@ target · -> pipe · {} params · << >> block scope · [] list · () group · | alt · .. range · :: type · $ variable · !~ negate value

Variables

Bind with ->$name, use with $name. Property access: $var.field.

Vocabulary

Actions: fnd find · mk make · del delete · mod modify · rd read · wr write · run exec · cpy copy · mv move · mrg merge · tst test · vfy verify · prs parse · fmt format · snd send · rcv receive

Scopes: @fs filesystem · @sh shell · @git git · @net network · @db database · @mem memory · @env environment · @usr user · @proc process · @pkg packages

Scoped actions: scope:action — !git:mrg vs !db:mrg

Modifiers: rec recursive · par parallel · seq sequential · dry dry-run · frc force · tmp temp · vrb verbose · sil silent · lmt limit · dep depth · pri priority · unq unique · neg negate

Qualifiers: rcn recent · lrg large · sml small · chg changed · stl stale · nw new · old old · act active · idl idle · fld failed · hlt healthy · hot hot · cld cold

Types: str · int · bln · lst · map · fn · pth · rgx · err · nul

Status: ok success · fl fail · prt partial · pnd pending · skp skipped · blk blocked

Control Flow

^if {cond} {then} ^el {else}        -- conditional
^lp {n:5} {body}                     -- loop
^ea {src} ->$item {body}             -- each/iterate
^par [!t1, !t2, !t3]                -- parallel
^seq [!t1, !t2, !t3]                -- sequential
^wt {cond} / ^rt {val}              -- wait / return
^br / ^ct                            -- break / continue
^frk:name {body}                     -- fork named task
^jn [names] ->$results               -- join/await
^lk:name / ^ulk:name                 -- mutex lock/unlock
^ch:name ::type buf:N                -- declare channel
^tx:name {v:$val} / ^rx:name ->$val -- send/receive channel
^tmo:N                               -- timeout (seconds)

<< >> for multi-statement bodies:

^ea {$files} ->$f <<
  ?rd @fs {p:$f} ->$content
  ^if {$content.sz>1000} {!mod @fs {p:$f trunc:true}}
>>

Composition

Chain with -> pipes, sequence with ; or newlines:

?fnd @fs {p:"*.ts" rgx:"parse"} ->$lst | ^ea ->$f !tst @sh {cmd:"vitest $f"} ->$rpt

Errors

~err {code:E_PARSE lvl:warn msg:"unknown token"}
~err {code:E_FS_NOT_FOUND lvl:fatal msg:"missing config"}

Codes: E_PARSE E_FS_* E_SH_* E_NET_* E_DB_* E_AUTH. Levels: info warn fatal.

Token Extension

~unk {tok:"xyz" req:def}             -- request definition
~def {tok:"xyz" means:"..."}         -- define inline

L3 Bytecode

Positional, period-delimited. Backtick-quote fields with periods:

Q.fs.fnd.`app.config.ts`.rec
R.ok.3.[`src/a.ts`:5,`src/b.ts`:12]

OpenClaw Integration Examples

sessions_spawn with OpenLang task

~openlang
?fnd @fs chg rcn {p:"src/**/*.ts" p:!~"*.test.ts" rgx:"TODO"} ->$lst
^ea ->$f {!rd @fs {p:$f} ->$content; !prs @mem {src:$content k:"todos"}}
>ok {summary:true fmt:map}

Announce result in OpenLang

~openlang
>ok {n:12 todos:[
  {f:"src/api.ts" ln:42 msg:"refactor auth flow"},
  {f:"src/db.ts" ln:18 msg:"add connection pooling"}
] truncated:10}
~L1: most TODOs are in api.ts and db.ts, concentrated around auth and connection handling

sessions_send ping-pong

-- Agent A -> Agent B
~openlang
?fnd @db {tbl:trades rcn lmt:100} ->$trades
!prs @mem {src:$trades k:pnl} ->$analysis
>ok {$analysis}

-- Agent B -> Agent A
~openlang
>ok {pnl:+2.3% win_rate:0.68 sharpe:1.42 trades:100
 top:{sym:"AAPL" pnl:+890} worst:{sym:"TSLA" pnl:-340}}

Rules

1. Default to L2 for all agent-to-agent messages.
2. Use normal language for human-facing channels (Telegram, Slack, etc).
3. Prefix with ~openlang so receivers know to parse as OpenLang.
4. Drop to L1 when grammar can't express a concept. Return to L2 immediately.
5. Use $ for all variable references.
6. Extend vocabulary with ~def — don't break grammar for new ideas.