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.
| To | The agent runs |
|---|---|
| see the scene | zeon snap out.png (rendered on the instance), zeon look TARGET |
| check the project, world, skills and runs | zeon brief, zeon py '<code>' |
| run a skill or a workflow | zeon run NAME |
| follow a run | zeon wait ID, zeon logs ID -f |
| answer a run's prompt | zeon answer ID [CHOICE] |
| stop a run | zeon 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 projectgets the starter's guide, which also describes the starter's world, skills and workflow. zeon cloneandzeon initwrite both files when the project has none;--no-agent-guideskips that. They never overwrite an existing file, so you can edit the guide;zeon syncadds 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-projectsgit -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,briefand 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
zeon sync(orzeon push) sends the project to the cloud.zeon uploads it and its world on the instance and prints the viewer link for the human. Needed once, and again after the instance restarted.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.- Try things:
zeon py '<code>'orzeon py -f scratch.pyfor quick checks;zeon run <skill> -i key=valueorzeon 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 --detachandzeon wait ID: the robot's control loops in real time. - Look:
zeon logs ID,zeon snap out.png,zeon brief. - Edit,
zeon sync(it refreshes the loaded project and printsinstance refreshed; without that line, runzeon up), repeat from 3. zeon downwhen 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
| Command | Default wait | What it does |
|---|---|---|
zeon up [--project ID] [--world W] | 300 s | Load the pushed project and its world (default: active_world in project.json); print the viewer link. |
zeon down | Release your instance. A run still going keeps it. | |
zeon brief | 60 s | Orientation in one call. |
zeon py 'CODE', zeon py -f FILE | 120 s | Run 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 s | Start 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 ID | 120 s | Wait for a run. |
zeon stop ID | 60 s | Stop a run, as Stop in the app does, and wait for it to end. A stopped run does not resume. |
zeon reset-arms | Put 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 -f | The run log; -f follows it until the run ends and exits with the run's outcome. |
zeon snap [PATH] [--view sim] | 60 s | Save 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 s | Post a message to the viewer's Agent panel. |
zeon look TARGET [--seconds 6] | 30 s | Point 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.
| Code | Meaning | What to do |
|---|---|---|
| 0 | ok | |
| 1 | the entry or run failed | Read the traceback or zeon logs ID, fix, run again. |
| 2 | usage: bad arguments, unknown id or name, run inputs refused before the start, another project loaded, project not pushed yet | zeon <command> --help, zeon brief, zeon up, zeon push. |
| 3 | not signed in, token rejected, or REPL not enabled for the account | zeon login; ask your Zeon contact for REPL access. |
| 4 | the REPL guard refused the code | Rewrite it with the skill API. |
| 5 | timed out, or stopped waiting | zeon wait ID, --detach, or a larger --timeout. |
| 6 | instance unavailable: starting, restarting, or no free instance | Wait 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 upandzeon openprint its link.zeon sayposts to its Agent panel, andzeon lookmoves its camera. -
Camera presets. When the default view of an object is blocked, add a preset to
viewer.yamlin the project root,zeon sync, thenzeon 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 Wprints a link to workflowW's run screen on its Inputs tab, whereW's canvas renders against the simulation (a workflow without a canvas gets its run screen);zeon app W --runopens the run screen (graph, inputs, log);zeon appalone opens the project.Wis the workflow id or its display name. Options:--world Wselects a world (default: the one the simulation has loaded),--project IDnames another project (default: the folder's),--no-login-linkprints the plain app link,--browseralso opens the link locally.zeon appneeds CLI 1.5.5 or newer;zeon open --workflow W/--canvas Wstill work and print a notice to usezeon 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 withzeon down,zeon logoutor 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 thezeon openviewer link. Adding&ui=operatorto the link opens the app in operator mode. See Login links from the CLI. The link opens the pushed version, sozeon syncfirst. The CLI refuses the link unless the project is the one the instance has loaded (zeon upfirst), 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.
Updated about 19 hours ago