Agents

​

Three ways a bot runs

​

Reach is separate from running

​

A Terminal bot is a full Bot

​

team.yaml

bots:
  - { bot: al,       role: coordinator, binding: hosted }
  - { bot: builder,  role: build,       binding: terminal, harness: claude }
  - { bot: checker,  role: check,       binding: terminal, harness: codex }
  - { bot: research, role: research,    binding: vendor,   vendor: chatgpt, lane: official, directed_by: al }
reach:
  al: [telegram, push]

​

Presets

gizzi agents up product-build --preset codex-heavy --dry-run

​

Changing a bot’s model

gizzi agents model builder@product opus --dry-run   # what would change
gizzi agents model builder@product opus             # applies on the next start
gizzi agents model builder@product opus --restart   # relaunch now; the conversation resumes
gizzi agents model builder@product --clear          # back to team.yaml's model

​

Handing a seat to a fresh session

1. It saves the old pane’s last screen (and your --note) to .allternit/factory/handoffs/<bot>-<team>-<time>.md.
2. It stops the old session. That session is marked finished, so gizzi agents recover won’t bring it back.
3. It starts the bot fresh, in the same folder, and its first message tells it to read the handoff file.

gizzi agents handoff builder@product --note "tests pass; next: wire the API" --dry-run
gizzi agents handoff builder@product --note "tests pass; next: wire the API"

​

--on <computer>

gizzi agents up product-build --on build-box

• A name that isn’t paired is refused (exit 2), and the message lists your paired computers.
• A computer that hasn’t joined the mesh yet is refused (exit 1).
• Checking needs allternit-api. Without it, the step fails as transport.

1. Your engine sends the team folder (team.yaml, CULTURE.md, bots/…) and the bots placed there.
2. When your workspace is a git repo with an https or ssh origin, it also sends the commit you’re on.
3. The other computer clones the repo at that commit into a workspace of its own for you and that team (~/.allternit/factory/remote-work/<you>/<team>/repo), and the bots work there. The bots push their work there as a branch, so the other computer needs its own git access to the repo.
4. Without a repo, the bots work in a plain folder there.

• gizzi agents ps shows it with that computer as its machine. Your engine asks that computer which of your bots are live.
• orchestration send and orchestration capture reach it, and agents down <bot@team> or agents down <team> stop it there.
• Its pane is live wherever local panes are. gizzi agents attach <bot@team> mirrors it in your terminal: you see its screen as it changes and your keystrokes go to it (ctrl+] leaves; the bot keeps running). gizzi agents wall <team> gives each of the team’s remote bots a pane on the wall that mirrors it, and closes those panes when you close the wall.
• The app’s Factory screens show it the same way, with its terminal tile live and labeled with the computer it runs on (Desktop, ai.allternit.com and the phone layout).

• The mirror redraws the other computer’s screen at its own size, about five times a second at most. Typing over the mesh is a little slower than in a local pane.
• Bots the other computer runs aren’t registered with allternit-api from there, so they appear under your account through your engine.
• A paired computer’s engine takes peer calls on port 3019. Desktop starts it with --peer-port 3019 when the Mac is paired, and allternit computers serve forwards that port over the mesh beside VNC. An engine started before the computer was paired starts taking peer calls within 30 seconds of the pairing.
• Your cloud computer pairs itself, with nothing to run: it’s listed as Cloud computer (gizzi agents up product-build --on "Cloud computer"). It puts only the peer port on the mesh, never its screen (cloud computers as paired computers). If --on says it isn’t paired, open Computers once in the app so the paired list syncs.
• Peer calls need a peer ticket from cloud-api, which goes only to the computer’s owner or a member of its organization (peer tickets). Your allternit-api asks for it and carries the call (/api/v1/computers/:id/factory-peer/*).
• On the other computer you can only reach the bots you started there, and only in your own workspace.

​

Bot templates

​

Harnesses

​

Watching and attaching

• gizzi agents ps lists every bot with its binding, state, current node and proof count. Running sessions are checked against the live panes on every ps, so a dead process shows as dead, never as running.
• gizzi agents wall opens the live wall of terminals in the engine’s pane view. ctrl+b q returns you to Gizzi.
• gizzi agents wall <team> opens the same wall with its Agents panel narrowed to that team’s running bots (the panel is titled team <name>) and focused on the first one. The narrowed view goes away when you close the wall. With none of the team’s bots running it says so (exit 2) and suggests gizzi agents up <team>. The view belongs to the shared wall session, so anyone attached to the wall at the same time sees it too.
• gizzi agents attach <bot@team> depends on the binding. A Terminal bot opens its pane (a bot on another computer opens a live mirror of it; see --on). A Hosted bot opens its session right in Gizzi’s TUI. A Vendor bot shows its thread and ticket status, because it has no terminal.
• gizzi agents recover shows what it would restart after a crash. --apply does it. A session qualifies when its pane is gone, it isn’t finished, and its notes sentinel (if it has one) doesn’t say status: done. Only the lead that started it can restart it (--lead <id>, else $ALLTERNIT_FACTORY_LEAD or your user name), unless you pass --as-human. The restart goes through the same spawn gate as any spawn, with the bot’s identity and WIH kept, and uses the harness’s own resume when the original launch named a session (claude --resume, codex resume, kimi --session, agy --conversation, grok --resume).
• gizzi agents down <bot@team> stops one bot’s pane; gizzi agents down <team> stops the team’s.

​

Related

• Command reference: gizzi agents
• Orchestration
• Bot threads, Vendor bots, Bot autonomy