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

## 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/ai`   | Shared AI API abstraction — Ollama and OpenAI, called by both            |

## AI API Abstraction (`@gadget/ai`)

All AI API calls throughout the Gadget Code ecosystem route through `@gadget/ai`. No consumer code imports Ollama or OpenAI SDKs directly. No consumer code checks `provider.sdk` after the factory call. The shared module translates Gadget Code's internal API contract into whatever provider is configured, and translates responses back to Gadget Code's internal types.

See `packages/ai/README.md` for the full API reference.

## Setup

```bash
pnpm install
```

## Build

```bash
pnpm -r build              # build all packages
pnpm --filter @gadget/ai build
pnpm --filter gadget-drone build
pnpm --filter gadget-code build:backend
```

## Run

```bash
# Backend
pnpm --filter gadget-code dev

# Drone worker (in a project workspace directory)
pnpm --filter gadget-drone dev
```

## Architecture

### @gadget/ai

AI API calls are handled by `@gadget/ai`, which both projects depend on. This keeps all AI SDK knowledge in one place, and currently implements:

- [AiApi](./packages/ai/src/api.ts) - abstract base class for all AI APIs/SDKs
- [OllamaAiApi](./packages/ai/src/ollama.ts) - Ollama API implementation
- [OpenAiApi](./packages/ai/src/openai.ts) - OpenAI API implementation

### gadget-drone

gadget-drone is a headless process runs on end-user machines, connecting via Socket.IO to gadget-code, to receive and execute work orders for the agentic workflow loop.

At startup, gadget-drone examines `process.cwd()` to determine if it's a workspace directory, and if so, starts a worker process that connects to gadget-code and waits for work orders. It processes work orders in project directories in the gadget-drone workspace directory, and communicates events, status, and results to the IDE via gadget-code's web services and Socket.IO.

gadget-drone never connects directly to MongoDB or Redis — it communicates entirely through the Gadget Code API.

### gadget-code

gadget-code runs on server infrastructure (MongoDB, Redis, etc.) and serves the browser-based IDE. The IDE connects to gadget-code via Socket.IO to send and receive commands in chat sessions to gadget-drone.

gadget-code can be stacked on a single host for local development, and can achieve significant scale on a single host. It can also be deployed in tiers, potentially made of clusters, and the web tier can be horizontally scaled for production use with high availability.

Libraries such as [redis-adapter](https://github.com/socketio/socket.io-redis-adapter) and [redis-emitter](https://github.com/socketio/socket.io-redis-emitter) are used for message routing and distribution in the Socket.IO library, handling the real-time message routing among gadget-code, gadget-drone, and the IDE running in the browser.