Agent Workflows

This guide covers how to use loop-task to schedule and run AI coding agents on a recurring cadence. You'll learn how to set up agent loops, chain tasks, and monitor results - all without keeping a terminal open.

Why loop-task for agents?

AI coding agents - Claude Code, Codex, OpenCode - work best in small, focused bursts. A single massive session burns through context windows, loses steam after 20 minutes, and costs more than it's worth.

Loop-task solves this by running agents on a schedule. Instead of one marathon session, you run a sprint every 30 minutes. The agent picks up a small piece of work, completes it, and exits. Loop-task handles the scheduling, persistence, crash recovery, and monitoring.

Basic agent loop

There are three ways to schedule an agent loop. All three produce the same result: a recurring loop that runs your agent command.

CLI

loop-task new 30m -- opencode run "find missing translations and translate them, 3 max"

The -- separator tells loop-task that everything after it is the command to run. The command runs in a shell, so pipes, redirects, and shell operators all work.

loop-task new 1h -- claude "review open pull requests and comment on any issues"

TUI

1. Open the loop-task TUI: loop-task
2. Press n to create a new loop
3. Enter the interval (e.g. 30m)
4. Enter the agent command (e.g. opencode run "process backlog items")
5. Press Enter to confirm

The loop appears in the board immediately and runs on its next scheduled tick.

HTTP API

POST /api/loops
Content-Type: application/json

{
  "interval": "30m",
  "command": "opencode run \"process backlog items\"",
  "cwd": "/home/user/project"
}

{
  "id": "loop_abc123",
  "interval": "30m",
  "status": "active",
  "nextRun": "2026-07-09T14:30:00Z"
}

Practical examples

Translation pipeline

Every 30 minutes, run an agent to find and fix missing translations. The agent scans for untranslated strings, translates up to 3 of them, and commits the result.

loop-task new 30m -- opencode run "find missing translations and translate them, 3 max"

Backlog processing

Every hour, have an agent pick up the next unassigned issue from your tracker, claim it, and start working on a fix.

loop-task new 1h -- opencode run "find the oldest unassigned issue, claim it, and start working on it"

Code review

Every 2 hours, run an agent to review open pull requests and leave comments.

loop-task new 2h -- opencode run "review open PRs, comment on any that need changes"

Test runner

Every 15 minutes, run the test suite and get notified on failures. This is a shell command - no agent needed.

loop-task new 15m -- npm test && echo "Tests passed" || echo "Tests failed"

Chaining agents with tasks

Combine loop-task's task chaining (see task-chaining.mdx) with agent loops for multi-step pipelines.

Here's a three-stage pipeline:

Stage 1 - Find issues: An agent scans the codebase and writes a JSON report of all issues found.

Stage 2 - Fix issues: A second loop picks up the report and fixes each issue, using {{key}} templates to pass file paths and descriptions from the JSON output.

Stage 3 - Create PR: A final loop collects all fixes, creates a branch, opens a pull request with a summary of changes.

Each stage runs on its own cadence and passes its output to the next stage via the task result cache.

Monitoring agent loops

CLI

Check the status of all loops:

loop-task status

Output shows each loop's ID, interval, last exit code, next run time, and recent run history:

ID            INTERVAL   LAST EXIT   NEXT RUN          COMMAND
loop_abc123   30m        0           14:30:00          opencode run "translate"
loop_def456   1h         1           15:00:00          opencode run "backlog"
loop_ghi789   2h         -           16:00:00          opencode run "review PRs"

Exit code 0 means success. A non-zero exit means the command failed - check the logs.

TUI

Open the board, select a loop, and view its run history. The TUI shows a sparkline of recent exit codes, the last few log lines, and the next scheduled run. Use the arrow keys to navigate between loops.

HTTP API

Fetch recent logs for a loop:

GET /api/loops/loop_abc123/logs?tail=50

{
  "logs": [
    {
      "run": 47,
      "exitCode": 0,
      "startedAt": "2026-07-09T14:00:00Z",
      "duration": "12.3s",
      "output": "Found 3 missing translations\nTranslated 3/3\nCommitted to main"
    }
  ]
}

Verify then fix

A common agent workflow is to verify code on a cadence, then have an AI agent fix whatever broke. Loop-task's stderr capture makes this simple.

Run a verify task that lints, tests, and builds. When it fails, the failure chains to an AI fix task that reads {{output}} to see the actual errors. Here is the pattern as a recipe:

version: 2

loops:
  - taskId: verify
    intervalHuman: "30m"
    description: Verify then fix
    immediate: true

tasks:
  - id: verify
    name: Lint, test, build
    command: sh -c 'pnpm lint && pnpm test && pnpm build'
    onSuccessTaskId: commit
    onFailureTaskId: fix

  - id: fix
    name: AI fix
    command: opencode run --agent fullstack-engineer "Fix errors: {{output}}"
    onSuccessTaskId: verify
    onFailureTaskId: null

  - id: commit
    name: Commit clean build
    command: sh -c 'git add -A && git commit -m "verified: lint, tests, build"'
    onSuccessTaskId: null
    onFailureTaskId: null

When the verify task fails, its stderr (compiler errors, test failures, lint violations) is captured into {{output}}. The fix task uses {{output}} to see exactly what went wrong. No custom JSON wrappers needed.

The fix task chains back to verify on success, so the pipeline retries until everything passes. Once verify succeeds, it chains to commit instead.

Tips

• Set --max-runs to limit execution. Without it, a loop runs forever. Add --max-runs 10 to stop after 10 executions. This prevents runaway agent loops.

• Scope the agent with --cwd. If your agent needs to operate in a specific project directory, set --cwd /path/to/project. The command runs from that directory.

• Use projects to group loops. Assign agent loops to the same project to organize related automation. View all loops in a project with loop-task status --project translation-pipeline.

• Check logs on failure. Run loop-task status to see the last exit code. If it's non-zero, inspect the logs via GET /api/loops/:id/logs or the TUI run history. Most agent failures are transient - the loop retries on its next tick.

• Keep agent commands short. A focused agent task runs faster, costs less, and is easier to debug than a monolithic prompt. Prefer the pattern of many small loops over one big one.