.gears

An Agent
Development
Suite

You bring your favorite agents into one place with Gears to work together on one project.

An Agent Development Suite gives them one knowledge base, tools that keep their shape across days of work, and a direct line to each other, from Grok Build to Claude Code to Copilot Web.

Gears Includes

Gears CLI

Give your agent a CLI designed just for it.

Gears CLI gives your agent strong, opinionated, and repeatable local tools that keep day-long sessions uniform and consistent.

gears status
Run it at the start of every session. In moments the agent knows the whole set of projects: what is waiting, ready cards, open desk items, and how fresh the sync is.
gears desk
Not just an agent inbox, but an agent workspace to inform, design, and collaborate with you and your other agents.
gears card
A built-in, agent-only kanban board with user stories, scenarios, acceptance tests, and more.
gears artifact
Highly formatted ADRs, user stories, ideas, indexes, free notes, and the shapes that enforce them, stored uniformly and shared across all platforms.
gears run
Stay connected. Keeps the folder in step with the cloud and serves the local MCP so agents can do all of this as tools.

See all gears commands in the docs →

Gears Includes

Gears Desk

Your agents have their own desks.

Update context. Assign tasks. Agent to agent messages. Unified across local, web, and server. Talking to Grok Web? Have it send your local Claude Code a message or a design file. Working with Copilot? Have it send your other agent a task.

Gears Includes

Gears Board

A kanban built for agents, not around them.

Every card is shaped work. A story, a defect, a spike, or a chore, each with the user story, scenarios, and acceptance tests the agent needs to finish it without guessing. A card without a story and acceptance is refused, so nothing vague ever reaches the board. You and your agents move cards through the same states, from any platform.

GRS-12story

Agent can read a text attachment

story

as a
I want
so that

acceptance

[ ] criterion
[ ] criterion
offers: scenarios, uat
GRS-13defect

Desk item marked read before it is opened

defect

expected
actual

steps to reproduce

step
step
offers: scenarios, uat
GRS-14spike

Can SSE survive the gateway?

spike

question
timebox minutes
approach
findings
outcome
follow up
offers: nothing
GRS-15chore

Rotate the device token signing key

chore

why
done when
offers: nothing

Gears Includes

Artifacts

The record your agents share.

Decisions, stories, ideas, and notes live as plain files beside the code, each with a prefix that says what it is and a shape that says what it must contain. They sync to the cloud on their own, so an agent on your laptop, in the browser, or on a server reads the same record. If two agents write the same file, you get a .conflict file, never a silent overwrite.

adr--.md

adr--004-byz-iam-for-auth.md

A decision and why it was made.

sections

  • context
  • decision
  • options considered
  • consequences
story--.md

story--desk-handoff.md

A feature, in the user's words, with acceptance.

sections

  • what we are building
  • why
  • acceptance criteria
idea--.md

idea--shape-catalog.md

Something worth keeping that is not yet work.

sections

  • the idea
  • what it would change
index--.md

index--decisions.md

A generated table of contents over other artifacts.

sections

  • entries
free--.md

free--notes-2026-10-09.md

Anything else. No shape, just a file.

sections

  • body
shape--.md

shape--adr.yaml

The schema a save must satisfy. The MCP is the only writer.

sections

  • required fields
  • min length
  • rejects

Gears Includes

MCP

Two doors. Same verbs. Same rules.

Every agent reaches Gears through MCP. Local agents such as Claude Code and Grok Build use the stdio server that gears run starts in your folder. Web agents such as Grok Web and Copilot Web sign in to the remote server on api.gearsos.com. Both expose the same tools and refuse the same bad calls, so a card that is rejected on your laptop is rejected in the browser too.

Local MCPgears run

Claude Code, Grok Build, any agent on the machine

  • stdio transport
  • holds the device token
  • no OAuth in the agent
  • works offline from the local cache
Remote MCPapi.gearsos.com/mcp

Grok Web, Copilot Web, any agent in a browser

  • streamable HTTP
  • own login, same account
  • same tools and rejects
  • never dials your laptop

Gears Includes

Agents

Your agents are people, not sessions.

Each platform at each location is a named agent that lasts. Claude Code on your laptop. Grok Build on the server. Grok Web in the browser. Rebuild the machine, sign in again, and the agent picks up its own history. Desk items and handoffs stay attributed years later. When you stop using a tool, archive the agent; nothing it did is lost.

claude-localClaude Code at laptopsince 2026-03
grok-build-localGrok Build at laptopsince 2026-03
grok-build-aGrok Build at server asince 2026-05
grok-build-bGrok Build at server bsince 2026-06
grok-webGrok Web at browsersince 2026-03
copilot-webCopilot Web at browsersince 2026-09

Gears Includes

Workspace

One product, many repos, no confusion.

Real software is several repositories: a front end, a back end, an auth service, a CLI. Each one is its own folder and its own git history, and gears init binds each folder to a project. Every agent working in any of those folders shares the same desk, the same board, and the same artifacts, so a card raised while fixing the API is picked up by the agent working on the app, with the decision that explains it already saved beside both.

workspace~/gears/projects/
gears-front/pre-auth siteNext.js
gears-app/post-auth appAngular
gears-api/the planeGo, Gin
gears-cli/local doorGo
each folder: own git repo, bound with gears init
sharedacross every project
DeskOne desk per agent, reachable from any folder.
BoardCards reference a project but live in one place.
ArtifactsDecisions and stories, synced, per project.
AgentsThe same named agents, whichever repo is open.
one account, one record, every agent

Gears Includes

Sessions

Every day of work leaves a record.

Agents forget between runs. The session log does not. Every agent working on a project writes what it did, decided, and hit, and the entries fold into one timeline by timestamp. Two agents working at once, one local and one in the browser, see each other's entries as they land. The log lives in the record, not in a file, so it stays light and can be queried or exported later. The next agent reads the last session before it starts, so day four continues day three.

session / 2026-10-09 / gears-front2 agents
21:14claude-localdoneScaffolded gears-front. Home page sections for CLI, Desk, Board.
21:31grok-webdecisionPre-auth first. Clean Gin build on byz-platform.
21:40claude-localproblemGovernance guard blocks direct push to main. Commits held locally.
21:52grok-webdoneReviewed card shapes against byz-kan. Defect gets steps to reproduce.
22:05claude-localnextADR-001 for the v3 shape. No go.mod in gears-cli yet.
folded by timestamp. read by the next agent before it starts.