heretic-cli

Sessions

Run several isolated agent instances from one project — session directories, container naming, label filtering, what is shared and what is not

A session is a named namespace for one run of a profile inside one project. It is the mechanism that lets the same agent run several times in the same repository without the instances trampling each other's state.

What a session name affects

ThingValue
Session directory.heretic/temp/<session>/ — becomes the agent's ~/.claude (or ~/.copilot)
Container nameheretic-<agent>-<session>-<hash8>
Container labelheretic.session=<name> — what ps, stop and attach filter on
Compose project nameheretic-<agent>-<session> (compose runner)
Sidecar network and buildersheretic-net-<agent>-<session>-<hash8>, heretic-builder-<runtime>-<session>-<hash8>

hash8 is the first 8 hex characters of sha256(<absolute project dir>), so the same profile and session in two different checkouts are still two different containers.

Without -s/--session the name is default. Names are sanitised: any character outside [a-zA-Z0-9_-] becomes -.

Usage

# two instances in parallel, separate state
heretic-cli run claude -s feature-a
heretic-cli run claude -s feature-b

heretic-cli ps                 # SESSION column shows which is which
heretic-cli ps -s feature-a    # filter
heretic-cli attach claude -s feature-a
heretic-cli stop -s feature-a -f

Session directory

<project>/.heretic/temp/
├── default/
│   ├── .mcp.json          generated MCP configuration
│   ├── settings.json      merged Claude settings → ~/.claude/settings.json
│   ├── .claude.json       onboarding seed
│   ├── compose.yaml       generated compose file (compose runner)
│   └── entrypoint.sh      embedded entrypoint (root mode)
└── feature-a/
    └── …

The directory is created with mode 0777 so any container uid can write to it, and the generated files are rewritten on every run. Everything the agent itself writes — Claude Code history, caches, credentials — also lands here, which is why session state survives heretic-cli stop.

Reset an agent by deleting its session directory:

rm -rf .heretic/temp/feature-a

What is isolated and what is not

Isolated per sessionShared across sessions
the agent's home directory (~/.claude / ~/.copilot)the workspace — every session mounts the same project directory
generated MCP config and merged settingsthe profile and its secrets
container, compose project, sidecar network and buildersnamed cache volumes (deliberately, to keep builder caches warm)

Sessions do not isolate your files

Two sessions edit the same working tree. For genuinely parallel work use separate checkouts (or git worktrees) — then the project-directory hash differs and the containers are independent by construction.

Same session twice replaces the first container

Starting a run when a container with the same name already exists stops and removes the old one. Use a different -s value to run side by side.

Next Steps