Integrations

Preview docs describe unreleased preview builds. Stable docs remain at /docs/.

Nagi detects supported agents automatically. Official integrations can add native session identity for restore, lifecycle state reports, or both.

Use integrations when you want native agent session restore from Claude Code/Codex/Copilot/Devin-style hooks, direct lifecycle reports from Pi/OMP/Kimi/OpenCode/Kilo/Hermes-style hooks or plugins, or both. See Agents for the full status authority model.

Install integrations

Open settings inside Nagi and use the integrations tab to install recommended integrations for agents found on your PATH, or run commands manually:

nagi integration install pi
nagi integration install omp
nagi integration install claude
nagi integration install codex
nagi integration install copilot
nagi integration install devin
nagi integration install droid
nagi integration install kimi
nagi integration install opencode
nagi integration install kilo
nagi integration install hermes
nagi integration install qodercli
nagi integration install cursor
nagi integration install mastracode

Uninstall integrations

nagi integration uninstall pi
nagi integration uninstall omp
nagi integration uninstall claude
nagi integration uninstall codex
nagi integration uninstall copilot
nagi integration uninstall devin
nagi integration uninstall droid
nagi integration uninstall kimi
nagi integration uninstall opencode
nagi integration uninstall kilo
nagi integration uninstall hermes
nagi integration uninstall qodercli
nagi integration uninstall cursor
nagi integration uninstall mastracode

How Nagi uses integrations

Nagi uses integrations in two different ways:

Integration type	Agents	Effect
Lifecycle authority	Pi, OMP, Kimi Code CLI, OpenCode, Kilo Code CLI, Hermes Agent, MastraCode	When installed and actively reporting for the pane, hook or plugin events author idle, working, and blocked. Nagi does not also use screen manifest fallback for that same lifecycle authority.
Session identity	Claude Code, Codex, GitHub Copilot CLI, Devin CLI, Droid, Qoder CLI, Cursor Agent CLI	The integration reports native session references for restore. State still comes from Nagi’s screen manifest detection.

Custom socket integrations can also report state when they define state that is not visible in the native terminal UI.

Some integrations report native agent session references. Nagi uses official session references to resume Claude Code, Codex, Devin CLI, Droid, Kimi Code CLI, Qoder CLI, Cursor Agent CLI, GitHub Copilot CLI, Pi, OMP, Hermes Agent, OpenCode, Kilo Code CLI, and MastraCode panes after a Nagi server restart unless [session] resume_agents_on_restore = false disables it.

Native session restore requires current Nagi integrations: Pi integration version 2, OMP version 3, Claude Code version 6, Codex version 5, GitHub Copilot CLI version 2, Devin CLI version 2, Droid version 2, Kimi Code CLI version 3, Qoder CLI version 2, Cursor Agent CLI version 1, OpenCode version 5, Kilo Code CLI version 1, Hermes Agent version 2, or MastraCode version 1. Check installed versions with nagi integration status.

Pi

Install the Pi integration:

nagi integration install pi

Nagi writes the bundled extension to:

~/.pi/agent/extensions/nagi-agent-state.ts

If PI_CODING_AGENT_DIR is set, Nagi writes to $PI_CODING_AGENT_DIR/extensions/nagi-agent-state.ts instead. The extensions directory must already exist. Uninstall removes only that extension file.

OMP

Install the OMP integration:

nagi integration install omp

Nagi writes the bundled extension to:

~/.omp/agent/extensions/nagi-omp-agent-state.ts

If PI_CODING_AGENT_DIR is set, Nagi writes to $PI_CODING_AGENT_DIR/extensions/nagi-omp-agent-state.ts instead. The extensions directory must already exist. Uninstall removes only that extension file.

The OMP integration reports omp as the agent label, lifecycle state, and native session identity through Nagi’s socket API. It does not require native process detection for the omp executable, and Nagi can resume an OMP pane with omp --resume=<session> after a server restart.

Claude Code

Install the Claude Code hook:

nagi integration install claude

The hook reports Claude Code session identity to the local Nagi socket on session start. Claude Code state comes from Nagi’s screen manifest detection.

