# 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

```bash
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:

```bash
./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:

```md
---
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` (bash), redrawn every N seconds (default 2) |
| `dash [--interval N]` | richer **Node** live dashboard — running workers (engine, elapsed, last log line) + recent done/failed |
| `stop` | kill running workers + the run loop |
| `logs <job> [-f]` | print / follow a job's log |

## Via `bytelyst-cli.sh`

Wired into the repo's unified CLI (no GitHub token required for this subcommand):

```bash
./bytelyst-cli.sh agent-queue run --max 2     # full passthrough
./bytelyst-cli.sh aq status                   # short alias
```

## 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.