# @siftd/connect-agent

Master orchestrator agent that connects to [Connect](https://connect.siftd.app) - 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

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

# 2. Pair your machine (with API key)
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

The agent runs as a **master orchestrator** (requires an Anthropic API key):
- 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

## Commands

```bash
# 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` - Show runtime details
- `/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:

```typescript
// 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

### Model + Cost Controls (Optional)

- `LIA_FORCE_OPUS` - Defaults to `1`; set to `0` to allow model overrides
- `LIA_MODEL` - Explicit model override (defaults to Opus 4.5 when forced)
- `LIA_MAX_BUDGET_USD` - Per-worker budget cap (USD) for Claude Code CLI
- `LIA_TOOL_MAX_TOKENS` - Max tokens for `/todo` + `/cal` tool calls
- `LIA_WORKER_VERBOSE` - Set to `1` for verbose worker logging

### Usage Logging

Anthropic usage is logged per channel in:

```
~/Lia-Hub/shared/outputs/.lia/usage.jsonl
```

## Requirements

- Node.js 18+
- [Claude Code CLI](https://claude.ai/code) 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