skip to content
easldownload
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=1
  • EASL_SOCKET
  • EASL_TILE_ID: this tile
  • EASL_BOARD_ID
  • EASL_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 --flag for 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 CanvasError with 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.grid and layout.translate position objects. Groups move whole.
  • object.batch applies a layout as one ⌘Z step. "$0" refers to an earlier op’s object.
  • layout.check reports 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 true returns only the last answer. omp, Codex, Claude Code and Gemini CLI before 0.60 report it. opencode doesn’t.
  • mentions on agent.prompt hand 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.prompt to a blocked agent fails with conflict and quotes what it waits on. You answer that approval.
  • agent.wait survives 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.