Junto docs

Junto is a desktop app where coding agents work together. It renders a canvas: agent seats, terminals, notes, git cards, and named regions are nodes, and the lines between them are edges. You author the canvas; agents read it and act through the tools its lines grant them.

An edge is the only way an agent gains access to another seat. Drawing a line grants access, the edge's verb limits it to the ports it compiles to, and deleting the line revokes it.

Junto is free, open-source software (Apache-2.0) for macOS 13 or later on Apple silicon. This document describes the official build: agent seats, terminals, agent-to-agent mail, notes, labels, git cards, and regions. More is in the source behind compile-time flags; see Feature flags.

• The canvas is authored by the human operator in the running app. Agents never write the canvas document.
• All product state lives in one local SQLite database at ~/.junto/state/junto.db. JSON Canvas exports and .digest.txt / .svg sidecars are outputs, never inputs.
• The canvas has a play state. Every launch comes back paused: agents keep working in their own terminals, but they cannot message each other or act through Junto until you press play. Pausing never kills a running process.
• Everything an agent can do through Junto flows through a connected edge and a compiled port — there are no ambient grants.

A Junto canvas is a JSON Canvas 1.0 document — nodes and edges — extended with one namespaced key, ether, on nodes and edges. Nodes have a JSON Canvas type (text, file, link, group), a position and size (x, y, width, height), and an optional ether object that gives the node a product identity.

{ "id": "n1", "type": "text", "x": 0, "y": 0, "width": 220, "height": 84,
  "text": "planner",
  "ether": {
    "entity": { "kind": "agent", "name": "local:planner" },
    "flags": ["blocker"]
  } }

{ "id": "e1", "fromNode": "planner", "toNode": "reviewer",
  "ether": { "verb": "messages" } }

Two invariants hold on every write, from the app or the CLI:

1. Graceful degradation — strip every ether key and the file is still a valid, readable JSON Canvas 1.0 document.
2. Mirror law — extension semantics mirror into native fields: a blocker flag paints the node's color crimson. Nothing on an edge mirrors — its live phase is recomputed at read time.

On a node, the ether object carries:

Decode is strict: a document with unknown or excess fields fails to load rather than silently carrying them, which keeps hand-edited files honest.

One authored default matters for safety: ether.terminal.onDelete defaults to detach: deleting the card leaves the process alive.

Every node is a JSON Canvas node (text, file, link, or group). The ether.entity.kind field assigns a product identity from an open vocabulary. Well-known kinds compile to a role (actor, sink, or geography), which decides what the node can do. Unknown kinds are inert geography: they display on the canvas but hold no seat, no ports, no inbox, and no work claim.

Roles are derived from the kind — never authored, and a group node is geography whatever kind it carries. agent is the only actor kind: the only node type that holds a live process seat and carries an inbox. Geography may still display agent state; display grants no capability.

entity.name follows a <host>:<profile> convention for managed entities (for example local:planner). An agent node becomes a deliverable seat only with all three of entity.name, ether.terminal.bindingId, and ether.terminal.harness — without them the node exists on the canvas but no process occupies it.

An edge is { id, fromNode, toNode, ether: { verb } } plus optional presentation fields (fromSide/toSide, fromEnd/toEnd, color, label) that never carry meaning. The verb is the one authored fact on an edge — what the relationship is. Everything else an edge does, such as which ports it grants, is compiled from the verb plus the two endpoint kinds. Compiled facets are never stored on the edge.

Direction is semantic, not spatial. fromNode is always the verb's source end, whichever way the edge was drawn; an edge drawn backwards is stored in the verb's own order.

A pair of node kinds with no verb refuses to connect, as do self-loops and duplicate pairs. Each edge reads as a plain sentence in the bottom command bar, painted in a fixed per-verb hue. No dash pattern, width, or arrowhead carries meaning. Clicking a drawn line selects it.

Deleting an edge revokes the capabilities it granted. There is no separate permission store: the drawing is the policy. A call outside the grant fails closed with a ScopeError that names the missing edge and the fix.

Every pair the official build lets you connect, and what the edge compiles to. Pairs not listed here are refused at draw time.

The running app derives these rules from the document; none of them is stored. Roles, capability grants, blocked seats, and live edge phase are recomputed from the canvas plus live state; absent data invents nothing.

• Roles are laws, not labels — actor (only agent), sink, scheduler, geography. A kind's literal group is its role; capability code matches on the role tag, never on a kind string.
• Blockable means actor — only agent seats can be in the blocked set.
• Admission is ordered and fail-closed — a call passes these checks in order: the nodes exist, an edge connects caller to target (region co-membership grants visibility, never ports), the role pair is legal (a non-actor caller or a geography target is denied), and the requested port is inside the edge's grant and the target's offers.
• No multi-hop — nothing propagates past the direct edge.

The canvas's visible glance state is itself derived: occupancy per node projects to empty, idle, working, attention, activity_blocked, stalled, parked, or gone from occupant presence, harness activity, last-seen time, and operator flags — missing inputs stay honest rather than inventing a state.

Terminals in Junto are managed PTY sessions: the app spawns the process, owns the pseudoterminal, and renders it in the canvas or a focus surface. An agent node is a managed terminal carrying a harness; a terminal node is a plain managed shell — seat-plane geography, no actor powers, and by construction it cannot hold a harness.

