Skip to main content

​
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:
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.
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.
macOS: Apple Seatbelt via sandbox-exec
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)

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.
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.
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.
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:
niia run connector.json reads these fields and builds the plugin chain automatically.