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

# 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 for setup and usage.

AI Provider Setup

Before using AI features, add a provider via CLI:

# 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

# 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

# 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

# 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)

# 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

# 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.

// 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 for the full API reference.

Documentation

• Architecture Overview
• Socket Protocol
• Workspace Management
• Drone Documentation
• UI Design Guide
• gadget-tasks Documentation

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 for details.

---

Status: v1.0.1 — First release. Self-hosted agentic engineering platform with local/self-hosted AI model support, complete Chat Session UI, subagent processing, and workspace management.
Last Updated: May 17, 2026