# OMP
> What an OMP session materialises, pre-tool hooks, autocomplete extensions, and profile command bridging.
Source: https://ivar.run/docs/providers/omp

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

Setup is harness-agnostic — see the [quickstart](/docs/quickstart) for creating
a hall and opening your first session. This page covers what is specific to
OMP once you're there.

## What lands in `.omp/`

An OMP session materialises a `.omp/` directory at the view directory's root,
alongside the promoted repos:

<Files>
  <Folder name=".omp" defaultOpen>
    <Folder name="commands" defaultOpen>
      <File name="ivar-discovery.md" />
      <File name="ivar-plan.md" />
    </Folder>
    <Folder name="skills" />
    <Folder name="hooks" defaultOpen>
      <Folder name="pre" defaultOpen>
        <File name="ivar.js" />
      </Folder>
    </Folder>
    <Folder name="extensions" defaultOpen>
      <File name="ivar.js" />
    </Folder>
  </Folder>
  <File name="AGENTS.md" />
  <File name="mcp.json" />
</Files>

`.omp/commands/` holds `ivar-*.md` command templates. `.omp/skills/` carries
every skill from both roots — the hall's committed skills and your personal
ones — materialised under its bare id; the directory itself is gitignored
because each child is a derived symlink back into `.ivar/`. `AGENTS.md` is the
provider-native instructions file OMP reads at startup. `mcp.json` configures
the hall's MCP servers under the `mcpServers` key.

## Pre-tool hook

The read-only guard is enforced by `.omp/hooks/pre/ivar.js`.

OMP discovers `.omp/hooks/pre/*.js` and loads each in-process as an ES module
whose default export is a factory receiving the hook API. The handler registers
on `tool_call` and blocks by returning `{ block: true, reason }`, where `reason`
becomes the tool error the model sees.

The hook does not evaluate policy itself: it shells out to `ivar guard --provider omp`
and translates a non-zero exit into the structured verdict, reading the reason
from stdout. See [guards](/docs/guide/guards) for the policy rules.

## Autocomplete extension

OMP provides native command-line completion via `.omp/extensions/ivar.js`.

OMP discovers `.omp/extensions/*.js` and loads each in-process as an ES module
whose default export is a factory receiving the extension API. It registers an
autocomplete provider through `ctx.ui.addAutocompleteProvider` on `session_start`.

When the user types the argument of a shipped `/ivar-*` command that takes an
existing feature, the extension offers candidates from `ivar feature list --json`.

<AutocompletePreview />

In a session already bound to a feature (`IVAR_FEATURE` set), or on any line that
does not match those commands, it delegates entirely to the live `current`
provider — every method is forwarded so normal file and command completion is
uninterrupted.

## Session projections

Every provider projects its command catalog into the session's config directory.
OMP additionally projects `.omp/hooks/pre` → `hooks/pre` and `.omp/extensions` → `extensions`
because OMP discovers those directories inside the session.

## Profile command bridge

OMP discovers slash commands from the active profile's commands directory rather
than the hall root:

- Default profile: `~/.omp/agent/commands` (or `$PI_CONFIG_DIR/agent/commands`)
- Named profile: `~/.omp/profiles/<name>/agent/commands` (or `$PI_CONFIG_DIR/profiles/<name>/agent/commands`)

The active profile is resolved from `OMP_PROFILE`, falling back to `PI_PROFILE`.
Empty values, whitespace, or `default` select the default profile.

`ivar sync` bridges this directory: it creates or updates symlinks pointing back
to the hall's `.omp/commands/ivar-*.md`, and removes stale `ivar-*.md` symlinks
pointing into the hall. A real file (not a symlink) at a target name is never
overwritten — `ivar` emits a warning instead. User files and unmanaged commands
remain untouched.

## MCP servers

`ivar` writes MCP servers under the `mcpServers` key of `mcp.json`. Canonical
`http` transports remain `http`; canonical `local` transports map to `stdio`.

When a server carries OAuth metadata with a `token_url`, `ivar` writes an `auth`
block with `type: "oauth"`, `clientId`, `tokenUrl`, optional `resource`, and
`clientSecret` (formatted as `${VAR}` when a secret environment variable is
configured). Without a `token_url`, no `auth` block is written. Deep MCP setup
lives at [MCP provider reference](/docs/guide/mcp/providers/omp).

## Add it to an existing hall

The [quickstart](/docs/quickstart) covers `ivar init`. If the hall already
exists with a different provider, add OMP alongside it:

```sh
ivar provider add omp
```