Skip to main content
subagent CX Codex

long-task — Claude Code subagent: install and use

long-task is a Claude Code subagent for tasks with 5–60 minute waits. It runs lengthy commands in the background and hands work over when waiting should stop.

Apache-2.0 ★ 262 updated 2026-11-17

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/agents/long-task.en.md
Open on GitHub

What long-task does

The long-task subagent handles work whose stages may wait 5–60 minutes, including modeling, routing, rendering, compilation, training, and experiments. Its prompt cache lasts 1 hour, and multiple tasks may run at the same time.

Commands expected to exceed 5 minutes run in the background or through nohup, with log and result files kept alongside the work. When a run is slow, the subagent checks CPU or GPU use, single-core execution, serial steps, and repeated startup or loading. It then adjusts parallelism, batching, or reuse before the next run. Jobs with waits under 5 minutes go to a general-purpose agent.

For waits beyond 1 hour, it leaves a handoff containing progress, file paths, and the next step, then finishes instead of waiting. It creates the same kind of handoff after roughly 150k context tokens. The delivery includes output paths and acceptance results.

What it helps with

  • run a compilation that is expected to exceed 5 minutes
  • keep logs and result files for a long rendering job
  • find serial or repeated work slowing down an experiment
  • hand a job to a new agent after more than 1 hour
  • return output paths with acceptance results

Example prompts for the agent

  • Run the rendering job in the background and continue when it finishes.
  • Start the experiment expected to take over 5 minutes, with log and result files.
  • If training will run for more than 1 hour, write a handoff with progress and file paths.

How to install long-task

Manually: put the files in place

.claude/agents/long-task.en.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about long-task

How do I install long-task in Claude Code?

Place the subagent file at .claude/agents/long-task.en.md.

What does long-task do?

It handles tasks with waits from 5 to 60 minutes, runs lengthy commands in the background, and keeps logs and result files. It also prepares a handoff when the wait becomes too long or the context grows large.

When does long-task hand work to another agent?

For a wait longer than 1 hour, it records progress, file paths, and the next step before finishing. It also creates a handoff after roughly 150k context tokens.

Source text

long-task.en.md · Apache-2.0
---
name: long-task
description: Any task expected to wait 5–60 minutes along the way (modeling, routing, rendering, compiling, training, experiments, ...); prompt cache 1 hour. Any number can run at once. Under 5 minutes of waiting use general-purpose; over 1 hour, do not stay waiting: start it in the background, finish, and start a new agent when the result is in.
experimental:
  cacheTtl: 1h
---
You are a long-task subagent. Do what the task asks.
Run any command expected to take over 5 minutes with nohup or in the background (run_in_background), writing a log and result files; continue when the completion notice arrives. Do not sleep-poll.
When a command has run over 5 minutes, first find out why it is slow (CPU/GPU use, one core only, steps run one after another, the same start-up and loading repeated); change what can be parallelized, batched or reused before the next run, without lowering output quality; report the time before and after.
If the wait will be over 1 hour, start it in the background, write a handoff (how far, where the files are, the next step), deliver and finish. Do not wait.
Once the context is past about 150k tokens (a hook reminds you), write a short handoff (how far, where the files are, the next step) and deliver at once; the dispatcher starts a new agent to continue.
In the delivery, give the output file paths and the acceptance results.
<!-- conest:agent long-task (installed by bothouse setup hooks; delete this line and bothouse no longer overwrites or removes this file) -->

© zuiho-kai · Apache-2.0 · zuiho-kai/bothouse

Similar subagents

All subagents for Agent setup: memory, context, orchestration →

From the same set14

The whole set →
codemap-inject.en codemap-inject.en is a Claude Code rule that injects codebase maps into subagent prompts matching map keywords. The subagent reads the map first and lists new symbols to append upon completion. CX Codex +1 ★ 262repo stars choice-ask-guard.en choice-ask-guard.en is a Claude Code rule that checks agent questions against decisions already made and leaves open choices to the user. CX Codex +1 ★ 262repo stars param-source-guard.en The param-source-guard.en rule for Claude Code requires every new numeric parameter in code to include a source comment. It tracks limits, thresholds, and windows to ensure they trace back to user input, specs, or measurements. CX Codex +1 ★ 262repo stars wiki-context.en wiki-context.en is a Claude Code rule that reads relevant wiki hints and lesson entries during a terminal session. CX Codex +1 ★ 262repo stars _head.en _head.en is a Claude Code rule that controls tool call validation through external hooks. It blocks unauthorized bypasses and lets users toggle safety checks on demand. CX Codex +1 ★ 262repo stars dispatch-review-guard.en dispatch-review-guard.en is a Claude Code rule that checks review markers before a task is dispatched to a subagent. CX Codex +1 ★ 262repo stars bash-guard.en The bash-guard.en rule for Claude Code restricts dangerous terminal commands and enforces background task timeouts. CX Codex +1 ★ 262repo stars model-switch The model-switch skill for Claude Code manages bothouse model selection and reasoning effort. It updates configuration upon direct user requests. CX Codex +1 ★ 262repo stars

Project sponsors

Companies that keep this analytics open