File formats — Docs · CommandAGI Developers

The rules

Plain files only. The most a file does is grow while it records — a stream's records.jsonl, its media file, a run's members.jsonl. There are no hidden databases, pointer files or bundles.
References are paths and ids. A run uses the asset at its path now; nothing pins a hash.
The folder is the project. Nothing about a project's layout is hard-coded into the workbench.
Levels. Every definition, world and setting can exist in the cloud or locally, at the global, user and project level, and they merge from broad to specific.

Devices

devices/<id>/definition.json, with its assets beside it in devices/<id>/assets/ (for example model.glb).

A definition names the machine (name, manufacturer, model_number, product_url …), its 3D model, and its channels:

json

{ "id": "gcode", "dir": "duplex", "medium": "records",
  "format": "gcode-chat", "dialect": "grbl", "transport": "serial", "baud": 115200 }

dir is in, out or duplex; medium is records, video, audio or bytes. A unit in a world can override a channel.

Worlds

worlds/<id>/world.json:

json

{ "id": "shop", "name": "Shop floor", "kind": "physical",
  "space": { "origin_mm": [0, 0, 0], "size_mm": [6000, 4000, 3000] },
  "units": [ { "uid": "mill-1", "name": "Mill", "device": "cnc-3018-montaj",
               "position": [1200, 800, 0], "rotation": [0, 0, 90] } ] }

kind is physical or simulation. A world may name a 3D scene (model, a .3dx) and, if it is a simulation, a simulation file (sim, a .sim.json). A world is not a 3D model, and a run is not a world.

Runs and streams

runs/<run>/ is one run in one world:

file	holds
`run.json`	`id`, `world`, `kind` (`session`, `recipe` or `thread`), `started`, `ended`, `from` (the run and time it was forked from)
`members.jsonl`	who and what took part, appended as they join
`steps.jsonl`	a recipe's steps
`streams/<uid>.<channel>/`	one stream: `stream.json` plus its data — `records.jsonl`, or one `video.webm`/`.mp4`, `audio.webm`/`.mp4`, or `data.bin`
`streams/chat/`	a thread's conversation
`streams/sim/`, `streams/sim-input/`	a simulation's frames and the inputs applied to it
`evidence/`	files kept as evidence

A record is one line of JSON:

json

{ "t": 7.180, "seq": 41, "src": "operator", "kind": "note", "text": "agent:night-shift: run_program", "by": "agent:night-shift" }

src is device, sim or operator; kind is command, event, ack, reply, state, evidence or note; seq strictly increases. An unknown state is written { "kind": "state", "status": "unknown" }.

Documents

Each editor document is one JSON file — { "format": "commandagi-document", "kind", "title", "meta", "body" } — with large assets in a <name>.assets/ folder beside it.

extension	opens in
`.3dx`	3D design (parts, assemblies, scenes)
`.camx`, `.slicex`	3D design in CAM and slicing mode; programs are saved beside them as `.gcode`
`.nestx`	the vector app's nesting mode (laser and sheet jobs)
`.drawx`, `.paintx`, `.imgx`	drawing, painting and image editing
`.deckx`	slides
`.vidx`	the video editor
`.musx`	music
`.geox`	geoeconomics workspaces
`.task`, `.project`	tasks and projects

Other formats

file	what it is
`<name>.sch.json` + `<name>.pcb.json`	a circuit: the schematic and its board, two files that name each other
`<name>.sim.json`	a simulation
`<name>.trials.json`	an experiment: many simulated runs over a parameter sweep
`<name>.graph.json`	a graph (knowledge, memory)
`<name>.dashboard.json`	a dashboard: panes and the files they show
`<name>.market.jsonl`	a market's tape, book, orders and positions
`calendar/<calendar>/<event>.ics`, `contacts/<email>.vcf`	calendars and contacts
`.xlsx`, `.md`, `.pdf`, `.ipynb`, `.gcode`, `.step`, `.stl`, `.glb` …	opened as they are, in the editor for their kind

Settings

Settings are VS Code–style settings.json files (comments allowed), one per level, merged from broad to specific: the cloud and local global levels, your organizations, your account, then this computer (~/.commandagi/settings.json) and this project (.commandagi/settings.json).

json

{
  "workbench.theme": "dark",
  "threads.agentControl": false,
  "devices.lanListener": true,
  "[.gcode]": { "editor.default": "gcode" }
}

A "[.ext]" block overrides settings for one file extension.