File Sync

Understanding how Gears synchronizes your .gears files.

Overview

Gears provides bidirectional file synchronization between your local .gears directory and the cloud. This ensures your project files are backed up, versioned, and accessible from anywhere.

How Sync Works

Push Operation

When you run gears sync push:

  1. Scan - The CLI scans your .gears directory for all files
  2. Checksum - Calculates MD5 checksums for each file
  3. Compare - Compares with cloud versions to detect changes
  4. Upload - Uploads only changed files
  5. Verify - Confirms successful upload

Pull Operation

When you run gears sync pull:

  1. Fetch - Retrieves file list from Gears
  2. Compare - Compares with local files
  3. Download - Downloads new or updated files
  4. Write - Writes files to .gears directory
  5. Verify - Confirms successful download

Supported File Types

Gears syncs all files in your .gears directory:

  • Session Logs (.gears/sessions/*.md)
  • Stories (.gears/story/*.md)
  • ADRs (.gears/adr/*.md)
  • Memory Files (.gears/memory/*.md)
  • Context Files (.gears/context/*.md)

File Versioning

Every file upload creates a new version:

  • Version Number - Incremental version counter
  • Checksum - MD5 hash for integrity verification
  • Timestamp - When the file was uploaded
  • Size - File size in bytes

You can view file history and download previous versions from the web dashboard.

Conflict Resolution

Local Changes vs Cloud Changes

If both local and cloud files have changed:

Pull Behavior:

  • By default, prompts you to choose which version to keep
  • Use --force to always overwrite local with cloud version

Push Behavior:

  • By default, overwrites cloud with local version
  • Creates a new version (old version preserved)

Best Practices

  1. Pull before editing - gears sync pull at start of day
  2. Push frequently - Commit your work regularly
  3. Check activity log - Review changes on web dashboard
  4. Use sessions - Document your work in session files

Performance

Incremental Sync

Only changed files are transferred:

Working with AI Agents

Sync commands are excellent teaching tools for AI agents. Always have your agent:

  • Run gears sync push to see what files exist and where they're stored
  • Run gears sync pull to understand how cloud sync works
  • Review sync output to learn about your documentation structure

The detailed output from sync commands helps agents understand:

  • What documentation you've created
  • Where files live in the .gears directory
  • How the synchronization system works
  • What information is available for reference

This makes the agent much more effective at helping you manage your project documentation.

  • Checksum comparison prevents unnecessary uploads
  • Reduces bandwidth usage
  • Faster sync times

Caching

The CLI caches file metadata locally:

  • Speeds up subsequent syncs
  • Located in ~/.gears/cache/
  • Can be cleared if issues occur

Security

Encryption

  • In Transit - All data encrypted with TLS
  • At Rest - Files stored securely on servers
  • Authentication - Token-based API access

Token Management

Your API token is stored in:

  • Windows: %APPDATA%\.gears\config.json
  • macOS/Linux: ~/.gears/config.json

Keep this file secure. Never commit it to version control.

Monitoring

Activity Log

View all sync operations in the web dashboard:

  • Go to Activity Log
  • Filter by type: file.pushed, file.pulled
  • See timestamp, file names, and checksums

File Browser

Browse all synced files:

  • Go to Files
  • View file contents
  • Download individual files
  • See version history

Troubleshooting

Sync Fails

If sync fails:

  1. Check authentication - gears auth to re-authenticate
  2. Verify network - Ensure you can reach Gears
  3. Check permissions - Ensure .gears/ directory is writable
  4. Clear cache - Delete ~/.gears/cache/ and retry

Stuck Files

If a file won't sync:

  1. Check file size - Large files may timeout
  2. Verify checksum - File may be corrupted
  3. Force push - gears sync push --force

Missing Files

If files are missing after pull:

  1. Check web dashboard - Verify files exist in cloud
  2. Check local directory - Ensure .gears/ exists
  3. Re-pull - gears sync pull --force

API Integration

Sync can also be triggered via API. See API Reference for details.

Next Steps

← Back to Documentation Home
Last updated: Mar 27, 2026