A city separates responsibility, evidence, and authority.

Mental model

One person may own several local cities. Another person keeps theirs on another computer. A remote road connects their seats without merging machines, workspaces, or credentials.

owner A · computer A
└── product city
    ├── seat · chair
    ├── delivery agent · code
    │   ├── mounts/api → API repo
    │   └── mounts/web → web repo
    ├── research agent
    │   └── mounts/handbook → documents
    └── remote road → owner B/security

$agents-city agents list --data <city> --card <owner-card>$agents-city agents mount --data <city> --agent writer --src ~/Documents/handbook

Agents are defined one at a time

Current main onboarding does not turn every folder into an agent. It completes one specialist before offering the next, and it also permits a city that starts with only its chair.

1. 1

   Name — how the agent appears in its window, on the map, and on the bus.

2. 2

   Kind of work — code, knowledge, or coordinator; this describes work and its building, not authority.

3. 3

   Role — its speciality, from this domain or another, without turning it into the chair.

4. 4

   Everything it uses — any mix of repositories, worktrees, and document folders mounted in its own workspace.

5. 5

   Runtime — Claude, Codex, OpenCode, Kimi, or an explicit terminal fallback.

6. 6

   Starting skills — only those the owner chooses, and only when the selected engine can read them.

$agents-city seat --agents$agents-city agents mounts --agent writer --data <city>$agents-city agents mount --agent writer --src ~/Documents/handbook --data <city>

One local bus, four native deliveries

Every actor receives typed envelopes through the same local WebSocket. The last mile changes to preserve each provider’s real interface.

The committee, step by step

The seat opens a committee only when specialised evidence can change the decision. It does not summon every agent by default.

1. 01

   Brief

   question, outcome, context, constraints, definition of done, authority, and participants.

2. 02

   Isolated positions

   each member answers without seeing the others; abstention is valid.

3. 03

   Synthesis

   the seat compares evidence, agreements, conflicts, and unknowns without voting.

4. 04

   Floor

   a member requests one turn for new evidence, contradiction, risk, or dependency.

5. 05

   Decision

   outcome, rationale, executor, verifier, dissent, and reopen conditions are recorded.

6. 06

   Verification

   another agent returns pass or fail; fail requires a replan.

$agents-city committee schema open$agents-city committee open --input proposal.json$agents-city committee show <deliberation-id>

Every deliberation keeps ACT.md for people, state.json for state, and events.jsonl as an append-only audit trail. They are not edited to bypass transitions.

Local and remote roads

A local road connects two cities on one machine without an external server. Across people or computers, each side accepts the other’s public invitation and both seats use the same optional relay with their own owner credential. The invitation never contains that token.

$agents-city road invite product > product.invitation.json$agents-city road connect research product.invitation.json$agents-city road invite research > research.invitation.json$agents-city road connect product research.invitation.json$agents-city bus roster

State you can inspect

~/.agents-city is a container. Every managed city lives below its owner and shares no configuration with home, product, or client-a.

~/.agents-city/<owner>/<city>/
├── city.yml
├── roads.json
├── <owner>.md
├── AGENTS.md
├── agents/
│   └── <agent>/
│       └── mounts/ → repos, worktrees, documents
├── domains/
├── roles/
├── deliberations/
├── units.yml
└── parcels.yml

domains/ and roles/ contain editable city Markdown. They are not hidden skills and are not automatically overwritten when a role changes.

A front door for every city

Current main can put a city on the desktop with its own name and icon. It creates a macOS app, a Linux .desktop entry, or a real Windows desktop shortcut when running through WSL. Every one opens the same city as the CLI.

$agents-city shortcut$agents-city shortcut product --hall$agents-city shortcut --remove