# jackin purge (https://jackin.tailrocks.com/commands/purge/)



## Synopsis [#synopsis]

```bash
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 [#arguments]

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

## Options [#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 [#examples]

```bash
# 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 [#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 [#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:

```bash
jackin eject agent-smith --purge
```

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

```bash
jackin purge agent-smith
```