Developer Setup

Set up your local development environment for contributing to Decepticon.

Prerequisites

• Docker with Docker Compose v2
• Git
• (Optional) uv for local linting and type checking

Clone & Start

git clone https://github.com/PurpleAILAB/Decepticon.git
cd Decepticon

Start the development environment with hot-reload:

# Terminal 1 — Start services with file watching
make dev

# Terminal 2 — Open the interactive CLI
make cli

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

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

# Run full test suite inside container
make test

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

Contributing Guide

Learn the contribution workflow — branching, commits, and pull requests.