Nethys is a real-time supervision sidecar for coding agents. It observes agent activity, runs independent read-only shadow reviews through the coding CLIs you already use, and feeds high-confidence findings back at safe points in the host agent loop.

It is deliberately not tied to one coding agent. The daemon, evaluation engine, audit store, and Web UI are shared; thin adapters translate OpenCode, Claude Code, and Codex lifecycle events into a small versioned protocol.

Status: early public preview. OpenCode and Claude Code expose the richest control surfaces. Codex is supported as a shadow runner and has a conservative host adapter while its public hook contract evolves.

• Watches prompts, tools, file changes, diagnostics, and session events.
• Filters events into configurable correctness, security, or project-specific reviewers.
• Runs declared linters and local validation commands before model review.
• Invokes opencode, claude, or codex non-interactively in read-only mode, reusing their existing authentication, models, skills, MCP servers, and repository instructions.
• Keeps ordinary findings silent until the next safe context boundary.
• Lets explicitly blocking reviewers hold a tool checkpoint for at most eight seconds.
• Blocks only critical, actionable, current-revision findings; failures and timeouts fail open.
• Shows the complete live timeline, shadow runs, evidence, output, host capabilities, and resolved configuration in a local Web UI.

Requires Node.js 22.5 or newer and at least one supported coding-agent CLI.

npm install -g nethys
nethys doctor
nethys install
nethys open

nethys install previews every adapter change before applying it and creates a backup beside any modified host configuration. The daemon auto-starts when an adapter first sends an event. Its Web UI binds only to 127.0.0.1.

For development:

npm install
npm run build
npm test
node dist/cli.js start --foreground

Nethys merges user configuration with .nethys/config.jsonc in the active repository. Project settings win. User configuration lives in %APPDATA%/nethys/config.jsonc on Windows and $XDG_CONFIG_HOME/nethys/config.jsonc on Unix-like systems.

{
  "version": 1,
  "daemon": {
    "gateTimeoutMs": 8000,
    "workspaceConcurrency": 2,
    "globalConcurrency": 4,
    "retentionDays": 30
  },
  "scripts": [
    {
      "id": "typecheck",
      "command": "npm",
      "args": ["run", "typecheck", "--", "--pretty", "false"],
      "cwd": "workspace",
      "timeoutMs": 30000,
      "maxOutputBytes": 262144
    }
  ],
  "agents": [
    {
      "id": "correctness",
      "runner": "host",
      "prompt": "Find concrete correctness regressions in the supplied change.",
      "blocking": false,
      "confidenceThreshold": 0.9,
      "severityThreshold": "high",
      "scripts": ["typecheck"],
      "triggers": [
        {
          "events": ["tool.after", "file.edited"],
          "tools": ["edit", "write", "apply_patch"],
          "paths": ["src/**/*.ts"],
          "keywords": []
        }
      ]
    }
  ]
}

runner: "host" uses the active coding agent's CLI. It can be overridden with opencode, claude, or codex. Optional model, agent, and profile values are passed only to runners that support them.

Scripts are executable plus argument arrays, never interpolated shell strings. Nethys adds NETHYS_SHADOW_RUN=1 and SENTINEL_SHADOW_RUN=1 to every shadow subprocess; all adapters immediately bypass themselves when either value is present, preventing recursive shadow runs.

1. A host adapter emits an event without waiting.
2. Matching shadow agents and scripts run concurrently while the primary agent continues.
3. Every host tool call can be used as a checkpoint.
4. Advisory results are delivered through the host's next supported context boundary.
5. Only reviewers with blocking: true may delay checkpoints, and only until the configured deadline.
6. A critical finding denies the tool with concrete evidence. The primary agent receives that reason and can correct itself.
7. Stale, duplicate, low-confidence, timed-out, or failed reviews never block the primary agent.

Adapters communicate with the loopback daemon using:

• POST /v1/events — asynchronous lifecycle events.
• POST /v1/checkpoints — bounded synchronous decisions.
• POST /v1/injections/consume — consume next-step context.
• POST /v1/manual — run a selected shadow agent from the dashboard.
• GET /v1/stream — live UI updates over SSE.
• GET /v1/events, /runs, /findings, /adapters, and /config — dashboard queries.

Checkpoint decisions are allow, allow_with_context, block, or timeout. Adapters advertise capabilities rather than pretending every host supports the same controls.

• The API and UI bind to loopback and reject non-loopback host headers.
• Shadow CLIs are invoked in read-only/plan modes.
• Local validation uses direct process spawning with fixed argument arrays, timeouts, cancellation, sanitized additions, and bounded output.
• Adapter failures and review timeouts fail open.
• Nethys does not collect or store provider credentials.
• Findings require structured evidence, confidence, severity, and a revision-aware fingerprint.

Nethys is a guardrail and review aid, not a security boundary. The host coding agent and configured commands still run with the authority granted by the user.

nethys start [--foreground]
nethys stop
nethys status
nethys open
nethys install [--hosts opencode,claude] [--yes]
nethys doctor
nethys hook <claude|codex>

OpenCode plugin ─┐
Claude hooks ────┼── events / checkpoints ── Nethys daemon
Codex hooks ─────┘                              ├── trigger engine
                                                ├── script runner
                                                ├── CLI shadow runners
                                                ├── SQLite audit store
                                                └── local Web UI

MIT