Skip to main content
subagent CX Codex

agent_interrupt — Claude Code subagent: what it does, how to install

This Claude Code subagent stops another agent and can send it a new instruction immediately. Use it to interrupt a stalled loop, repeated failure, or work heading in the wrong direction.

MIT ★ 395 updated 2026-11-16

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

What agent_interrupt does

agent_interrupt cuts off the selected agent’s current turn and can pass it a replacement instruction right away. Select the machine by the name or ID shown in agents_list, then provide the agent’s session ID or its first eight characters. Leave then empty to stop without sending a message.

The agent and its session remain, but completed work is untouched. Files already changed and commands already run need a separate instruction to undo. This subagent does not target assistant conversations or read-only agents. A then value containing only /exit or /quit is rejected for an agent on a task supervised by another conversation; nothing is stopped or sent.

What it helps with

  • stop an agent repeating a failed step
  • interrupt an agent stuck polling or sleeping
  • redirect an agent without ending its session
  • send a replacement instruction as the agent stops

Example prompts for the agent

  • Stop the agent on devbox with session a1b2c3d4 and ask it to revert its latest changes to src/app.ts.
  • Interrupt session a1b2c3d4 on devbox; it is stuck checking the same thing.
  • Stop agent a1b2c3d4 on devbox without sending another instruction.

How to install agent_interrupt

Manually: put the files in place

.claude/agents/agent_interrupt.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 agent_interrupt

How do I install agent_interrupt in Claude Code?

Place the subagent file at .claude/agents/agent_interrupt.md.

What does agent_interrupt do?

It interrupts a selected agent’s current turn and can send it another instruction immediately. The agent and its session remain active.

What details are needed to stop an agent?

Provide the machine name or ID from agents_list, plus the session ID or its first eight characters. Work already done is not rolled back.

Source text

agent_interrupt.md · MIT
Stop what an agent (from agents_list) is doing right now, and optionally redirect it: its current turn is cut off (Esc in its terminal, or its runtime's cancel), the agent and its session stay, and `then` is sent to it at once as the user would type it. Use it when waiting is worse than stopping: it works in the wrong direction, waits in a loop (sleep, polling), repeats a failing step, collides with another agent, or the user said stop. To add a word to an agent that works fine, use agent_send instead (queued behind its turn). What it did already is not undone (files it changed, commands it ran): tell it in `then` what to put back. Not for assistant conversations, and not for agents that can only be read. A `then` of only /exit or /quit to an agent on a task another conversation supervises is refused, as agent_send refuses it: nothing is stopped or sent.

```json
{
  "type": "object",
  "required": ["machine", "session_id"],
  "properties": {
    "machine": {
      "type": "string",
      "description": "the machine's id or name, as agents_list shows it"
    },
    "session_id": {
      "type": "string",
      "description": "the agent's session id, or its first 8 characters"
    },
    "then": {
      "type": "string",
      "description": "the new instruction, sent right after it stopped; empty: just stop it"
    }
  }
}
```

© nwverse · MIT · nwverse/persona

Similar subagents

Subagents catalog →

From the same set61

The whole set →
task_spawn The task_spawn Claude Code subagent starts a separate agent for part of an active assignment. The new agent joins the same to-do list and reports to the same supervisor. CX Codex ★ 395repo stars task_leader The task_leader subagent for Claude Code splits work among child agents and checks their results against defined completion criteria. It handles review decisions for each delegated task. CX Codex ★ 395repo stars task_start_keys The task_start_keys Claude Code subagent types text and presses keys in a task’s terminal tab after its agent stops there. It can answer a shell prompt or move past the screen’s current point. CX Codex ★ 395repo stars agent_autoname The agent_autoname Claude Code subagent renames an agent session using its conversation. It runs only after an explicit Auto Rename request. CX Codex ★ 395repo stars task_handoff The task_handoff Claude Code subagent sends part of an assigned task to a separate session through Persona. The handoff stays attached to the same to-do and supervisor. CX Codex ★ 395repo stars leader_progress The leader_progress Claude Code subagent adds direction updates to a work log. It reports completed goals and scheduled check-ins, rather than every intermediate step. CX Codex ★ 395repo stars interaction_answer The interaction_answer Claude Code subagent answers another agent’s question on the user’s behalf when the user has chosen an answer or delegated the choice. It picks from the offered options and leaves personal decisions to the user. CX Codex ★ 395repo stars agent_autoname_receipt The agent_autoname_receipt Claude Code subagent reads existing name-confirmation cards and one coding agent’s current naming snapshot. It helps inspect the available evidence about a rename. CX Codex ★ 395repo stars

Project sponsors

Companies that keep this analytics open