# ivar session
> Session commands — start, connect, convert, stop, prune and relay, and the read-only guard they set up.
Source: https://ivar.run/docs/reference/session

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

A **session** is a view directory plus the agent running in it. The view
directory is assembled per feature: the promoted repos mounted at its root, all
on the feature's branch, with the harness config materialised for whichever
provider you opened it in.

## Start one

```sh
ivar session start billing-currency
```

Omit the feature and you get a **discovery session** instead: no feature bound,
every repo read-only on its default branch. That is the session to open when you
still need to understand a problem before committing to a change.

```sh
ivar session start
```

`--provider` picks the harness when you do not want the hall's default.
`--detached` creates the session without launching an agent, and the view
directory persists until an explicit stop.

## What the view directory looks like

<Files>
  <Folder name="billing-currency" 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="infra — read-only" />
    <Folder name="plans" />
    <File name="CLAUDE.md" />
  </Folder>
</Files>

Repos sit at the root, so the agent reads `api/openapi.json` and writes
`web/src/api/billing.ts` in one session, with no handoff between them. The
harness config directory — `.claude/` or `.opencode/` — carries the hall's
skills and the session's bootstrap instructions.

## 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. The harness hook only explains
  how to promote the repo if it turns out to belong in the feature.
</Callout>

Lifting the guard for a repo is exactly one command — the same promotion
described in [`ivar feature promote`](/docs/reference/feature#promote-the-repos-it-touches):

```sh
ivar feature promote billing-currency shared
```

## Reconnect and stop

```sh
ivar session connect billing-currency   # or a session id prefix
ivar session stop billing-currency
ivar session prune
```

`connect` re-binds to a live session and re-materialises its view directory,
repairing anything that drifted — repo symlinks, the read-only guards, the
provider's config directory. Use it after an agent restart rather than starting
a second session for the same feature.

`stop` tears the view directory down and ends the harness. `prune` removes stale
sessions that are no longer bound to any feature.

## Convert a discovery session

```sh
ivar session convert billing-currency
```

Binds a discovery session to a feature and moves its view directory into that
feature's session tree. It is one-way: a feature session cannot be turned back
into a discovery session.

## Relay to another harness

Nothing in the view directory belongs to a particular vendor — the worktrees are
git, the manifest is JSON, the skills are folders of Markdown. A session relays
to a different provider with the same branch and the same context, and nothing
is uploaded to do it.

```sh
ivar session relay billing-currency --provider opencode
```

`--provider` is required: a relay exists to switch harnesses. Both `start` and
`connect` emit the same binding keys, so whatever drives the session can read
`IVAR_SESSION_ID`, `IVAR_FEATURE` and `IVAR_SESSION_PATH` the same way either
way.