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 gears init in your workspace root
3. Authenticate - Run gears auth to connect to Gears
4. Hydrate Agent Context - Run gears hydrate --chat at session start
5. Create Documentation - Run gears session, gears story new, gears adr new
6. Sync Files - Run gears sync push and 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.