Working with a coding agent

How a coding agent develops a Zeon project: the agent guide in the project, the zeon agent commands, the viewer and app links for the human watching.

A coding agent (Claude Code, Codex, or similar) can develop a Zeon project end to end: edit skills and workflows, sync them, run them in your cloud simulation, read the result and fix what failed. The zeon CLI is built for this: commands never prompt, every instance command takes --json, exit codes are stable, and every error ends with a next: line that says what to do.

Agents use the CLI; people use the web app

A coding agent works through the zeon CLI, not through the web app. The CLI is the supported path for agents: it is faster, it scripts, its output is text or JSON, and every error says what to do next. The web app is for people. zeon open prints a link for a person; an agent should not open it with browser tools to click, pan or zoom.

ToThe agent runs
see the scenezeon snap out.png (rendered on the instance), zeon look TARGET
check the project, world, skills and runszeon brief, zeon py '<code>'
run a skill or a workflowzeon run NAME
follow a runzeon wait ID, zeon logs ID -f
answer a run's promptzeon answer ID [CHOICE]
stop a runzeon stop ID
put the arms back after a failed run (Reset)zeon reset-arms

The starter's agent guide (AGENTS.md / CLAUDE.md) says the same.

The agent guide: AGENTS.md and CLAUDE.md

Each project carries a guide for coding agents, the same text in AGENTS.md (read by Codex and others) and CLAUDE.md (read by Claude Code). It covers the loop, the commands, the skill API conventions, and the rules below.

  • A project created with zeon new project gets the starter's guide, which also describes the starter's world, skills and workflow.
  • zeon clone and zeon init write both files when the project has none; --no-agent-guide skips that. They never overwrite an existing file, so you can edit the guide; zeon sync adds it to the project.

Keep the guide current: describe your deck, your protocol, and anything about your cell a new session could not infer from the files.

Optional: the zeon-projects agent skill

The zeon-projects skill gives an agent the project file formats, the skill API, the CLI loop and a local validator. In Claude Code, install it as a plugin:

/plugin marketplace add zeonsystems/zeon-project-skill
/plugin install zeon-project-skill@zeon

For agents that read skills from ~/.agents/skills (and Pi, from ~/.pi/agent/skills), clone it and link it:

mkdir -p ~/.agents/skills ~/.pi/agent/skills
git clone --template= https://github.com/zeonsystems/zeon-project-skill.git ~/.agents/skills/zeon-project-skill
ln -s ~/.agents/skills/zeon-project-skill/skills/zeon-projects ~/.pi/agent/skills/zeon-projects

git -C ~/.agents/skills/zeon-project-skill pull updates it.

REPL access

Most agent commands work for every account: zeon up, zeon down, zeon run, zeon wait, zeon stop, zeon reset-arms, zeon logs, zeon app. The commands that run code on the instance (zeon py, zeon brief, zeon snap, zeon say, zeon look) and the viewer link (zeon open) use the instance's REPL, which Zeon enables per account. Without it they exit with code 3 and say that REPL access is not enabled for the account; ask your Zeon contact. zeon up still loads the project and prints viewer: not available yet (...).

On your cloud instance the REPL:

  • runs the simulation only;
  • accepts code that uses the skill API (sim, sim.world, skills, snapshot, say, look, brief, and the motion and gripper functions skills use). A guard refuses code that reads platform internals, environment variables, credentials or Zeon's own files; the refusal exits with code 4, nothing runs, and the message says what to use instead. Code that uses only the skill API, skills, run_workflow, snapshot, say, look, gizmos, brief and plain Python (math, json, numpy, ...) is always allowed;
  • logs every entry and every run with your account.

An agent uses the REPL the way you do. See The REPL for what it is, how entries keep state, and the names it provides.

The loop for an agent

  1. zeon sync (or zeon push) sends the project to the cloud.
  2. zeon up loads it and its world on the instance and prints the viewer link for the human. Needed once, and again after the instance restarted.
  3. zeon brief: the project, the setup the instance runs, the loaded world and its objects, each arm's state (what it holds, whether it is at its start position), the active workflow, skills and workflows with their inputs, recent runs and their failures.
  4. Try things: zeon py '<code>' or zeon py -f scratch.py for quick checks; zeon run <skill> -i key=value or zeon run "<workflow name>" for a real simulated run. Runs are Fast at 8x by default (planned, then played back; --speed 1|2|4|8). Before the real robot, run the workflow once with --motion full --detach and zeon wait ID: the robot's control loops in real time.
  5. Look: zeon logs ID, zeon snap out.png, zeon brief.
  6. Edit, zeon sync (it refreshes the loaded project and prints instance refreshed; without that line, run zeon up), repeat from 3.
  7. zeon down when done.

A refused move names the move, the target and the reason (unreachable, would collide with a named object, joint limit, a straight line that cannot be made). Fix the target, the approach or the placement; do not retry the same move. A failed run's error ends with the skill, the node and the line of the skill's code that raised ([skill move_plate, node transfer, robotic_code.py:57]), and its next: line depends on what failed.

After a failed run the simulated world can be left half done, with an arm still holding or touching something (the next run fails with the arm starts with ... from '<object>'). zeon reset-arms puts both arms back at their start position with open grippers; zeon run NAME --world W then reloads the world before the run. A world reload alone does not move the arms.

Commands

