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: 
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. 
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. 
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)

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. 
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. 
niia serve --env ANTHROPIC_API_KEY=sk-... --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. 
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: 
{
  "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.