> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monolex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Session Plugins

> Daemon-external plugins that transform PTY session configuration — worktree, sandbox, scratchpad, and more.

# Session Plugins

Plugins extend PTY sessions without modifying the daemon binary.
They work by transforming `cwd` and `shell` before the daemon sees them.

## Plugin Trait

Every plugin implements the same interface:

```
SessionPlugin:
  name()            → plugin identifier
  before_session()  → transform session config (cwd, shell, env)
  after_session()   → cleanup when session ends
```

Plugins chain. Each receives the output of the previous plugin.
Order matters.

## Available Plugins

### worktree — Git Isolation

Creates an isolated git worktree so the session operates on a separate branch.
Other sessions/workers can run in parallel without file conflicts.

```bash theme={null}
niia serve --worktree feat-auth
```

**Before session**:

1. `git worktree add -B niia-wt-feat-auth /tmp/niia-worktree-feat-auth HEAD`
2. Symlink large directories (node\_modules, target, .venv) to save disk
3. Set session `cwd` to worktree path

**After session**:

* No uncommitted changes → auto-cleanup (worktree remove + branch delete)
* Uncommitted changes → preserve worktree, print path

**What daemon sees**: `CreateSession { cwd: "/tmp/niia-worktree-feat-auth" }`
Daemon doesn't know it's a worktree.

### sandbox — OS-Level Isolation

Wraps the shell process with platform-specific sandbox restrictions.

```bash theme={null}
niia serve --sandbox
```

**macOS**: Apple Seatbelt via `sandbox-exec`

```
sandbox-exec -p '(version 1)
  (allow default)
  (deny network*)
  (deny file-write*)
  (allow file-write* (subpath "/tmp/niia-worktree-feat-auth"))
  (allow file-write* (subpath "/tmp"))
' /bin/zsh
```

**Default policy**:

* Network: **denied**
* File write: **denied** except cwd + /tmp
* File read: allowed

**What daemon sees**: `CreateSession { shell: "sandbox-exec -p '...' /bin/zsh" }`
Daemon doesn't know it's sandboxed.

### worktree + sandbox (composition)

```bash theme={null}
niia serve --worktree feat-x --sandbox
```

Execution order:

1. **worktree** runs first → changes `cwd` to `/tmp/niia-worktree-feat-x`
2. **sandbox** runs second → reads `cwd`, allows writes only there

This is why order matters: sandbox needs to know the worktree path to allow writes to it.

### scratchpad — Shared Knowledge Directory

Creates a shared directory accessible by all workers in a pipeline.

```bash theme={null}
niia serve --worktree feat-x --scratchpad
```

Creates `{worktree}/scratchpad/` that all sessions can read and write.
Workers share findings, decisions, and intermediate results here.

### env — Environment Injection

Injects environment variables into the session.

```bash theme={null}
niia serve --env API_KEY=your-key --env HTTPS_PROXY=http://...
```

Useful for:

* API key isolation per session
* Proxy configuration per worker
* Model selection via environment

### timeout — Session Lifetime

Limits how long a session can run.

```bash theme={null}
niia serve --timeout 3600
```

After timeout, session is gracefully terminated.
Worktree changes are preserved.

## Plugin Development

Plugins implement the `SessionPlugin` interface.

A plugin only needs to:

1. Optionally modify `cwd` (change working directory)
2. Optionally modify `shell` (wrap shell command)
3. Optionally modify `env` (inject variables)
4. Optionally run cleanup after session

The daemon protocol already supports `cwd` and `shell` fields.
No daemon modification is needed to add new plugins.

## connector.json Integration

Plugins map directly to connector.json `session` fields:

```json theme={null}
{
  "session": {
    "worktree": "feat-x",
    "sandbox": true,
    "scratchpad": true,
    "env": { "API_KEY": "..." },
    "timeout_ms": 3600000
  }
}
```

`niia run connector.json` reads these fields and builds the plugin chain automatically.