Command: gears init

Initialize a new .gears directory structure in your project.

Overview

The init command sets up the Gears documentation framework in your project by creating a structured directory system for AI-assisted development. This should be the first command you run when starting to use Gears in a new project.

Syntax

gears init

No flags or arguments required.

What It Does

Workspace Structure

Gears uses a specific workspace structure that separates the shared .gears directory from individual project directories:

/root/                          # Your workspace root
├── .gears/                     # Shared Gears directory (ONE per workspace)
│   ├── sessions/               # Daily AI conversation logs
│   ├── story/                  # Feature specifications
│   ├── adr/                    # Architectural Decision Records
│   ├── memory/                 # Project knowledge base
│   ├── context/                # Current work tracking
│   └── config.json             # Configuration (created on first auth)
└── projects/                   # All your projects
    ├── project-1/              # First project
    │   ├── src/
    │   └── ...
    └── project-2/              # Second project
        ├── src/
        └── ...

Important: The .gears directory lives at your workspace root (e.g., /root/.gears), NOT inside individual project directories. This allows you to manage documentation across all your projects from a single location.

.gears Directory Structure

Running gears init creates a .gears/ directory with the following structure:

.gears/
├── sessions/       # Daily AI conversation logs (YYYY-MM-DD.md format)
├── story/          # Feature specifications and user stories
├── adr/            # Architectural Decision Records (working code docs)
├── memory/         # Project knowledge base and context
├── context/        # Current work tracking
└── config.json     # Configuration file (created on first auth)

Each directory serves a specific purpose in maintaining project understanding across development sessions.

When to Use

• First time setup: When starting to use Gears in a new project
• Team onboarding: When setting up Gears for new team members
• Project migration: When adopting Gears in an existing project

Working with AI Agents

Always have your AI agent run gears init for you, even if just to verify setup. The command output:

• Shows the directory structure and what each folder is for
• Teaches the agent where documentation lives
• Helps the agent understand the workspace architecture

Example:

• ❌ "I think we have .gears set up"
• ✅ "Run gears init to verify the workspace structure"

This ensures the agent understands your project organization from the start.

Examples

Initialize a New Project

$ cd /path/to/your/project
$ run gears init
Creating .gears directory...
├── sessions/     # Daily AI conversation logs
├── story/        # Feature specifications
├── adr/          # Architecture decisions
├── memory/       # Project knowledge base
└── context/      # Current work tracking
[OK] .gears initialized

Already Initialized

If you run init in a project that already has a .gears directory, the command will detect this and not overwrite existing files:

$ run gears init
.gears directory already exists

Directory Purpose Guide

sessions/

Daily session logs documenting what was worked on each day. Files are named YYYY-MM-DD.md. These help AI agents understand recent project history and maintain context across conversations.

Created by: gears session command

story/

Feature stories and specifications that define what needs to be built before implementation begins. Stories serve as implementation specs for AI agents.

Created by: gears story new <name> command

adr/

Architectural Decision Records that document important technical decisions, design patterns, and code architecture. These explain the "why" behind working code.

Created by: gears adr new <title> command

memory/

Project-specific knowledge base, conventions, patterns, and context that should be remembered across sessions. This is freeform documentation.

Created manually or by AI agents during development

context/

Current work tracking, active tasks, and immediate context. This directory contains information about what's currently being worked on.

Created manually or by AI agents during development

Common Workflows

Starting a New Project with Gears

# 1. Navigate to project root
cd /path/to/project

# 2. Initialize Gears
gears init

# 3. Authenticate with the cloud platform
gears auth

# 4. Create your first session
gears session

# 5. Start documenting
gears story new "user authentication"

Team Setup

After cloning a repository that already uses Gears:

# 1. The .gears directory already exists in the repo
cd /path/to/cloned-project

# 2. Authenticate with your own account
gears auth

# 3. Pull the team's shared documentation
gears sync pull

# 4. Create your session file
gears session

Troubleshooting

Permission Denied

Problem: Cannot create .gears directory

Permission denied: .gears

Solution: Ensure you have write permissions in the current directory:

# Check current directory permissions
ls -la

# Fix permissions (Unix/Mac)
chmod u+w .

# On Windows, check folder properties

Directory Already Exists

Problem: .gears already exists but you want to reinitialize

Solution: This is usually not needed. The .gears directory intentionally persists to preserve your documentation. If you truly need to start fresh:

# Backup first (important!)
cp -r .gears .gears.backup

# Remove (careful!)
rm -rf .gears

# Reinitialize
gears init

Git Integration

It's recommended to commit your .gears directory to version control:

# .gitignore - add config.json (contains auth token)
echo ".gears/config.json" >> .gitignore

# Commit the structure
git add .gears/
git commit -m "Initialize Gears documentation framework"

What to commit:

• ✅ .gears/sessions/ - Team can see what was worked on
• ✅ .gears/story/ - Shared feature specifications
• ✅ .gears/adr/ - Architectural decisions
• ✅ .gears/memory/ - Project knowledge
• ✅ .gears/context/ - Current work state
• ❌ .gears/config.json - Contains personal auth token (add to .gitignore)

Related Commands

• gears auth - Authenticate with mygears.dev
• gears session - Create today's session file
• gears story - Manage feature stories
• gears adr - Document architectural decisions
• gears sync - Sync files to cloud

Next Steps

After initializing Gears:

1. Authenticate: Run gears auth to connect to the cloud platform
2. Create a session: Run gears session to start documenting today's work
3. Write a story: Run gears story new "feature name" to define your first feature
4. Sync to cloud: Run gears sync push to backup your documentation

← Back to CLI Overview | Command: auth →