Skip to content
Documentation

Subagents, background tasks, and loops

The agent can split a large request into pieces, run them in parallel, and keep work going in the background while you continue. Everything described here runs inside your terminal session and stops when the session ends.

A subagent is a separate agent with its own fresh context, instructions, and tool list. Eve starts subagents when a task benefits from parallelism, for example to search multiple modules of a large codebase, run benchmarks, or execute independent refactors concurrently. Only the subagent’s final answer returns to the main conversation, keeping the primary context window compact.

  • Subagents run in parallel, up to 32 at a time by default. Eve can launch batches of parallel tasks in a single turn for maximum throughput.
  • A subagent can start its own subagents, up to two levels deep.
  • Subagents never get more permissions than your session. Their permission prompts appear in your terminal, labelled with the subagent’s name, one at a time.
  • Multi-hour workflows and complex turn suspensions are supported up to 2,000 turn cycles.
  • Each subagent turn is a normal agent turn and counts toward your limits.
AgentToolsUse
generalEvery local and CHAMPREP tool the session hasSelf-contained pieces of a larger task.
exploreRead-only local toolsFast codebase search that returns conclusions.
planRead-onlyA step-by-step implementation plan.
reviewRead-only, plus read-only gitReviewing a diff, branch, or merge request.
platformCHAMPREP tools only; no local files or commandsWork across your CHAMPREP services.
/agents
/agents run explore where is the invoice total calculated?
@explore where is the invoice total calculated?

@agent-name prompt starts the agent as a background task and reports its answer when it finishes. Create your own agents with /agents create NAME; see Custom agents.

For multi-step requests Eve keeps a live task list with pending, in-progress, and done items. Press Ctrl+T to show or hide it, or run /todos.

Eve can start long-running commands, such as a dev server, a file watcher, a compiler, or long test suites, in a background shell and keep working. It monitors outputs asynchronously and can wait for patterns such as server listening or FAIL before continuing.

  • Up to 64 background shells can run simultaneously.
  • Live background activity is tracked on the statusline (e.g. 🐚 2 shells) and turn status summary (⚡ 2 shell(s), 3 agent(s) active).
  • Use /shells or /procs to open the dedicated shells inspector showing PIDs, command lines, exit codes, and output tails.

Run a prompt repeatedly in the current session:

/loop 5m check whether the deploy finished and summarise any errors
/loop --max 10 30m run the test suite and fix new failures
/loop keep improving test coverage for src/billing
/loop stop
  • With an interval between 30s and 24h, the prompt runs on that schedule.
  • Without an interval, the loop is self-paced: the agent decides when to run next, between one minute and one hour later.
  • A loop stops after 50 runs by default; change this with --max N. It also stops with /loop stop [id] or when you exit.

Each run is a normal turn: it uses your limits and asks for permission like any other turn.

/tasks lists everything running in the background — subagents, background shells, and loops — with elapsed time. /shells (or /procs) focuses specifically on active and completed shell processes.

/tasks
/tasks tail ID
/tasks attach ID
/tasks stop ID
/tasks stop all
/shells
/procs

The status line shows how many tasks and shells are active. /exit warns you before leaving while background processes or tasks are still running.

Background tasks, subagents, and the number of parallel subagents are plan features. See Plans and limits.

A git worktree gives the session its own checkout, so parallel sessions or subagents never edit the same files.

Terminal window
champrep ai --worktree
champrep ai --worktree fix-rounding
/worktree fix-rounding
/worktree exit

The worktree is created under .champrep/worktrees/NAME on a new branch ai/NAME. When you leave it, a worktree without changes is removed; one with changes is kept and reported so you can commit or discard them. A custom agent can also set isolation: worktree to always work in its own worktree.

/review
/review main
/review !42
/security-review
  • With no argument, /review reviews your uncommitted and staged changes.
  • With a branch or ref, it reviews that branch against the current HEAD.
  • With !NUMBER or a merge request URL, it reviews a CHAMPREP Code merge request through your CHAMPREP tools.

/security-review looks for exploitable issues such as injection, authorization gaps, committed secrets, and path traversal. Both commands run the read-only review agent and report findings by severity with file and line.