> ## Documentation Index
> Fetch the complete documentation index at: https://docs.decepticon.red/llms.txt
> Use this file to discover all available pages before exploring further.

# Developer Setup

> Set up your local development environment for contributing to Decepticon.

## Prerequisites

* [Docker](https://docs.docker.com/get-docker/) with Docker Compose v2
* [Git](https://git-scm.com/)
* (Optional) [uv](https://github.com/astral-sh/uv) for local linting and type checking

## Clone & Start

```bash theme={null}
git clone https://github.com/PurpleAILAB/Decepticon.git
cd Decepticon
```

Start the development environment with hot-reload:

```bash theme={null}
# Terminal 1 — Start services with file watching
make dev

# Terminal 2 — Open the interactive CLI
make cli
```

<Info>
  Development runs in the **same Docker containers** as production. Source changes are automatically synced into containers via `docker compose watch` — no manual rebuilds needed.
</Info>

## Make Targets

| Command      | Description                                                   |
| ------------ | ------------------------------------------------------------- |
| `make dev`   | Build images + start with hot-reload (`docker compose watch`) |
| `make cli`   | Open the interactive CLI (run in a separate terminal)         |
| `make start` | Start in background, production-like (no hot-reload)          |
| `make stop`  | Stop all services                                             |
| `make test`  | Run `pytest` inside the container                             |
| `make lint`  | Run linter + type checker locally (requires `uv sync --dev`)  |
| `make help`  | Show all available Makefile targets                           |

## Project Structure

```
Decepticon/
├── decepticon/             # Core Python package (LangGraph agents)
│   ├── agents/             # 16 specialist agent definitions + system prompts
│   ├── core/               # Schemas (RoE, ConOps, OPPLAN), engagement lifecycle, config
│   ├── llm/                # Model profiles, provider routing, LLM factory
│   ├── middleware/         # OPPLAN, Skills, EngagementContext, Filesystem, SubAgent middleware
│   ├── sandbox_kernel/     # Sandbox-side daemon, jobs, tmux session manager
│   ├── sandbox_server/     # Sandbox-side HTTP server (FastAPI)
│   ├── tools/              # bash, research (Neo4j/CVE), reversing, ad, cloud, web, contracts
│   └── backends/           # Docker / HTTP sandbox backends
├── skills/                 # Skill library (18 categories: per-agent + shared + benchmark)
├── clients/
│   ├── cli/                # React 19 + Ink terminal UI (TypeScript)
│   ├── web/                # Next.js 16 web dashboard (TypeScript, Prisma)
│   ├── launcher/           # Go CLI launcher (Cobra + Charmbracelet Huh v2)
│   └── shared/             # Shared TypeScript packages
├── containers/             # Dockerfiles (sandbox, cli, web, langgraph, litellm, c2-sliver)
├── config/                 # LiteLLM proxy config (litellm.yaml)
├── benchmark/              # CTF evaluation framework (xbow validation-benchmarks)
├── scripts/                # Install and launcher scripts
├── tests/                  # pytest suite
├── docker-compose.yml      # Infrastructure definition
├── langgraph.json          # 19 graph entry points (decepticon orchestrator + soundwave planner + 17 specialists)
└── Makefile                # Development workflow commands
```

## Hot Reload

`make dev` uses `docker compose watch` to monitor source files. When you edit code:

1. Changes are synced into the running containers automatically
2. Affected services restart with the new code
3. No manual `docker compose build` or restart needed

This provides the fastest development loop while maintaining the exact same Docker environment as production.

## Running Tests

```bash theme={null}
# Run full test suite inside container
make test

# Local linting (requires uv)
uv sync --dev
make lint
```

<Card title="Contributing Guide" icon="git-merge" href="/en/contributing/contributing-guide">
  Learn the contribution workflow — branching, commits, and pull requests.
</Card>