---
title: Sessions
description: "Run several isolated agent instances from one project — session directories, container naming, label filtering, what is shared and what is not"
canonical: https://giglabo.com/heretic/docs/heretic-cli/configuration/sessions
locale: en
---

# Sessions

> Markdown twin of https://giglabo.com/heretic/docs/heretic-cli/configuration/sessions
> Fetch this instead of the HTML page: same content, a fraction of the bytes.
> Site structure and the full page list for agents: https://giglabo.com/llms.txt

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

| Thing | Value |
|-------|-------|
| Session directory | `.heretic/temp/<session>/` — becomes the agent's `~/.claude` (or `~/.copilot`) |
| Container name | `heretic-<agent>-<session>-<hash8>` |
| Container label | `heretic.session=<name>` — what `ps`, `stop` and `attach` filter on |
| Compose project name | `heretic-<agent>-<session>` (compose runner) |
| Sidecar network and builders | `heretic-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

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

```bash
rm -rf .heretic/temp/feature-a
```

## What is isolated and what is not

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

> **Warning: 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.

> **Note: 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

- [run](https://giglabo.com/heretic/docs/heretic-cli/commands/run) — the `-s` flag in context
- [ps, stop, attach](https://giglabo.com/heretic/docs/heretic-cli/commands/ps-stop-attach) — session filtering
- [Sidecars](https://giglabo.com/heretic/docs/heretic-cli/configuration/sidecars) — per-session builders and networks

## Related

- HTML version of this page: https://giglabo.com/heretic/docs/heretic-cli/configuration/sessions
- Site map for agents: https://giglabo.com/llms.txt