# Quickstart
> Install ivar, create a hall, and open your first discovery session in Claude Code or OpenCode.
Source: https://ivar.run/docs/quickstart

import { Callout } from 'fumadocs-ui/components/callout';
import { Card, Cards } from 'fumadocs-ui/components/card';
import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

Install ivar, create a hall, and open your first discovery session on a repo
you own. Fifteen minutes, one repo, nothing to undo afterwards.

## Before you start

- **git**, and read access to at least one repo you can clone.
- **A harness** — [Claude Code](https://claude.com/claude-code) or
  [OpenCode](https://opencode.ai). Pick the one you already work in; the steps
  below are the same either way.
- **Remote auth.** `ivar repo add` clones through your existing git remotes. For
  GitHub it reads a token from the GitHub CLI, so run `gh auth login` first, or
  export `$GITHUB_TOKEN` / `$GH_TOKEN`.

<Callout title="Nothing leaves your machine">
  `ivar` is a single binary that never talks to a server. It clones from the
  remotes you already use and writes only inside the hall directory.
</Callout>

## Install

<Tabs items={['Install script', 'cargo', 'Release binary']}>
  <Tab value="Install script">
    Fetches the release binary for your platform and verifies its checksum.

    ```sh
    curl -fsSL ivar.run/install | sh
    ```
  </Tab>
  <Tab value="cargo">
    Builds from source; needs a Rust toolchain.

    ```sh
    cargo install ivar
    ```
  </Tab>
  <Tab value="Release binary">
    Every [release](https://github.com/mnzsss/ivar/releases/latest) carries one
    binary per platform — `ivar-linux-x86_64`, `ivar-linux-aarch64`,
    `ivar-darwin-x86_64`, `ivar-darwin-aarch64` — each with a `.sha256` beside
    it. These are the same artifacts the install script fetches.

    ```sh
    chmod +x ivar-linux-x86_64 && mv ivar-linux-x86_64 ~/.local/bin/ivar
    ```
  </Tab>
</Tabs>

## Verify

```sh
ivar --version
```

If the shell cannot find `ivar`, the install directory is not on your `PATH`.
Start a new shell, or add it.

## Set up the hall

Pick your harness in the second step below; the rest is identical either way.

<Steps>
<Step>

### Create the hall directory

A hall is the directory that owns your repos and sessions. Make one and turn
it into a git repo — the hall itself is version-controlled, because that is
what lets a teammate reproduce it.

```sh
mkdir my-hall && cd my-hall
git init
```

</Step>
<Step>

### Create the hall

Writes the hall record: `ivar.json`, `.ivar/`, and the hall's gitignore lines.
`ivar.json` is the part you commit; `.ivar/` is local working state and is
ignored for you.

<Tabs items={['Claude Code', 'OpenCode']}>
  <Tab value="Claude Code">
    ```sh
    ivar init
    ```
  </Tab>
  <Tab value="OpenCode">
    ```sh
    ivar init --provider opencode
    ```
  </Tab>
</Tabs>

The hall takes its name from the directory — `--name` overrides that. The
provider recorded here becomes the hall's default; add more later with
`ivar provider add`.

</Step>
<Step>

### Add a repo

Declares the repo in `ivar.json`, clones it bare, and materialises its
default-branch worktree. `<name>` is one path segment, unique in the hall;
`<url>` is the git remote.

```sh
ivar repo add <name> <url>
```

The default branch is `main` unless you pass `--default-branch`. Repeat the
command for every repo the hall should own — a hall with one repo is valid, it
just has nothing to span yet.

</Step>
<Step>

### Check the hall

Before opening an agent on it, confirm the hall is what you expect. `status`
reports health and each repo's state; `doctor` diagnoses problems and suggests
fixes when it is not.

```sh
ivar status
ivar repo list
```

</Step>
<Step>

### Open a discovery session

<Tabs items={['Claude Code', 'OpenCode']}>
  <Tab value="Claude Code">
    In Claude Code, run `/ivar-discovery`. It starts a guided discovery
    session, with no feature attached yet — every repo mounted read-only on
    its default branch.

    ```sh
    /ivar-discovery
    ```

    The session gets its own view directory with the repos at the root and
    `.claude/` materialised for Claude Code, so the agent starts with the
    hall's skills and context already in place.
  </Tab>
  <Tab value="OpenCode">
    In OpenCode, run `/ivar-discovery`. It starts a guided discovery session,
    with no feature attached yet — every repo mounted read-only on its
    default branch.

    ```sh
    /ivar-discovery
    ```

    The session gets its own view directory with the repos at the root and
    `.opencode/` materialised for OpenCode, so the agent starts with the
    hall's skills and context already in place.
  </Tab>
</Tabs>

</Step>
</Steps>

<Callout title="If a clone fails">
  `ivar repo add` clones from your remotes. For GitHub, ivar reads its token
  from the GitHub CLI. Run `gh auth login` first, or export `$GITHUB_TOKEN` /
  `$GH_TOKEN`. Every command also takes `--json`, which prints exactly the
  value the command computed — useful when the human-readable error is not
  enough.
</Callout>

## What happens next

The agent asks what you would like to understand or decide, then explores the
codebase read-only. Repos are never written to during discovery. Once it has a
problem, a desired outcome, scope boundaries, affected repos, and risks, it
may offer to convert the session into a Feature Session. Conversion is
offered, never automatic, and it is irreversible.

After conversion the feature's repos become writable, and `/ivar-plan` turns
the discovery brief into a plan. From there the feature has its own loop:
`ivar feature promote` brings another repo onto the branch when the work turns
out to reach further than you thought, and `ivar feature deliver` pushes each
promoted worktree and opens its pull request. Both are beyond this quickstart.

Commands verified against `ivar 0.2.1`.

## What you will end up with

A directory that is itself a git repo, holding a committed `ivar.json` and an
`.ivar/` working area. Commit the hall and a teammate gets the same repos on the
same branches with `git clone` and `ivar sync` — no second setup document to
keep current.

<Callout type="info" title="One hall, or several?">
  A hall is cheap: it is a directory with a manifest. Teams usually keep one per
  product area, holding the repos that change together — not one per developer,
  and not one for the whole company.
</Callout>

## Further reading

Per-harness reference — what each session materialises and how `/ivar-discovery`
runs there.

<Cards>
  <Card
    title="Claude Code"
    description="Config directory, init flag, and provider reference for Claude Code."
    href="/docs/providers/claude-code"
  />
  <Card
    title="OpenCode"
    description="Config directory, init flag, and provider reference for OpenCode."
    href="/docs/providers/opencode"
  />
</Cards>

## Then what

<Cards>
  <Card
    title="Sessions"
    description="Open, reattach to and close the directory your agent works in."
    href="/docs/guide/sessions"
  />
  <Card
    title="Discovery"
    description="Understand the problem before committing to a change."
    href="/docs/guide/discovery"
  />
</Cards>