qtzx06/yolodex

yolodex

architecture

flowchart LR
  A["data source (any unlabeled data)"] --> B["collect"]
  B --> C["label"]
  C --> D["augment"]
  D --> E["train"]
  E --> F["eval"]
  C -. "parallel subagents in git worktrees" .-> C
  F --> G{"meets target?"}
  G -- "no" --> C
  G -- "yes" --> H["complete"]

components

• skills runtime: codex skills
• pipeline skills: collect, label, augment, train, eval, yolodex
• orchestration loop: yolodex.sh + AGENTS.md
• shared helpers: shared/utils.py

installation

git clone https://github.com/qtzx06/yolodex && cd yolodex
bash setup.sh

requirements:

• macos, linux, or windows
• python 3.11+
• codex cli (latest — supports forked skill contexts and per-skill model overrides)

codex workflow (main path)

1. start codex in repo root
2. use the yolodex skill to gather config
3. run labeling with subagents when needed
4. iterate until eval target is met

example:

$ codex
> use the yolodex skill to train a detector from this video: https://youtube.com/...
> classes: player, weapon, vehicle

codex determines how many subagents to spawn for labeling based on the dataset size:

bash .agents/skills/label/scripts/dispatch.sh 

run modes

autonomous loop:

bash yolodex.sh

manual skills:

uv run .agents/skills/collect/scripts/run.py
bash .agents/skills/label/scripts/dispatch.sh 4
uv run .agents/skills/augment/scripts/run.py
uv run .agents/skills/train/scripts/run.py
uv run .agents/skills/eval/scripts/run.py

config

minimal config.json:

{
  "project": "my-project",
  "video_url": "https://youtube.com/watch?v=YOUR_VIDEO",
  "classes": ["player", "weapon", "vehicle"],
  "label_mode": "codex",
  "target_accuracy": 0.75,
  "num_agents": 4,
  "fps": 1,
  "yolo_model": "yolov8n.pt",
  "epochs": 50,
  "train_split": 0.8,
  "seed": 42
}

key fields:

outputs

• eval: runs//eval_results.json
• frames: runs//frames/
• label previews: runs//frames/preview/
• trained weights: runs//weights/best.pt

repo layout

yolodex/
├── .agents/skills/
│   ├── yolodex/
│   ├── collect/
│   ├── label/
│   ├── augment/
│   ├── train/
│   └── eval/
├── shared/utils.py
├── pipeline/main.py
├── docs/
├── yolodex.sh
├── setup.sh
├── AGENTS.md
├── config.json
├── progress.txt
└── pyproject.toml

docs

• docs/usage.md
• docs/models.md
• docs/skills.md
• docs/architecture.md
• docs/changelog.md

contributing

contributions are welcome.

standard flow:

1. fork the repo and create a branch from main
2. keep changes scoped and explain the why in your pr
3. run relevant checks before opening the pr
4. open a pull request with:
   • clear summary
   • test/validation notes
   • screenshots/log snippets when relevant

if you’re planning a bigger change, open an issue first so we can align on direction.

license

mit

---

made with love at openai ♡