GSD Agent - Local Filesystem Sync Daemon

The GSD Agent is a lightweight Node.js daemon that runs on your local machine, automatically discovering GSD projects and synchronizing their planning files to the cloud for real-time web UI updates.

Features

• Real-time Sync: Changes to your .planning/ directories sync to the cloud within seconds
• Multi-user Support: Secure authentication and data isolation for each user
• Automatic Discovery: Finds GSD projects in your configured watch directories
• Conflict Resolution: Handles concurrent changes between local and web UI
• Large File Support: Files >200KB automatically uploaded to secure storage
• Secure Authentication: Device flow authentication with encrypted credentials

Prerequisites

• Node.js 20+ installed
• Git installed on your system
• Active GSD account (sign up at your GSD web UI)

Installation

Public npm Package (Recommended)

npm install -g gsd-agent

This installs the agent globally on your system.

Run Without Installing

npx gsd-agent@latest auth
npx gsd-agent@latest start

This runs the agent without installing it permanently.

Quick Start

1. Authenticate with your account

gsd-agent auth

This will:

• Generate a device code
• Display instructions to visit the web UI
• Prompt you to enter the code
• Complete authentication flow

2. Start the agent daemon

gsd-agent start

3. Verify status

gsd-agent status

Commands

Configuration

Configuration is stored in ~/.gsd-agent/config.json:

{
  "watch_dirs": [
    "~/Projects",
    "~/Code",
    "~/workspace"
  ],
  "ignored_patterns": [
    "node_modules/",
    ".git/",
    "dist/",
    "build/",
    "*.log"
  ],
  "log_level": "INFO",
  "batch_size": 50,
  "debounce_ms": 300
}

How It Works

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  Local Files    │    │  GSD Agent      │    │  Cloud (Web UI) │
│  (.planning/)   │◄──►│  (Node.js)      │◄──►│  (Supabase)     │
│                 │    │  - FileWatcher  │    │  - Database     │
│  MyProject/     │    │  - SyncEngine   │    │  - Storage      │
│  └─ .planning/  │    │  - Realtime     │    │  - Realtime     │
│     ├─ PLAN.md  │    │  - Auth Flow    │    │                 │
│     ├─ STATE.md │    │                 │    │                 │
│     └─ etc...   │    │                 │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘

1. File Watching: Agent monitors .planning/ directories for changes
2. Local Processing: Changes batched and processed locally
3. Cloud Sync: Changes securely transmitted to Supabase
4. Real-time Updates: Web UI receives updates via Supabase Realtime
5. Web Changes: UI changes pushed back to local files

Security

• End-to-End Encryption: All data encrypted in transit
• Secure Storage: Credentials stored with restricted permissions (0600)
• User Isolation: Row-level security ensures data isolation
• Token Management: Automatic refresh and secure storage
• Audit Trail: All operations logged for security review

Troubleshooting

Agent won't start

• Check authentication: gsd-agent status
• Verify credentials file exists: ~/.gsd-agent/credentials.json
• Check logs: gsd-agent logs

Files not syncing

• Ensure .planning/ directory exists in your project
• Verify watch directories in config
• Check network connectivity to Supabase

Authentication issues

• Run gsd-agent disconnect then gsd-agent auth
• Clear credentials: rm -rf ~/.gsd-agent/credentials.json
• Re-authenticate

Auto-start

Linux (systemd)

# Create systemd user service
mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/gsd-agent.service << EOF
[Unit]
Description=GSD Agent
After=network.target

[Service]
Type=simple
ExecStart=$(which gsd-agent) start
Restart=always

[Install]
WantedBy=default.target
EOF

systemctl --user enable gsd-agent
systemctl --user start gsd-agent

macOS (launchd)

cat > ~/Library/LaunchAgents/com.gsd.agent.plist << EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.gsd.agent</string>
    <key>ProgramArguments</key>
    <array>
        <string>$(which gsd-agent)</string>
        <string>start</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>
EOF

launchctl load ~/Library/LaunchAgents/com.gsd.agent.plist

Development

# Clone and install
git clone https://github.com/your-org/gsd-agent.git
cd gsd-agent
npm install

# Build
npm run build

# Development mode
npm run dev

# Run tests
npm test

Support

• Documentation: https://gsd.fahad.ink/docs
• Issues: https://github.com/your-org/gsd-agent/issues
• Community: https://discord.gg/your-server

Note: This agent requires an active internet connection to sync with the cloud. All data is encrypted and secured according to industry standards.