@siftd/connect-agent

Master orchestrator agent that connects to Connect - control Claude Code remotely from any browser.

What is this?

Connect Agent runs on your machine and bridges the Connect web app to Claude Code CLI. It's not just a relay - it's a master orchestrator with:

• Persistent Memory - Remembers your preferences, projects, and context across sessions
• Worker Delegation - Delegates complex tasks to Claude Code CLI workers
• Task Scheduling - Schedule tasks for future execution
• Hub System - Organized workspace at ~/Lia-Hub/ for state management
• Gallery View - See all files your workers create in the UI
• Progress Tracking - Real-time progress bars for running workers

Quick Start

# 1. Go to https://connect.siftd.app and get a pairing code

# 2. Pair your machine (with API key for full orchestrator mode)
npx @siftd/connect-agent pair <CODE> --api-key <YOUR_ANTHROPIC_API_KEY>

# 3. Start the agent
npx @siftd/connect-agent start

On first start, the agent creates ~/Lia-Hub/ with:

• AGENTS.md - Agent identity
• CLAUDE.md - Your custom instructions
• LANDMARKS.md - Current state
• notebook-a/ - Working notes and worker logs

Modes

Orchestrator Mode (Recommended)

When you provide an Anthropic API key, the agent runs as a master orchestrator:

• Uses Claude API directly for the orchestration layer
• Maintains persistent memory about you and your projects
• Delegates file/code work to Claude Code CLI workers
• Schedules future tasks
• Reads hub files for context on every startup

Simple Relay Mode

Without an API key, the agent acts as a simple relay to claude -p --continue.

Commands

# Pair with the web app
connect-agent pair <CODE> [--api-key <KEY>]

# Start processing messages
connect-agent start [--interval <ms>]

# Check status
connect-agent status

# Set API key (without re-pairing)
connect-agent set-key <KEY>

# Clear configuration
connect-agent logout

Special Commands (via web chat)

• /reset or /clear - Clear conversation history
• /mode - Check current mode (orchestrator vs simple)
• /memory - Show memory statistics
• /verbose - Toggle verbose tool output

Hub Structure

~/Lia-Hub/
├── AGENTS.md           # Agent identity and capabilities
├── CLAUDE.md           # Your custom instructions (always followed)
├── LANDMARKS.md        # Current state, active projects
├── MISTAKES.md         # Lessons learned (never deleted)
├── notebook-a/
│   ├── SCRATCHPAD.md   # Working notes and plans
│   └── WORKER-LOG.md   # All worker history (auto-logged)
└── shared/
    └── outputs/        # Worker output files

Edit CLAUDE.md to customize the orchestrator's behavior!

How It Works

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Browser        │────▶│  Connect Server  │◀────│  Connect Agent  │
│  (any device)   │     │  (connect.siftd) │     │  (your machine) │
└─────────────────┘     └──────────────────┘     └────────┬────────┘
                                                          │
                                                          ▼
                                                 ┌─────────────────┐
                                                 │ Master          │
                                                 │ Orchestrator    │
                                                 │ (memory, hub)   │
                                                 └────────┬────────┘
                                                          │ delegates
                                                          ▼
                                                 ┌─────────────────┐
                                                 │ Claude Code CLI │
                                                 │ (file ops, code)│
                                                 └─────────────────┘

The orchestrator understands it's the master, not a worker. It:

1. Loads hub context (AGENTS.md, CLAUDE.md, LANDMARKS.md)
2. Receives your message from the web
3. Searches memory for relevant context
4. Decides what needs to be done
5. Delegates actual work to Claude Code CLI workers
6. Shows progress in real-time
7. Synthesizes results into a clear response
8. Logs workers to WORKER-LOG.md
9. Remembers important things for next time

Customizing Worker Behavior

All worker prompts are defined in src/prompts/worker-system.ts. Update this file to change how ALL workers behave:

// src/prompts/worker-system.ts
export const WORKER_IDENTITY = `...`;
export const WORKER_OUTPUT_FORMAT = `...`;
export function buildWorkerPrompt(task, options) { ... }

Environment Variables

• ANTHROPIC_API_KEY - Alternative to --api-key flag
• VOYAGE_API_KEY - (Optional) For better semantic search embeddings
• DATABASE_URL - (Optional) PostgreSQL for cloud memory persistence

Requirements

• Node.js 18+
• Claude Code CLI installed and authenticated
• Anthropic API key (for orchestrator mode)

Version History

• v0.2.28 - Lia-Hub structure, CLAUDE.md support, standardized worker prompts
• v0.2.27 - Fixed workers opening browser tabs
• v0.2.26 - Gallery view, worker asset tracking
• v0.2.25 - Progress bars, heartbeat system

License

MIT