A seat is the durable binding between a canvas node and a process generation. There are two creation paths: a raw terminal (a plain shell — geography) and an agent seat (an actor: declared harness, agent key, canvas and node identity). Creating an agent seat on an occupied seat is never a silent replace — the incumbent must match the exact requested actor identity or the call fails as a seat-identity conflict.

Occupancy is independent of process liveness:

• A seat is vacant or occupied. Creating a session occupies; a stopped but still-indexed generation still occupies — a stopping incumbent is not a vacancy.
• Exited, missing, or absent means vacant. Resumable, crashed, stalled, and paused describe the occupant process, never the seat.
• Occupying a vacant seat and activating an occupied seat are different operations. Activation is validate-only: harness, agent key, node, binding, and generation must all match — an occupied generation is never repurposed for a different actor.
• Pin, unpin, and remount activate a view; they never occupy.

An agent node runs an agent CLI — a harness — inside a managed terminal. Each harness has a template declaring the spawn binary and arguments, how Junto delivers its instructions (Tier A: a system-prompt or rules flag in argv at launch; Tier B: the first typed message once the seat proves idle), the named-session contract, which settings it takes (model, effort, permission mode), and how the seat reads status.

• Three session families: pin harnesses take a Junto-minted id at spawn; capture harnesses print none, so the app watches from spawn and stores the id it proves before any resume form is ever emitted; Amp provisions a thread and resumes it by subcommand.
• Resume launches re-apply model, effort, and permission flags — several harnesses do not inherit them across a resume, and a seat that silently reverted its model would be lying about what is running.
• A harness whose instructions freeze at thread creation (codex) cannot receive re-injected instructions on resume; later generations get orientation notices instead.
• Settings cover what a harness is: model, effort, permission mode. Look-and-feel flags are never emitted; they stay in the harness's own config, so a managed seat behaves like the same harness started by hand.

Harnesses run with their own accounts, tools, and provider costs. The seat contract — process-bind identity, edge-granted ports, the typed-write gate — is identical across harnesses; what varies is fidelity: how completely each harness's screen states, resume shape, and settings have been probed.

A messages edge between two agent seats lets each one mail the other through the junto CLI. The sender picks the shape. A notice types one short line into the recipient's input, naming the sender and the command that reads the message (junto msg read <id>). A prompt types the full text instead.

junto msg send '{"target":"reviewer","text":"auth refactor is up, please review src/auth"}'
junto msg send --prompt '{"target":"reviewer","text":"Review src/auth and reply by mail with any blocking issue."}'
junto msg list

Either way, the text is typed into the recipient's input and submitted at once, whatever the agent is doing; its harness queues or steers it. Nothing is refused and nothing needs a retry. A recipient whose seat is not running, or has no seat yet, gets the mail when its terminal comes up. The send answers delivered (typed into the seat) or waiting (the seat is not up yet).

Mail is durable: it stays in the recipient's mailbox until read. A seat's own msg list marks its mail read, msg reply answers, msg react acknowledges without a reply, and msg sent shows whether each message was delivered and read. While the canvas or seat is paused, an agent cannot send or read mail, but mail already sent still reaches it; see Play and pause.

The same edge grants seat wait (block until the other seat is idle, working, or needs attention) and seat read (read the other seat's terminal).

Agents and scripts reach the running app through the junto CLI, which talks to the app's local control socket (~/.junto/work/control.sock, bearer token in ~/.junto/work/token). The CLI never opens the SQLite database; only the app does.

Identity is process-bind: the CLI must run as a descendant of a live, Junto-registered agent process. The app admits callers by their Unix peer pid and walks ancestors — a CLI may be a grandchild — and start-key epochs reject pid reuse. The seat's principal (agent key, node, canvas) is resolved server-side; the wire carries no identity claim at all, and the token is a file-backed (0600) transport credential, never an env var or an argument.

The capability contract an admitted agent sees comes from its edges. junto capabilities and junto onboard report the live edge contract for the calling principal; calls outside it fail closed with a scope error.

Every work command takes one JSON argument (inline, @file, or stdin) and returns JSON. The CLI is self-describing: schema show <command> prints the input shape, examples show <command> prints executable examples, and junto docs prints the generated reference — the node catalog, per-kind depth, concepts, and this contract — straight from the physics registry, so it cannot drift from the program. Batch-capable commands accept a JSON array plus --concurrency <n>.

Errors are a closed family carrying type, retryable, and next_step. The agent-facing members: ScopeError (not connected; the fix is an edge), InputError (payload failed decode; schema show prints the shape), RuntimeDown / Paused (wait and re-onboard), Blocked (this seat is blocked; stop and wait), plus UnknownTarget, StaleNodeRef, AuthError, ProtocolError, InternalError for the plumbing. Retry only when retryable is true, at most twice. While a seat is blocked, ping, doctor, capabilities, onboard, and rulings stay open; mailbox and every mutating op refuse.

In a source checkout, bun run canvas:ls lists canvases, bun run digest <canvas> prints a text projection of one, and bun run render writes an SVG image of the canvas. They read the running app and never write the canvas.

Product surfaces are compile-time gated. Official builds use the ship profile; source builds can turn on the rest for development. This document covers what ship enables.

A node or edge kind that is compiled out still decodes if it exists in a document — durability outlives features — but it has no authoring surface and cannot be created in this build.