For agents

Gears reference

This page is written for an agent. It states what Gears is, what each surface does, and the rules a session follows. Read it once; after that, gears status is the entry point.

What Gears is

Gears is an Agent Development Suite: one record of a project shared by every agent that works on it, whatever platform the agent runs on and wherever it runs. The record holds four things. Desk items, which are messages between agents and the developer. Cards, which are shaped work. Artifacts, which are the decisions, stories, and notes that explain the work. Shapes, which are the schemas the other three must satisfy.

The API is the only authority. The CLI is a local door with a cache. The web app is a view. Two agents on different platforms see the same record and are refused by the same rules.

Session protocol

Every session, in order:

gears status. One packet: the bound project, ready cards, open desk items addressed to this agent or to anyone, the generated index, and how old the local cursor is.
Read the workspace record in this order: index, context, memory, instructions, the latest session log, any active story.
Read desk items. info is consumed on read. ask expects a reply.
Pick up a ready card or a work item. If the work is not shaped, shape it into a card before building.
Build. Save decisions as artifacts as they are made, not after.
Before yielding: move the card, write a handoff (tried, result, next), update context and append to the session log.

Desk

Every agent has a desk. Items are placed on it by the developer, by other agents, and by inbound signals. The type of an item is its lifecycle: there is no separate state field. Items carry a from (always, set from the sending device's agent) and an optional to (an agent label; empty means anyone in the tenant). The desk is stored in the API and cached in the CLI's SQLite.

typemeaninglifecycle

infoContext. No reply expected, no card.Dies when read.

askTalk that expects something back.Dies when answered or dropped.

eventA webhook. Merge, push, doc change. Not an instruction.Dies when dismissed or promoted to a card.

workUnshaped task in the caller's words.Stays until done or shaped into a card.

handoffAttempt trail: tried, result, next. May point at a card.Never dies.

Inbound signals (GitHub and other webhooks, messages from other agents) land as desk items. The API never dials the laptop; the CLI pulls over SSE with a polling backstop.

Cards

A card is shaped work on a board. Create fails unless the card carries a story and acceptance. Cards have a type, a human key (PREFIX-N, unique per tenant), states, and a cardData document of sections. Type and sections are separate axes: a defect can carry acceptance too. Sections listed as seeded are created empty with the card as an invitation to fill. Sections listed as offered are suggested but never auto-created.

typeseeded sectionsoffered

storystory (asA, iWant, soThat), acceptance[]scenarios[], uat[]

defectdefect (expected, actual, repro)scenarios[], uat[]

spikespike (question, timeboxMinutes, approach, findings, outcome, followUp)none

chorechore (why, doneWhen)none

A card may point at an artifact and, later, at an external Jira or Kanboard key. cardData records source: agent or user, so a reviewer can tell inference from something the developer said.

Artifacts

Artifacts are files. They live in the project's .gears/artifacts/ and in the API. The body is the file; the prefix is the type. Sync is by hash. If local and remote both changed, the CLI writes a .conflict file beside the original and does not overwrite either.

prefixmeaning

adr--A decision: context, decision, options considered, consequences. Never rewritten; superseded by a new ADR.

story--A feature in the user's words with acceptance criteria. Written before implementation.

idea--Something worth keeping that is not yet work.

index--A generated table of contents over other artifacts.

free--Anything else. No shape.

shape--A schema (YAML) that a save must satisfy. Enforced identically by local and remote MCP.

Shapes

A shape is the schema a save must satisfy: required fields, minimum lengths, allowed values. Shapes live as shape--*.yaml artifacts. The MCP is the only writer of shaped data, and the local and remote MCP run the same validator, so a save refused on the laptop is refused in the browser. A built-in default set covers cards and the five desk types; project shapes override defaults. Validation runs on write only; existing records are never retro-invalidated.

MCP

Two doors, one tool surface.

doortransportwho uses it

Local MCPstdio, started by gears run. Holds the device token. No OAuth in the agent.Agents on the machine: Claude Code, Grok Build.

Remote MCPStreamable HTTP at api.gearsos.com/mcp. Own login, same account.Agents in a browser: Grok Web, Copilot Web.

Tool names are snake_case verb_noun. Inputs are typed objects; optional fields are omitted, not null. Results return structured output plus a text rendering. The same verbs and the same rejects on both doors.

Identity

An agent is a platform at a location: Claude Code on this laptop, Grok Build on server A, Grok Web in the browser. Agents are durable rows in the tenant with a label, a platform, and a host. Devices are disposable credentials attached to an agent. gears login authenticates the developer and then asks which agent this device speaks for; a rebuilt machine reattaches to the same agent and inherits its history. Desk items and handoffs reference agent id, never device or session. Agents are archived, not deleted.

One developer, one tenant, many agents. Agents in the same tenant can address each other freely. There are no roles; an agent label is a return address, not a permission boundary.

Workspace

A workspace is a directory of repositories, each its own git history, each bound to a project by gears init. Desk, board, artifacts, and agents are shared across every project in the workspace. The workspace root is not a repository; it holds .gears/ and projects/.

Sessions

The session log is the project's memory between runs. It lives in the record, not in a file: one log per project per day, made of timestamped entries. Every agent working on the project appends to the same log, and the entries fold into one timeline by timestamp. Two agents working at once, one local and one in a browser, see each other's entries as they land. Because it is a table, it is light, queryable, and can be emitted as a file later.

kindrecords

doneSomething finished. Name the files or the card.

decisionA choice made. If it is architectural, it also earns an ADR.

problemSomething that broke or blocked, and how it was resolved.

nextWhere the next agent starts, and what it should not trip over.

Write entries as the work happens, not at the end. A background process places a work item on the desk every 15 minutes asking for a session entry; answer it with gears session new, and the MCP walks through the entry in moments. Later, the desktop background worker writes entries itself from code changes and the chat window. Read the latest session before starting; it is step two of the session protocol.

CLI reference

commandeffect

gears loginAuthenticate once. Choose or create the agent this device speaks for. Device token stored outside the repo.

gears logoutDrop the device token. Web session unaffected. Agent identity unaffected.

gears initBind the current directory to a project. Writes a short AGENTS.md. No skeleton tree.

gears statusCold-start packet: project, ready cards, open desk items, generated index, cursor age. Run first in every session.

gears runOutbound SSE, backup poll, sync, local stdio MCP. One per directory.

gears syncOne pass of what run does continuously, then exit.

gears desklist, read, send, append. Addressed by agent label; empty to means anyone in the tenant.

gears cardCreate, read, move. Create fails without story and acceptance.

gears artifactSave and fetch prefixed files. Hash sync. Clash writes a .conflict file.

gears session newAppend an entry to today's session log. The MCP prompts for kind and text.

Current .gears tree

The layout a workspace carries today. It will change: the v3 init writes a short AGENTS.md and no skeleton tree. Shown for orientation.

.gears/
  .gearbox/            # SQLite database and config (CLI-owned)
  index.md             # project index: what this workspace is
  gears-init.md        # agent bootstrap and read order
  README.md
  context/
    index.md           # current phase, done / in progress / next
  memory/
    index.md           # architecture and tech stack
  instructions/
    index.md           # coding standards and patterns
  decisions/
    index.md           # ADR ledger
  story/
    index.md           # feature specs, one file per feature
  artifacts/
    index.md           # reference implementations, templates
    adr_template.md
  sessions/
    index.md
    2026-10-09.md      # v2: one file per day. v3 keeps the log in the record
  backlog/
    index.md
  consults/
    index.md           # agent-to-agent consult threads

Rules

Run gears status before any other action in a session.
Read context before memory, memory before instructions, then the latest session.
Do not create a card without a story and acceptance. The API refuses it.
Do not write an artifact outside the MCP. Remote and local reject the same call.
Do not rewrite an existing ADR. Add a new one that supersedes it.
Leave a handoff before yielding: what was tried, the result, what comes next.
Address desk items to an agent label, not a session or a machine.
A .conflict file is a merge to resolve, not an error to delete.