bytelyst-devops-tools/agent-queue/README.md

agent-queue

A zero-dependency folder "kanban" runner for headless coding-agent CLIs — Devin, Claude Code, and OpenAI Codex. Drop prompt .md files into a folder, and they get executed (in auto-approve mode) one slot at a time, moving through inbox → doing → done/failed with live status.

Why this exists: the agent CLIs ship a minimal local interface (no built-in batch/queue/dashboard — that lives in their cloud products). This is the ~250-line glue that turns "run one prompt interactively" into "queue many and walk away."

---

Quick start

cd learning_ai_devops_tools/agent-queue
chmod +x agent-queue.sh
./agent-queue.sh init

# queue a roadmap for Devin, running in the tracker-web repo, auto-approving everything
./agent-queue.sh add ~/roadmaps/UX-2.md \
  --engine devin \
  --cwd /Users/sd9235/code/mygh/learning_ai_common_plat/dashboards/tracker-web \
  --yolo

# start processing (foreground; Ctrl-C to stop). Run up to 2 agents at once.
./agent-queue.sh run --max 2

In a second terminal, watch progress:

./agent-queue.sh watch

  AGENT QUEUE  /…/agent-queue/queue
  inbox 3   doing 2   done 5   failed 0   running 2/2

  RUNNING
    20260528-2130__UX-2        devin     4m12s  pid 51234  ⏺ Edited src/app/dashboard/items/page.tsx
    20260528-2131__UX-3        claude    1m02s  pid 51290  Running: pnpm typecheck

---

How a task is configured

Each .md carries optional frontmatter telling the runner which engine to use, which directory to run in, and whether to auto-approve:

---
engine: devin          # devin | claude | codex   (default: $AGENT_QUEUE_ENGINE)
cwd: /abs/path/to/repo # where the agent executes   (default: cwd when added)
yolo: true             # auto-approve ALL tools      (default: true)
---

# Your task / roadmap goes here
...

add --engine/--cwd/--yolo will inject this frontmatter for you if the file doesn't already have a --- block.

Engine mapping

engine:	Command run	Auto-approve flag (yolo: true)
devin	devin -p --prompt-file <file>	--permission-mode dangerous
claude	claude -p "<file contents>"	--dangerously-skip-permissions
codex	codex exec "<file contents>"	--dangerously-bypass-approvals-and-sandbox

Flags drift between CLI versions — if one changes, edit build_agent_cmd() in agent-queue.sh (it's the single place each engine is mapped).

Commands

Command	What it does
init	create the queue/ folders
add <file> [--engine E] [--cwd P] [--yolo|--no-yolo]	queue a prompt into inbox/
run [--max N] [--engine E] [--once]	process the inbox (foreground loop)
status	kanban counts + running-worker table
watch [interval]	live status, redrawn every N seconds (default 2)
stop	kill running workers + the run loop
logs <job> [-f]	print / follow a job's log

Folder layout

queue/
  inbox/    # drop / queued .md files (oldest picked first)
  doing/    # currently executing
  done/     # exited 0
  failed/   # non-zero exit (or bad cwd)
  logs/     # <job>.log — full agent output
  .state/   # <job>.meta heartbeats + daemon.pid (runtime only)

Config (env overrides)

Var	Default	Meaning
AGENT_QUEUE_ROOT	./queue	where the kanban folders live
AGENT_QUEUE_MAX	2	max concurrent agents
AGENT_QUEUE_ENGINE	devin	default engine when none in frontmatter
AGENT_QUEUE_POLL	3	inbox poll interval (seconds)
DEVIN_BIN / CLAUDE_BIN / CODEX_BIN	autodetected	override CLI binary paths

⚠️ Safety

Running agents with yolo: true means no approval prompts — they will edit files, run shell commands, and commit unattended. Mitigate:

• Prefer scope-locked prompt files (e.g. "edit only under dashboards/tracker-web/").
• Tell prompts not to git push — review commits before they leave your machine.
• Avoid queueing two tasks that touch the same repo concurrently (git contention). Use --max 1 if all tasks share a repo.
• Watch cost: each job is a full agent session.

Roadmap / nice-to-haves

• --push opt-in + per-repo lock to serialize same-repo jobs automatically.
• Node/TS rewrite with a richer live TUI dashboard.
• done-folder retention / archive by date.