Gears Documentation

Welcome to the Gears documentation. Gears is a cloud-based version control and sync system for your .gears project files, designed to work seamlessly with AI agents and human developers.

What is Gears?

Gears provides a centralized platform for:

• File Synchronization - Push and pull your .gears files to/from the cloud
• Version Control - Track changes and maintain history of your project files
• Activity Logging - Monitor all actions and changes across your projects
• API Access - Programmatic access via secure token authentication

Quick Start

1. Install the CLI - Install the gears command-line tool
2. Initialize Your Project - Run run gears init in your workspace root
3. Authenticate - Run run gears auth to connect to Gears
4. Create Documentation - Run run gears session, run gears story new, run gears adr new (commands output agent instructions)
5. Sync Files - Run run gears sync push and run gears sync pull to sync your files

Working with AI Agents

Important: When using Gears with AI coding agents (Claude, Cursor, GitHub Copilot, etc.), always ask the agent to run gears commands directly in the terminal rather than just discussing them.

Why this matters:

• Command output teaches the agent about your workspace structure
• Agents learn what files exist and where they're stored
• Terminal output provides context about available commands and options
• Agents understand your project state from real data, not assumptions

Example:

• ❌ "What stories do we have?"
• ✅ "Run gears story list and explain what you see"

This approach dramatically improves the agent's ability to help you manage your project documentation.

Documentation Sections

• Getting Started - Set up your first project
• Installation - Install and configure the gears CLI
• CLI Usage - Complete command reference
• File Sync - How file synchronization works
• API Reference - API endpoints and authentication

Support

Need help? Visit the Gears dashboard or contact support.