gadget/README.md

# Gadget Code

A self-hosted **Agentic Engineering Platform (AEP)** — an IDE that drives autonomous AI agents to perform software engineering work on your behalf, running in your own environment.

## Quick Start

```bash
# Install dependencies
pnpm install

# Start backend (Terminal 1)
cd gadget-code
pnpm dev:backend

# Start frontend (Terminal 2)
cd gadget-code/frontend
pnpm dev

# Open browser to https://localhost:5174
```

## Projects

| Package            | Role                                                                     |
| ------------------ | ------------------------------------------------------------------------ |
| `gadget-code`      | Web service — agentic IDE, browser UI, API server                        |
| `gadget-drone`     | Worker process — runs the agentic workflow loop in workspace directories |
| `gadget-tasks`     | Scheduled task worker — headless IDE client for cron-driven tasks        |
| `@gadget/ai`       | Shared AI API abstraction — Ollama and OpenAI                            |
| `@gadget/ai-toolbox` | Shared AI tool implementations — search, file, plan, subagent tools    |
| `@gadget/api`      | Shared TypeScript interfaces — common types across all packages          |
| `@gadget/config`   | Shared YAML config loader — per-package configuration                    |

## Architecture

```
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Browser IDE │────▶│  gadget-code │────▶│ gadget-drone │
│  (React 19)  │◀────│ (Express 5)  │◀────│  (Worker)    │
└──────────────┘     └──────────────┘     └──────────────┘
       │                    │                      │
       │ Socket.IO          │ MongoDB              │ Files
       │ JWT Auth           │ Redis                │ Git
```

### How It Works

1. **User creates a project** in the browser IDE
2. **User selects a drone** instance to work on the project
3. **User enters a prompt** in the Chat Session view
4. **Prompt flows** IDE → Web → Drone via Socket.IO
5. **Drone executes** the Agentic Workflow Loop (AWL)
6. **Streaming response** flows back: thinking → response → tool calls
7. **Results persist** in MongoDB as ChatTurn records

### Scheduled Tasks (gadget-tasks)

gadget-tasks is a **headless IDE client** that automates the browser IDE flow on a cron schedule. It does not duplicate AI, database, or workspace code — it drives the existing gadget-code platform via REST API and Socket.IO, the same protocol the browser IDE uses.

```
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│ gadget-tasks │────▶│  gadget-code │────▶│ gadget-drone │
│  (Scheduler) │◀────│ (Express 5)  │◀────│  (Worker)    │
└──────────────┘     └──────────────┘     └──────────────┘
       │                    │                      │
       │ REST + Socket.IO   │ MongoDB              │ Files
       │ JWT Auth           │ Redis                │ Git
```

**Per-task flow:**
1. CronJob fires → create ChatSession via REST API
2. Lock drone via Socket.IO `requestSessionLock`
3. Set workspace mode to Agent via `requestWorkspaceMode`
4. Submit task prompt via `submitPrompt` → drone processes work order
5. Receive `workOrderComplete` → release session lock
6. Update `task.lastRun` via `PATCH /projects/:id/tasks/:taskId/lastRun`

See [gadget-tasks documentation](./docs/gadget-tasks.md) for setup and usage.

## AI Provider Setup

Before using AI features, add a provider via CLI:

```bash
# Add Ollama provider (no API key needed)
cd gadget-code
pnpm cli provider add "Local Ollama" ollama http://localhost:11434

# Add OpenAI provider
pnpm cli provider add "OpenAI" openai https://api.openai.com $OPENAI_API_KEY

# List providers
pnpm cli provider ls

# Probe provider for models (discovers available models)
pnpm cli provider probe <provider-id>
```

## User Management

```bash
# Add a user
pnpm cli user add user@example.com password123 "Display Name"

# Grant admin rights
pnpm cli admin grant user@example.com

# Reset password
pnpm cli user password user@example.com newpassword
```

## Development

### Prerequisites

