# Sessions
> The commands that open, reattach to and close the directory your agent works in — and the guard that decides what it can write.
Source: https://ivar.run/docs/guide/sessions

import { Callout } from 'fumadocs-ui/components/callout';
import { File, Files, Folder } from 'fumadocs-ui/components/files';

Everything you do with `ivar` happens inside a session. You start one from your
harness with a slash command; `ivar` assembles the view directory and the agent
runs in it.

## Start a session

```text
/ivar-session-start [feature-name]
```

Name a feature and you get a **feature session**: its promoted repos mounted at
the view directory's root, all on the feature's branch, writable.

Leave the name off and you get a **discovery session**: no feature bound, every
repo read-only on its default branch. That is the one to open when you are still
working out what the change even is — see [Discovery](/docs/guide/discovery).

## What the agent sees

<Files>
  <Folder name="$IVAR_SESSION_PATH" defaultOpen>
    <Folder name="api" defaultOpen>
      <File name="openapi.json" />
    </Folder>
    <Folder name="web" defaultOpen>
      <File name="src/api/billing.ts" />
    </Folder>
    <Folder name="shared — read-only" />
    <Folder name="plans" />
    <File name="CLAUDE.md" />
  </Folder>
</Files>

Repos sit at the root — not under a `repos/` level — so a path is
`api/openapi.json`, and a write-contract glob is `<repo>/src/**`. The harness
config directory carries the hall's skills and the session's bootstrap
instructions, and `plans/<feature>/` is the feature's planning artifacts
projected in from the hall.

The session exports three keys that everything else keys off:

```sh
IVAR_SESSION_ID=<uuid>
IVAR_FEATURE=<feature-or-empty>
IVAR_SESSION_PATH=<absolute-view-dir>
```

## The guard

Repos you have not promoted have their write bits cleared — `mode & ~0o222`,
applied recursively. The kernel refuses the write.

<Callout type="warn" title="chmod, not a prompt">
  Asking an agent not to touch `shared` works until it does not. A cleared write
  bit does not depend on the model's cooperation. When the agent hits one, the
  harness hook explains how to promote the repo — it does not argue.
</Callout>

Lifting the guard is one command, covered in [Features](/docs/guide/features).

## Reattach after a restart

```text
/ivar-session-connect [session-id-prefix]
```

Reconnect re-materialises the view directory and repairs whatever drifted: repo
symlinks, the read-only guards, the provider's config directory, the projected
plan link.

<Callout title="Reconnect, do not restart">
  If a session already exists for your feature, connect to it. Starting a second
  one for the same feature leaves you with two view directories over the same
  worktrees.
</Callout>

Both `start` and `connect` emit the same three binding keys, so it does not
matter which one got you there.

## Close it

```text
/ivar-session-stop
```

Tears the view directory down, ends the harness and cleans up the guards.