The development loop

Every change you make to a Zeon project goes through the same six-step cycle. Learn it once on your first change and the rest of the hackathon is repetition.

The loop runs on the zeon CLI, so install it first: Install the CLI.

The three places your code lives

Before the loop makes sense, you need the mental model behind it. A Zeon project exists in up to three places at the same time:

These three copies are not automatically the same. Nothing you save on your laptop reaches the simulator until you push it, and nothing reaches the robot until the lab machine pulls it.

Sync is the only thing that moves work between them. The cloud copy is the hub: your laptop pushes to it, the lab machine pulls from it. That is why the loop begins and ends with a sync.

The loop

1. Get the latest

Always start from the cloud's current state. Which command depends on what you have on disk.

You already have the project locally. Run this at the project root:

zeon sync

If nothing has changed on either side it prints already up to date and exits.

You have the project in the cloud but not on disk:

zeon clone <project>

You have a folder of files that isn't a Zeon project yet. zeon init registers the current directory as a new cloud project and pushes what's in it:

cd my-project
zeon init -m "Import existing project"

init is strict about three things, and it fails fast rather than half-registering:

• The directory must already contain skills/, worlds/, and workflows/. If any are missing it refuses and names the missing ones.
• The directory must not already contain .zeon/. If it does, the folder is already linked to a cloud project, so use zeon sync instead.
• The directory's name becomes the cloud project name, and that name must be free in your account. If a project by that name already exists (including archived ones), init stops and tells you to rename the directory or archive the old project.

-m sets the message on the initial commit. Without it the commit is recorded as Import existing project.

2. Make the change

Skills, workflows, and worlds are plain files on disk: Python, JSON, and YAML. There is no proprietary editor and no special file format. Open the project folder in whatever you already use, whether that is VS Code, Vim, or an editor you had never heard of yesterday.

An AI coding agent such as Claude Code is one reasonable way to do this step. Point it at the project folder and describe the skill or workflow you want. It reads and writes the same files you would. If you go this way, install the Zeon project skill first, which teaches Claude Code the project format so what it writes validates. Everything after this step is identical either way, and you should still review its edits in step 3 before pushing.

One thing worth knowing before you edit a skill: a skill's parameters come from the Python function signature in its robotic_code.py, not from metadata.yaml. Change the signature and you have changed the skill's inputs.

If you want to eyeball where a file actually sits in the project and what format it is in, ide.zeonsystems.app shows you the file tree and contents in a browser. It is a viewer for orienting yourself, not where you do the work.

3. Review what changed

Optional, but cheap, and it catches a surprising number of mistakes when an agent has been editing for you.

zeon status

status prints the current local commit and the last-known cloud commit, then lists your files grouped as Added, Modified, Deleted, and Unmerged. With no changes it prints working tree clean. Add --json if you want to script against it.

To see the actual edits:

zeon diff

diff prints a unified diff of your working tree against your last commit, one file at a time. Pass paths to narrow it:

zeon diff skills/my_skill/robotic_code.py

4. Push it up

zeon sync -m "Add plate transfer skill"

One command does the whole round trip: it commits your working tree, pulls the cloud's current state, merges the two, and pushes the result. You do not need a separate commit-then-push dance, and you do not need to remember to pull first.

-m supplies the message for the commit that records a merge of cloud changes into your work. When there is nothing to merge, your changes still go up under an automatic message, so a bare zeon sync is always safe.

Sync stops for exactly one reason: a file was edited both locally and in the cloud, and the two edits overlap. When that happens it prints CONFLICT next to each affected path and leaves conflict markers in the file. Fix the file, then:

zeon sync --continue

Or back out entirely and keep your local work untouched:

zeon sync --abort

For the full conflict walkthrough, see Resolving "diverged from cloud".

5. Preview it in the simulator

Open the web app at https://zeonsystems.app, open your project, and run the workflow against the simulator. Nothing physical moves; you watch the run in a 3D viewport. This is where you catch a reversed waypoint or a wrong plate position before a real arm tries it.

Iterate here. Sim runs cost you nothing but time, so it is normal to go round steps 2 to 5 several times before you touch hardware. See The main app and Running a workflow in the cloud sim.

6. Run it for real

Hardware runs happen on the lab machine attached to the robot, not from your laptop and not from the cloud UI. The lab machine has to pull your change first, which means step 4 is a hard prerequisite: if you didn't sync, the robot is still running your last version.

See Running a workflow on real hardware for the full procedure.

Worked situations

"I'm starting my day and someone else edited the project last night"

zeon sync

That's the whole answer. It pulls their work, merges it into yours, and pushes anything of yours that was still local. Run it before you write a line of code, not after.

"Something rewrote four files and I want to check before pushing"

zeon status
zeon diff

status gives you the file list; diff gives you the lines. If it looks right, zeon sync -m "...". If it doesn't, edit the files and look again. Nothing has left your machine yet.

"My change works locally but the simulator still shows the old behaviour"

The cloud has not seen your edit. Run zeon status. If it lists anything under Added, Modified, or Deleted, or if head and remote head differ, that work has not reached the cloud. Run zeon sync -m "...", then re-run in the web app.

"The robot is running an old version of my workflow"

Same cause, one step further along. On your laptop, check zeon status shows a clean tree with head and remote head matching. Note that status reads a pointer cached at your last sync rather than asking the server, so run zeon sync if you are unsure. Then pull it down on the lab machine with zeon sync before starting the run.

"Sync stopped and told me there's a conflict"

Open each file it printed CONFLICT for. Delete the <<<<<<< markers and the version you don't want, keep the rest, then run zeon sync --continue. If you'd rather deal with it later, zeon sync --abort restores your local changes and leaves the cloud alone.

"I have a folder of skills from a teammate and want it in the cloud"

Make sure it has skills/, worlds/, and workflows/ at the top level. Create the empty ones if it doesn't, then:

cd my-project
zeon init

The folder name becomes the cloud project name, so rename the folder first if you want something different.

How long each step takes

Steps 1, 3, and 4 are seconds. Step 2 is where your time goes. Step 5 is the one people skip and regret. Step 6 is the only one that can break something physical.