jackin purge

Synopsis

jackin purge <SELECTOR> [OPTIONS]

Delete persisted state (Claude history, settings, GitHub CLI state, plugins) for an agent whose Docker resources are already gone. Use this to discard local recovery state after you no longer need the instance.

Arguments

Argument	Required	Description
SELECTOR	Yes	Role selector, instance ID, or container name

Options

Option	Description
--all	Delete state for every matching instance. Without --all, the command errors if more than one instance matches the target
--debug	Print every external command jackin issues and their captured output. Also enabled by JACKIN_DEBUG=1.

Examples

# Purge default instance state
jackin purge agent-smith

# Purge all instances
jackin purge agent-smith --all

# Purge a specific indexed instance
jackin purge k7p9m2xq

# Purge a namespaced agent
jackin purge chainargos/backend-engineer

What gets deleted

The agent’s persisted state:

• Claude Code session history and runtime settings
• GitHub CLI authentication and settings
• forwarded auth credentials (when auth_forward = "sync" was used)
• any plugins the role installed into per-agent state

For workspaces with isolated mounts (worktree or clone), purge also force-removes:

• every per-container isolated worktree or clone the workspace materialized
• the matching local scratch branch jackin’ created for that container

There is no unpushed-commit guard, no --delete-branches flag, and no interactive prompt — once the operator runs purge, the recovery state is gone. If you may still need an isolated branch, push it (or rename it) before purging.

If the host repo backing an isolated mount has been deleted or moved between load and purge, jackin’ tolerates the missing parent and best-effort cleans up what remains. Purge does not fail just because the host repo is gone.

The Docker image and the cached role repository are not affected. Role containers, DinD sidecars, and jackin-managed Docker networks are not deleted by plain purge; if any of those resources still exist, purge refuses and tells you to use jackin eject <selector> --purge instead. Use --rebuild on the next jackin load to force a full image rebuild.

Docker-resource guard

purge refuses to run when the role container or DinD sidecar still exists, whether it is running or stopped. This keeps local recovery state from being deleted while Docker still has an instance that may need it.

To purge an instance with Docker resources still present, use the combined form:

jackin eject agent-smith --purge

If the Docker resources are already gone, purge the remaining local state directly:

jackin purge agent-smith