- Node.js 22+
- pnpm 10+
- MongoDB on `localhost:27017`
- Redis on `localhost:6379`
- SSL certificates in `ssl/` directory (for dev servers)

### Build

```bash
# Build all packages
pnpm -r build

# Build specific package
pnpm --filter @gadget/ai build
pnpm --filter gadget-drone build
pnpm --filter gadget-code build
```

### Run Development Servers

```bash
# Backend (gadget-code directory)
cd gadget-code
pnpm dev:backend
# Runs on https://localhost:3443

# Frontend (gadget-code/frontend directory)
cd gadget-code/frontend
pnpm dev
# Runs on https://localhost:5174

# Drone worker (in a workspace directory)
cd ~/my-gadget-workspace
pnpm --filter gadget-drone dev

# Task scheduler (requires running gadget-code + drone)
cd gadget-tasks
pnpm dev -- --user=admin@example.com --password=secret
```

### Global Install (CLI)

```bash
# Link gadget-drone and gadget-tasks globally for CLI use
pnpm link:global

# Now available as system commands
gadget-drone
gadget-tasks --user=admin@example.com --password=secret
```

### Testing

```bash
# Unit tests (gadget-code directory)
cd gadget-code
pnpm test

# E2E tests with Playwright (requires running dev servers)
npx playwright test tests/e2e/project-manager.test.ts
npx playwright test tests/e2e/chat-session.test.ts

# Seed test data for E2E tests
npx tsx scripts/seed-test-drones.ts
```

## Key Features

### Project Manager

- Create and manage projects
- Select available drones (filters out offline)
- View chat session history
- Create new chat sessions with provider/model selection

### Chat Session View

- Real-time streaming responses
- Collapsible thinking content
- Tool call summaries
- Model/mode selection per session
- Session statistics (tool calls, file ops, subagents)

### Workspace Management

- Each drone manages a workspace directory
- Projects cloned into workspace by slug
- Crash recovery via `.gadget/` directory
- Workspace persistence across restarts

## AI API Abstraction

All AI calls route through `@gadget/ai`. No consumer code imports Ollama or OpenAI SDKs directly.

```typescript
// Correct: Use the factory
import { createAiApi } from '@gadget/ai';
const ai = createAiApi(providerConfig);

// Incorrect: Don't import SDKs directly
import { Ollama } from 'ollama'; // ❌
```

See [`packages/ai/README.md`](./packages/ai/README.md) for the full API reference.

## Documentation

- [Architecture Overview](./docs/architecture-stats.md)
- [Socket Protocol](./docs/socket-protocol.md)
- [Workspace Management](./docs/gadget-workspace.md)
- [Drone Documentation](./gadget-drone/docs/gadget-drone.md)
- [UI Design Guide](./gadget-code/docs/ui-design-guide.md)
- [gadget-tasks Documentation](./docs/gadget-tasks.md)

## Monorepo Structure

```
gadget/
├── packages/ai/           # @gadget/ai — AI API abstraction
├── packages/ai-toolbox/   # @gadget/ai-toolbox — Shared tool implementations
├── packages/api/          # @gadget/api — Shared interfaces
├── packages/config/       # @gadget/config — YAML config loader
├── gadget-code/           # Web service + browser IDE
│   ├── src/               # Backend (Express, Socket.IO, Mongoose)
│   ├── frontend/          # Frontend (React, Vite, Tailwind)
│   └── tests/             # Unit + E2E tests
├── gadget-drone/          # Worker process
│   ├── src/               # Drone implementation
│   └── docs/              # Drone documentation
├── gadget-tasks/          # Scheduled task worker
│   └── src/               # Headless IDE client + cron scheduler
└── docs/                  # Architecture & protocol docs
```

## License

Apache 2.0 — See [LICENSE](./LICENSE) for details.

---

**Status:** Production-ready foundation with complete Chat Session UI  
**Last Updated:** May 17, 2026