luk/GODSPEED_SYNC.md

Godspeed Sync

A two-way synchronization tool between the Godspeed task management API and local markdown files.

Features

• Bidirectional Sync: Download tasks from Godspeed to markdown files, edit locally, and upload changes back
• Directory Structure: Creates a clean directory structure matching your Godspeed lists
• ID Tracking: Uses hidden HTML comments to track task IDs even when you rearrange tasks
• Markdown Format: Simple - [ ] Task name <!-- id:abc123 --> format for easy editing
• Completion Status: Supports incomplete [ ], completed [x], and cancelled [-] checkboxes
• Notes Support: Task notes are preserved and synced
• CLI Interface: Easy-to-use command line interface with shortcuts

Installation

The Godspeed sync is part of the GTD Terminal Tools project. Make sure you have the required dependencies:

# Install dependencies
uv sync

# Or with pip
pip install requests click

Configuration

Option 1: Environment Variables

export GODSPEED_EMAIL="your@email.com"
export GODSPEED_PASSWORD="your-password"

# OR use an API token directly
export GODSPEED_TOKEN="your-api-token"

# Optional: Custom sync directory
export GODSPEED_SYNC_DIR="~/Documents/MyTasks"

# Optional: Disable SSL verification for corporate networks
export GODSPEED_DISABLE_SSL_VERIFY="true"

Option 2: Interactive Setup

The tool will prompt for credentials if not provided via environment variables.

Getting an API Token

You can get your API token from the Godspeed desktop app:

1. Open the Command Palette (Cmd/Ctrl + Shift + P)
2. Run "Copy API access token"
3. Use this token with GODSPEED_TOKEN environment variable

Usage

Basic Commands

# Download all tasks from Godspeed to local markdown files
python -m src.cli.godspeed download
# OR use the short alias
python -m src.cli.godspeed download  # 'gs' will be available when integrated

# Upload local changes back to Godspeed
python -m src.cli.godspeed upload

# Bidirectional sync (download then upload)
python -m src.cli.godspeed sync

# Check sync status
python -m src.cli.godspeed status

# Open sync directory in file manager
python -m src.cli.godspeed open

# Test connection and SSL (helpful for corporate networks)
python -m src.cli.godspeed test-connection

Workflow Example

1. Initial sync:

   python -m src.cli.godspeed download
   

2. Edit tasks locally: Open the generated markdown files in your favorite editor:

   ~/Documents/Godspeed/
   ├── Personal.md
   ├── Work_Projects.md
   └── Shopping.md
   

3. Make changes:

   # Personal.md
   - [ ] Call dentist <!-- id:abc123 -->
   - [x] Buy groceries <!-- id:def456 -->
     Don't forget milk and eggs
   - [-] Old project <!-- id:ghi789 -->
   - [ ] New task I just added <!-- id:jkl012 -->
   
   # Work_Projects.md  
   - [ ] Finish quarterly report <!-- id:xyz890 -->
     Due Friday
   - [-] Cancelled meeting <!-- id:uvw567 -->
   

4. Sync changes back:

   python -m src.cli.godspeed upload
   

File Format

Each list becomes a markdown file with tasks in this format:

- [ ] Incomplete task <!-- id:abc123 -->
- [x] Completed task <!-- id:def456 -->
- [X] Also completed (capital X works too) <!-- id:ghi789 -->
- [-] Cancelled/cleared task <!-- id:jkl012 -->
- [ ] Task with notes <!-- id:mno345 -->
  Notes go on the next line, indented

Important Notes:

• Don't remove the <!-- id:xxx --> comments - they're used to track tasks
• Don't worry about the IDs - they're auto-generated for new tasks
• Checkbox format matters:
  • Use [ ] for incomplete tasks
  • Use [x] or [X] for completed tasks
  • Use [-] for cancelled/cleared tasks
• Completion status syncs both ways:
  • Check/uncheck boxes in markdown → syncs to Godspeed
  • Mark complete/incomplete/cleared in Godspeed → syncs to markdown
• Completed/cancelled tasks are hidden: When downloading from Godspeed, only incomplete tasks appear in local files (keeps them clean)
• Notes are optional - indent them under the task line
• File names correspond to list names (special characters replaced with underscores)

Directory Structure

By default, files are synced to:

• ~/Documents/Godspeed/ (if Documents folder exists)
• ~/.local/share/gtd-terminal-tools/godspeed/ (fallback)

Each Godspeed list becomes a .md file:

• "Personal" → Personal.md
• "Work Projects" → Work_Projects.md
• "Shopping List" → Shopping_List.md

Sync Metadata

The tool stores sync metadata in .godspeed_metadata.json:

{
  "task_mapping": {
    "local-id-1": "godspeed-task-id-1",
    "local-id-2": "godspeed-task-id-2"
  },
  "list_mapping": {
    "Personal": "godspeed-list-id-1",
    "Work Projects": "godspeed-list-id-2"
  },
  "last_sync": "2024-01-15T10:30:00"
}

API Rate Limits

Godspeed has rate limits:

• Listing: 10 requests/minute, 200/hour
• Creating/Updating: 60 requests/minute, 1,000/hour

The sync tool respects these limits and handles errors gracefully.

Troubleshooting

SSL/Corporate Network Issues

If you're getting SSL certificate errors on a corporate network:

# Test the connection first
python -m src.cli.godspeed test-connection

# If SSL errors occur, bypass SSL verification
export GODSPEED_DISABLE_SSL_VERIFY=true
python -m src.cli.godspeed test-connection

Authentication Issues

# Clear stored credentials
rm ~/.local/share/gtd-terminal-tools/godspeed_config.json

# Use token instead of password
export GODSPEED_TOKEN="your-token-here"

Sync Issues

# Check current status
python -m src.cli.godspeed status

# Verify sync directory
ls ~/Documents/Godspeed/

# Check metadata
cat ~/.local/share/gtd-terminal-tools/godspeed/.godspeed_metadata.json

Common Problems

1. "List ID not found": New lists created locally will put tasks in your Inbox
2. "Task not found": Tasks deleted in Godspeed won't sync back
3. Duplicate tasks: Don't manually copy task lines between files (IDs must be unique)

Development

Testing

Run the test suite:

python test_godspeed_sync.py

File Structure

src/services/godspeed/
├── __init__.py          # Package init
├── client.py            # Godspeed API client
├── sync.py              # Sync engine
└── config.py            # Configuration management

src/cli/
└── godspeed.py          # CLI interface

Contributing

This is part of the larger GTD Terminal Tools project. When contributing:

1. Follow the existing code style
2. Add tests for new functionality
3. Update this README for user-facing changes
4. Test with the mock data before real API calls

License

Same as the parent GTD Terminal Tools project.