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
.claude/agents/agent_archive.mdWhat 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.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/agent_archive.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/agent_archive.mdCursor also reads .claude/agents/
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