OpenLang — Compact Agent-to-Agent Protocol

When communicating with other agents (via

sessions_spawn

sessions_send

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

Compression Levels

~L1

~L2

~L3

Switch mid-message with

~L1:

~L2:

~L3:

Sigils

?

?fnd @fs {p:"src/*.ts"}

!

!del @fs {p:"tmp/"}

>

>ok {n:3 paths:[...]}

#

#ctx {lang:ts env:node}

~

~L2

~ack

~err

^

^if {cond} {then} ^el {else}

Structure

@

->

{}

<< >>

[]

()

|

..

::

$

!~

Variables

Bind with

->$name

$name

$var.field

Vocabulary

Actions:

fnd

mk

del

mod

rd

wr

run

cpy

mv

mrg

tst

vfy

prs

fmt

snd

rcv

Scopes:

@fs

@sh

@git

@net

@db

@mem

@env

@usr

@proc

@pkg

Scoped actions:

scope:action

!git:mrg

!db:mrg

Modifiers:

rec

par

seq

dry

frc

tmp

vrb

sil

lmt

dep

pri

unq

neg

Qualifiers:

rcn

lrg

sml

chg

stl

nw

old

act

idl

fld

hlt

hot

cld

Types:

str

int

bln

lst

map

fn

pth

rgx

err

nul

Status:

ok

fl

prt

pnd

skp

blk

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)

<< >>

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

Composition

Chain with

->

;

?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

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.