Nagi uses ~/.claude by default, or CLAUDE_CONFIG_DIR when set. The Claude config directory must already exist. Install writes hooks/nagi-agent-state.sh and updates settings.json with Nagi hook entries. Uninstall removes the matching hook entries and deletes the hook script.

Codex

Install the Codex hook:

nagi integration install codex

The Codex hook reports session identity through the same local socket API used by other integrations. Codex state comes from Nagi’s screen manifest detection.

Nagi uses ~/.codex by default, or CODEX_HOME when set. The Codex config directory must already exist. Install writes nagi-agent-state.sh, updates hooks.json, and ensures [features] hooks = true in config.toml. It also removes the deprecated top-level codex_hooks flag when present. Uninstall removes Nagi entries from hooks.json and deletes the hook script, but leaves config.toml unchanged.

GitHub Copilot CLI

Install the GitHub Copilot CLI hook:

nagi integration install copilot

The Copilot hook reports session identity through the same local socket API used by other integrations. Copilot state comes from Nagi’s screen manifest detection.

Nagi uses ~/.copilot by default, or COPILOT_HOME when set. The Copilot config directory must already exist. Install writes hooks/nagi-agent-state.sh and updates settings.json with a SessionStart hook entry. Uninstall removes Nagi entries from settings.json and deletes the hook script.

After Copilot emits a session-bearing event, Nagi can use the reported session id to resume the pane with copilot --resume=<id>.

Devin CLI

Install the Devin CLI hook:

nagi integration install devin

The hook reports native session identity from Devin session, prompt, tool-use, permission, and stop events. Devin state still comes from Nagi’s screen manifest and OSC detection because Devin hooks do not emit a reliable state transition after every permission cancellation or user interrupt.

Nagi uses ~/.config/devin by default, or $XDG_CONFIG_HOME/devin when XDG_CONFIG_HOME is set. The Devin config directory must already exist. Install writes nagi-agent-state.sh and updates config.json with Nagi hook entries. The hook refreshes the session reference while Devin runs. Uninstall removes Nagi entries from config.json and deletes the hook script.

Nagi resumes stored Devin sessions with devin --resume <id>. Native screen manifest detection remains the state authority whether or not the hook is installed.

Kimi Code CLI

Install the Kimi Code CLI hook:

nagi integration install kimi

The hook reports Kimi session identity and lifecycle state to Nagi for native restore and authoritative idle, working, and blocked status. It requires Kimi Code CLI 0.14.0 or newer.

Nagi uses ~/.kimi-code by default, or KIMI_CODE_HOME when set. The Kimi Code config directory must already exist. Install writes hooks/nagi-agent-state.sh and appends Nagi-managed [[hooks]] entries to config.toml. Uninstall removes the Nagi-managed config block and deletes the hook script.

Nagi resumes stored Kimi sessions with kimi --session <id>.

Droid

Install the Droid hook:

nagi integration install droid

The Droid hook reports session identity through the same local socket API used by other integrations. Lifecycle state still comes from Nagi’s screen manifest detection because Droid hooks do not cover every lifecycle transition.

Nagi uses ~/.factory for Droid hooks. The Factory config directory must already exist. Install writes hooks/nagi-agent-state.sh, updates settings.json with a Nagi SessionStart hook entry, and removes older Nagi Droid hook entries from hooks.json if present. Uninstall removes Nagi entries from both config files and deletes the hook script.

After Droid emits a session start event, Nagi can use the reported session id to resume the pane with droid --resume <id>.

OpenCode

Install the OpenCode plugin:

nagi integration install opencode

Nagi writes the plugin to ~/.config/opencode/plugins/nagi-agent-state.js. The OpenCode config directory must already exist. Uninstall removes only that plugin file.

The plugin reports lifecycle state and session identity while OpenCode runs inside a Nagi pane. After OpenCode emits a session-bearing event, Nagi can use the reported session id to resume the pane with opencode --session <id>. Native screen manifest detection remains available when the plugin is not installed.

Kilo Code CLI

Install the Kilo Code CLI plugin:

nagi integration install kilo

Nagi writes the plugin to ~/.config/kilo/plugin/nagi-agent-state.js. The Kilo config directory must already exist. Uninstall removes only that plugin file.

