Skip to main content

​
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

CommandDescription
make devBuild images + start with hot-reload (docker compose watch)
make cliOpen the interactive CLI (run in a separate terminal)
make startStart in background, production-like (no hot-reload)
make stopStop all services
make testRun pytest inside the container
make lintRun linter + type checker locally (requires uv sync --dev)
make helpShow 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.