CommandDefault waitWhat it does
zeon up [--project ID] [--world W]300 sLoad the pushed project and its world (default: active_world in project.json); print the viewer link.
zeon downRelease your instance. A run still going keeps it.
zeon brief60 sOrientation in one call.
zeon py 'CODE', zeon py -f FILE120 sRun Python in the REPL and print its output. -f - reads stdin. On timeout the entry is interrupted.
zeon run NAME [-i k=v ...] [--world W] [--kind auto|skill|workflow] [--motion fast|full] [--speed N] [--detach]120 sStart a simulated run and wait for it. NAME is a skill id, or a workflow id or display name (--kind auto prefers a workflow). Fast at 8x by default; --speed 1|2|4|8; --motion full runs the robot's control loops in real time (1x only). Ctrl+C cancels the run. On timeout the run continues.
zeon wait ID120 sWait for a run.
zeon stop ID60 sStop a run, as Stop in the app does, and wait for it to end. A stopped run does not resume.
zeon reset-armsPut both simulated arms back at their start position: grippers open, a held object let go where it is. Refused during a run.
zeon answer ID [CHOICE]Answer the run's open ask_user_slack prompt. Without CHOICE it shows the question and its options.
zeon logs ID [-f]120 s with -fThe run log; -f follows it until the run ends and exits with the run's outcome.
zeon snap [PATH] [--view sim]60 sSave a PNG of the simulation viewer (default .zeon/snaps/snap-<id>.png in a project folder, never synced; else snap-<id>.png). The instance renders it; no browser needs to be open.
zeon open [--browser]Print the 3D viewer link, the view to share with the people watching.
zeon app [W] [--run]Print the person's signed-in web app link: W's canvas, its run screen with --run, or the project.
zeon say "TEXT"30 sPost a message to the viewer's Agent panel.
zeon look TARGET [--seconds 6]30 sPoint the viewer camera at an object id, <holder>.<anchor>, or a preset, and highlight it.

Change a wait with --timeout SECONDS. For long runs use zeon run ... --detach, which prints the run id, then zeon wait ID or zeon logs ID -f.

A run that waits on an ask_user_slack prompt does not end by itself. A timed-out zeon run or zeon wait says so ("waiting_on_prompt": true in --json). zeon answer ID shows the question and its options; zeon answer ID CHOICE answers it (or a person answers in Slack or the app); then zeon wait ID. Ask the person watching when the answer is theirs to give.

-i key=value values are parsed as JSON when they parse (-i count=3, -i 'slots=["slot_1","slot_2"]'), otherwise taken as text. A workflow input you do not pass takes its declared default. An object input also takes a display name, or a type the world has one instance of. zeon run checks the name and the inputs before it starts the run: an unknown name or -i key (with did you mean ...?), a missing required input or a value of the wrong type is refused with exit 2 and nothing starts.

Run zeon run from the project folder: when the instance has another project loaded, it refuses (exit 2) and says to run zeon up. After zeon down, the next command that takes an instance again prints a notice: line saying so.

Long output (zeon py, zeon logs) is capped at 16000 characters inline (--max-chars, 0 for no cap). --out FILE writes all of it; when output is capped without --out, the message names a temporary file that holds the rest.

JSON output and exit codes

With --json a command prints one JSON object on stdout, errors included. Without it, an error prints error: ... and next: ... on stderr.

CodeMeaningWhat to do
0ok
1the entry or run failedRead the traceback or zeon logs ID, fix, run again.
2usage: bad arguments, unknown id or name, run inputs refused before the start, another project loaded, project not pushed yetzeon <command> --help, zeon brief, zeon up, zeon push.
3not signed in, token rejected, or REPL not enabled for the accountzeon login; ask your Zeon contact for REPL access.
4the REPL guard refused the codeRewrite it with the skill API.
5timed out, or stopped waitingzeon wait ID, --detach, or a larger --timeout.
6instance unavailable: starting, restarting, or no free instanceWait about a minute, zeon up, retry.

An exit code 6 in the middle of work usually means the instance restarted. Wait about a minute and run zeon up. A restart resets the simulated world to the saved world, so earlier runs' effects are gone.

For the human watching

The agent works on your instance; you watch it.

  • The 3D viewer. zeon up and zeon open print its link. zeon say posts to its Agent panel, and zeon look moves its camera.

  • Camera presets. When the default view of an object is blocked, add a preset to viewer.yaml in the project root, zeon sync, then zeon look NAME:

    presets:
      stands:
        look_at: wellplate_stand_1        # an object id or <holder>.<anchor>
        target: [0.40, -0.64, 0.08]       # world frame, metres; used when look_at does not resolve
        position: [1.30, -0.64, 0.80]     # where the camera stands
  • Web app links. zeon app W prints a link to workflow W's run screen on its Inputs tab, where W's canvas renders against the simulation (a workflow without a canvas gets its run screen); zeon app W --run opens the run screen (graph, inputs, log); zeon app alone opens the project. W is the workflow id or its display name. Options: --world W selects a world (default: the one the simulation has loaded), --project ID names another project (default: the folder's), --no-login-link prints the plain app link, --browser also opens the link locally.

    zeon app needs CLI 1.5.5 or newer; zeon open --workflow W / --canvas W still work and print a notice to use zeon app. The link is for the same account and opens on its instance. It is a login link: it signs the browser that opens it in, without a password, so it also works in a browser pane next to the agent. It works once and is valid for 5 minutes; for a fresh one, the agent runs the command again. The browser session lasts 12 hours and ends with zeon down, zeon logout or a sign-out in the browser. The link is personal: give it only to the person at the screen, not to a shared channel. To show the simulation to others, give them the zeon open viewer link. Adding &ui=operator to the link opens the app in operator mode. See Login links from the CLI. The link opens the pushed version, so zeon sync first. The CLI refuses the link unless the project is the one the instance has loaded (zeon up first), because opening another project would switch the instance under the agent. Opening the link never clears the simulated world.

    A page opened from such a link follows the agent's pushes: every few seconds it re-reads the workflow and its canvas and updates in place. It does not update during a run (it catches up after) or over unsaved edits in the page. When the canvas changed, its inputs reset and Run waits until you confirm the inputs again.


Did this page help you?