The plugin reports lifecycle state and session identity while Kilo runs inside a Nagi pane. After Kilo emits a session-bearing event, Nagi can use the reported session id to resume the pane with kilo --session <id>. Native screen manifest detection remains available when the plugin is not installed.

Hermes Agent

Install the Hermes Agent plugin:

nagi integration install hermes

Nagi writes ~/.hermes/plugins/nagi-agent-state/ and enables nagi-agent-state in ~/.hermes/config.yaml. The Hermes config directory must already exist. Restart Hermes after installing so the plugin loads. Uninstall removes the plugin directory and removes nagi-agent-state from plugins.enabled.

The plugin reports lifecycle, tool, approval state, and session id while Hermes runs inside a Nagi pane. Nagi can use the reported session id to resume the pane with hermes --resume <id>. Native screen manifest detection remains available when the plugin is not installed.

Qoder CLI

Install the Qoder CLI hook:

nagi integration install qodercli

The hook reports Qoder CLI session identity to Nagi for native restore. Lifecycle state still comes from Nagi’s screen manifest detection because Qoder hooks do not cover every lifecycle transition.

Nagi uses ~/.qoder by default, or QODER_CONFIG_DIR when set. The Qoder config directory must already exist. Install writes hooks/nagi-agent-state.sh and updates settings.json with Nagi hook entries. Uninstall removes the matching hook entries and deletes the hook script.

Nagi resumes stored Qoder CLI sessions with qodercli --resume <id>.

Native screen manifest detection remains available when the hook is not installed.

Cursor Agent CLI

Install the Cursor Agent CLI hook:

nagi integration install cursor

The hook reports session identity through Cursor’s sessionStart hook while Cursor Agent CLI runs inside a Nagi pane. Cursor state comes from Nagi’s screen manifest detection.

Nagi uses ~/.cursor by default, or CURSOR_CONFIG_DIR when set. The Cursor config directory must already exist. Install writes nagi-agent-state.sh and adds a Nagi sessionStart entry to hooks.json. Uninstall removes the matching hook entry and deletes the hook script.

After Cursor emits a session start event, Nagi can use the reported session id to resume the pane with cursor-agent --resume <id>. The cursor-agent command must be on PATH when Nagi restores the pane; Nagi does not launch the generic agent command.

MastraCode

Install the MastraCode hook:

nagi integration install mastracode

The hook reports MastraCode lifecycle state and thread identity to Nagi for authoritative idle, working, and blocked status and native restore. MastraCode has no screen manifest fallback; state comes from the hook while MastraCode runs inside a Nagi pane.

Nagi uses ~/.mastracode. Install writes hooks/nagi-agent-state.sh and adds Nagi command entries to hooks.json, creating the directory when missing. Uninstall removes the matching hook entries and deletes the hook script.

Nagi resumes stored MastraCode threads with mastracode --thread <id>.

Custom status labels

Integrations report lifecycle state as semantic state only. For example, report an agent as working without adding display fields to the lifecycle report.

nagi pane report-agent w1:p1 \
  --source custom:docs \
  --agent docs-bot \
  --state working

User hooks that run next to a Nagi-managed integration should use metadata instead of report-agent. Metadata changes presentation without taking over the integration’s idle, working, blocked, or session restore authority. --agent and --applies-to-source guard only presentation fields (--title, --display-agent, and --state-label). Token patches always apply; their reporter owns clearing or TTL refresh. --display-agent changes the visible name.

nagi pane report-metadata "$NAGI_PANE_ID" \
  --source user:claude-title \
  --agent claude \
  --title "Refactor auth middleware" \
  --display-agent "Claude: auth" \
  --token summary="refactor auth" \
  --state-label working="refactoring auth" \
  --ttl-ms 3600000

Tokens and state labels are visual-only. Waits, notifications, and workspace rollups still use the semantic state.

Debug integration state

List known agents:

nagi agent list

Read a pane when you need to verify what Nagi can see:

nagi pane read w1:p1 --source recent --lines 50

If integration state looks wrong, first confirm the agent is running inside Nagi and that the relevant hook or plugin was installed for the same user account.