Skip to main content
subagent CX Codex

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

Subagent for Claude Code moves a coding agent session from the active list to the archive. It triggers when cleaning up or archiving agent sessions.

MIT ★ 395 updated 2026-11-16

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

What agent_archive does

The subagent transfers sessions from agents_list to the archived section without deleting any transcripts or project data. Restoring an archived session is handled separately via agent_unarchive. When the target tool has built-in archive support, such as Codex, the subagent issues an archive request to that native tool and reports the outcome as done, pending, or unsupported.

Operation requires machine along with session_id. The close parameter defaults to false. When set to true, it shuts down the agent process and closes its terminal tab on the host machine after phone confirmation. Busy agents are rejected: running background jobs, active code execution, queued prompts, running /loop routines, or active network listeners block the operation.

The force: true parameter cancels and closes an agent stuck on terminal confirmation prompts. This subagent does not handle standard Persona chat sessions, which use conversation_archive instead.

What it helps with

  • archive inactive coding agent sessions from agents_list
  • cancel and terminate agents stuck waiting for terminal confirmation
  • shut down remote agent processes and terminal windows with mobile confirmation
  • trigger native session archiving inside Codex

Example prompts for the agent

  • Archive session a1b2c3d4 on machine dev-box
  • Archive session 98765432 and close its terminal on my desktop
  • Force close and archive the blocked agent e5f6a7b8 on machine mac-mini

How to install agent_archive

Manually: put the files in place

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

How to install agent_archive in Claude Code?

Add the configuration file at .claude/agents/agent_archive.md.

What does agent_archive do?

It moves an agent session from the active list into the archive without deleting history. With the close option, it also terminates the agent process and terminal window.

What happens if the agent is currently busy?

The archive request will be rejected. The subagent refuses to touch agents that are executing tasks, waiting on background jobs, running loops, or serving ports.

Source text

agent_archive.md · MIT
Archive a coding agent's session (from agents_list) when the user asks to archive or tidy up agents: it leaves the Agents list for Archived in the app, nothing is deleted, and agent_unarchive brings it back (never remove a session any other way). Persona also asks the agent's own tool to archive it where that tool has an archive (Codex); the result says whether it did (native: done / pending / unsupported). Without close the agent itself is not closed: one open on its computer stays open. With close, its agent and its terminal tab are also closed on its computer (its transcript stays; then it is stopped until resumed): only when the user asks to close it too, and the user confirms on the phone first (declined: nothing changes). A busy agent is refused and nothing changes: working, waiting for an answer or background work, and for close also a /loop, queued messages or a server it runs. When the close does not happen the session stays archived and still open on the computer, and the result says why: tell the user exactly that, not that it was closed. With `force: true`, explicitly cancel and close an Agent stuck waiting for a terminal confirmation, then archive it, as `paseo archive --force` does. Use force only when the user asks to stop or archive that blocked Agent. Pending permissions and plans are rejected or cancelled, never allowed. Working Agents, background work, running subagents/workflows, queued messages, loops and serving ports are still refused. A failed close leaves it visible. Force implies close and does not ask for a second permission card. Not for Persona conversations (conversation_archive).

```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"
    },
    "force": {
      "type": "boolean",
      "description": "cancel and close a confirmation-blocked Agent before archiving; only when the user asks; never approve its pending request"
    },
    "close": {
      "type": "boolean",
      "description": "also close its agent on the computer (asks the user on the phone first); default false: archive only"
    }
  }
}
```

© nwverse · MIT · nwverse/persona

Similar subagents

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

From the same set61

The whole set →
agent_supervise The agent_supervise Claude Code subagent takes over an agent that was started without a task and tracks its work as a task in the current conversation. It routes progress messages to a supervisor and closes the task with task_review. CX Codex ★ 395repo stars task_decided The task_decided Claude Code subagent records an owner's answer to a pending task decision. It captures the choice when the owner gives it in the conversation. CX Codex ★ 395repo stars agents_list agents_list — a subagent for Claude Code and Codex monitoring running herdr sessions across user machines. Displays active jobs, pending approvals, and subscription limits. CX Codex ★ 395repo stars task_scope task_scope — a subagent for Claude Code revises a supervised task after it starts. It updates the completion criteria and time estimate, with the change shown to the owner in their next digest. CX Codex ★ 395repo stars agent_switch This subagent for Claude Code moves a running agent to another launcher on the same computer. It switches sessions only when the user asks. CX Codex ★ 395repo stars worker_supervise worker_supervise — a subagent for Claude Code supervises background workers launched with task_plan. It checks submitted evidence against completion criteria and updates worker status via task_review. CX Codex ★ 395repo stars agents_switch agents_switch — a subagent for Claude Code moves multiple running or stopped agents to a different launcher in a single invocation. Executes when requested to manage subscription usage quotas. CX Codex ★ 395repo stars standing_actions Claude Code subagent standing_actions classifies the operations authorized by an agent confirmation card. CX Codex ★ 395repo stars

Project sponsors

Companies that keep this analytics open