179108504f
Add a zero-dependency, bash 3.2-compatible queue runner that executes prompt .md files through headless coding-agent CLIs in auto-approve mode, moving them inbox -> doing -> done/failed with per-job logs and live status. - pluggable engine drivers (devin --prompt-file, claude/codex via stdin) - per-task YAML frontmatter: engine, cwd, yolo - subcommands: init, add, run (--max N), status, watch, stop, logs - runtime queue/ state gitignored
128 lines
4.4 KiB
Markdown
128 lines
4.4 KiB
Markdown
# 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`, 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.
|