docs menu: agent api
docsfor agents
agent api
The socket, SDKs and easl CLI that agents use to work on the board and reach each other.
on this page
Agents work on the board through the easl API.
pieces
| Piece | What it is |
|---|---|
| Socket | A local Unix socket, ~/Library/Application Support/Easl/easl.sock (mode 0600) |
| Schema | schema/easl-api.json: the method catalog and single source of truth |
| Python SDK | easl_sdk, for agents with a persistent Python REPL |
| TypeScript client | CanvasClient, used by the omp extension and from JS |
easl CLI |
For agents without a REPL. On PATH in every terminal tile |
| Skill | skills/easl/SKILL.md |
Each terminal tile sets:
EASL_ENV=1EASL_SOCKETEASL_TILE_ID: this tileEASL_BOARD_IDEASL_BOARD_ROOT: the board’s directory, the repository’s main checkout from any worktree
The clients read these.
the easl cli
Methods are namespace.method. Params take three forms:
--key value, parsed as JSON when possible.- A bare
--flagfor true. --json '{…}',--json @params.json, or@-for stdin.
easl methods # every method with its description
easl methods view.render # its params (types, defaults, required) and result
easl methods CodeProps # a type's props (any *Props: NoteProps, HtmlProps, …)
easl object.create --type note --json '{"props":{"markdown":"# Plan"}}'
easl get obj_… --as graph # object.get shorthand
easl render obj_… # view.render shorthand; prints the PNG path
Results print as JSON on stdout. Errors print code: message on stderr and exit 1.
the python sdk
from easl_sdk import canvas
board = canvas.board.get() # manifest of every object
note = canvas.object.create(type="note", props={"markdown": "# Plan"})["object"]
canvas.agent.wait(target="reviewer", timeout_ms=600000) # keywords are snake_case (CLI: --timeoutMs)
- Reserved words take a trailing underscore (
as_="graph"). - Errors raise
CanvasErrorwith a.code. help(canvas.<ns>.<method>)shows a method’s signature.
If a kernel lacks the tile’s environment, connect explicitly:
from easl_sdk import connect
canvas = connect(socket="…/easl.sock", tile="obj_…", board="brd_…")
the typescript client
const client = new CanvasClient({ socketPath, tile, board }); // all optional
await client.api.object.get({ id: "obj_…" });
Methods are client.api.<ns>.<method>({…}). Source: clients/ts/src/index.ts.
results and errors
Every result is an object. object.create, object.update and object.get return {object}, so the new id is result["object"]["id"]. Unknown prop keys, like colour, come back in warnings.
| Error code | Means |
|---|---|
not_found |
No such object, agent or board (or a code tile’s file or commit) |
conflict |
A stale rev. Re-read, re-apply, retry |
invalid_params |
An unknown or missing required param. The message lists the method’s params |
unavailable |
The app isn’t running, or a terminal has no running session |
unsupported |
Not supported for this object |
timeout |
agent.wait ran out of time |
After an app restart, the next call reconnects, waiting up to 15 seconds.
show work on the board
| To show | Create |
|---|---|
| Real code | code: {"path": "src/store.ts", "range": {"start": 41, "end": 60}, "caption": "restore replays the log"} |
| Notes, plans, findings | note: {"markdown": "…"} |
| A chart or figure | image: {"path": "out/fig.png", "caption": "…"} |
| An explainer or comparison | html: {"html": "…", "title": "…"} |
| What you changed | changes: {} with "size": "fit" |
| A web page | browser: {"url": "http://localhost:3000"} |
| Structure | shape, arrow, group |
easl object.create --type changes --json '{"props":{},"size":"fit"}'
Without a frame, an object lands next to the agent’s terminal (see agents). For deliberate layouts:
size: "fit"sizes a tile to its content.layout.place,layout.stack,layout.gridandlayout.translateposition objects. Groups move whole.object.batchapplies a layout as one ⌘Z step."$0"refers to an earlier op’s object.layout.checkreports overlaps, arrows through tiles, labels on tiles, content that doesn’t fit, and cut-off captions. An empty report is clean.
canvas.object.batch(ops=[
{"method": "object.create", "params": {"type": "code", "props": {"path": "src/a.ts", "range": {"start": 10, "end": 30}}, "size": "fit", "frame": {"x": 0, "y": 0}}},
{"method": "object.create", "params": {"type": "note", "props": {"markdown": "Why this matters"}, "size": "fit", "frame": {"x": 0, "y": 0, "w": 320}}},
{"method": "layout.place", "params": {"id": "$1", "near": "$0", "side": "below", "gap": 14}},
{"method": "object.create", "params": {"type": "group", "props": {"members": ["$0", "$1"], "title": "Request path", "color": "blue"}}},
])
For a walkthrough, join stops with "relation": "next_step" arrows (see navigation).
see the board
| Want | Call |
|---|---|
| Objects or a region, wherever the user is | view.render |
| What the user sees now, as pixels | view.snapshot |
| Where the user is looking, without pixels | view.get |
| What happened since you last looked | board.history |
easl render obj_… # one object (the board region under it)
easl render obj_a,obj_b --scale 2 # the region covering several
easl render 0,1200,2400,1600 --exclude '["terminal"]' # a board rect x,y,w,h
easl render obj_… --full # a note/HTML tile's whole content
view.render never moves your view. Without --out, it writes a PNG under $TMPDIR/easl-renders/ and returns the path.
point the user at something
Agents don’t move your view unless you ask. They raise an attention marker:
easl view.attention --id obj_… --message "The race is here" # → {"id": "obj_…", "active": true}
easl view.attention --id obj_… --clear # take it back
agent to agent
Reach any terminal’s agent, on any open board, by tile id or name:
easl agent.list # every terminal: tile, kind, name, lifecycle, board, root, program, title
easl agent.prompt --target reviewer --text "Review the diff in src/store.ts" # → waitable, submittedAt
easl agent.wait --target reviewer --timeoutMs 600000 # until idle/done/blocked
easl agent.read --target reviewer --since prompt # only what came after your last agent.prompt
agent.read --final truereturns only the last answer. omp, Codex, Claude Code and Gemini CLI before 0.60 report it. opencode doesn’t.mentionsonagent.prompthand off board objects as hidden context naming the sender (see mentions).
canvas.agent.prompt(target="fees", text="review the findings note against the code, read-only",
mentions=[{"object": note_id}, {"object": code_id, "lines": {"start": 41, "end": 48}}])
canvas.agent.wait(target="fees", timeout_ms=900_000) # done, idle, or blocked
reply = canvas.agent.read(target="fees", final=True)["text"]
agent.promptto a blocked agent fails withconflictand quotes what it waits on. You answer that approval.agent.waitsurvives an app restart. The clients retry once the app is back.
compositions
Both SDKs ship reusable helpers. Write your own as a plain module, ~/.easl/compositions/<name>.py (.ts for the TypeScript client), then call canvas.compositions.reload(). Yours shadow built-ins of the same name.
canvas.compositions.available() # name -> summary
canvas.compositions.grid.arrange([id1, id2, id3]) # grid beside your terminal, clear of other tiles
canvas.compositions.locations.open(["src/a.ts:12-40", "src/b.ts#L7"])
boards
easl board.open --root <absolute dir> # open a directory's board as a tab, behind the current one
easl board.list # every stored board, archived ones too
easl board.export # write <root>/.easl/board.json for committing
the skill
The skill teaches agents which client to use, where objects land, and how to read mentions, show changes and reach other agents.
Integrations offer it only inside easl (EASL_ENV=1). omp and Codex get its location. Claude Code loads it as the plugin’s easl:easl skill. Nothing goes into your global agent config.