Nofax

Nofax

Human-in-the-loop approvals and notifications for AI coding agents, without running a Nofax SaaS.

Nofax is a small open-source bridge between an agent and a human. Local mode can pause an AI workflow, notify your phone, and return an explicit decision. An optional self-deployed Cloudflare Worker exposes a deliberately narrower remote MCP surface for one-way notifications and safe request inspection.

No Nofax account. No paid model API. No inbound port on your machine. MIT licensed.

Current status: local Nofax is on the stable 0.2.x line. The optional Cloudflare Worker is the upcoming 0.3.0 remote surface and is developed alongside the local package.

Why Nofax

Agent workflows increasingly need a clean answer to one question: when automation reaches a human decision boundary, how does it ask without pretending that silence means approval?

Nofax keeps that boundary explicit:

• pending is never approval;
• timeout and transport failure fail closed;
• the first accepted terminal response wins;
• agent-specific hook schemas stay isolated in adapters;
• remote access is intentionally narrower than local access;
• Nofax does not grant authority the calling agent did not already have.

Two operating modes

The remote Worker is not a hosted remote-approval service. It can send an informational notification and inspect existing request state, but it has no approval callback, choice, refinement, wait, webhook, or arbitrary remote-write endpoint.

Quick start

1. Install

npm install -g nofax

Requires Node.js 20 or newer.

2. Initialize

nofax init

Nofax creates ~/.nofax/config.json and generates a high-entropy notification topic. With the default transport, subscribe to the displayed topic in the ntfy mobile app.

3. Test

nofax test

4. Use it

nofax notify --title "Build finished" "All tests passed"

nofax approve --title "Deploy?" "Release 1.4.0 is ready" nofax refine --title "Refine draft" "Tell me what to change"

An approval resolves to stable terminal JSON:

{"decision":"allow"}

or:

{"decision":"deny"}

If the request is still pending, times out, disconnects, or hits a transport error, Nofax never converts that condition into approval.

For scripts using nofax approve, exit status 0 means explicit allow, 2 means explicit deny, 3 means timeout, and 1 means an error or unrecognized decision. The terminal JSON decision remains unchanged. Never treat a denied request as successful based solely on receipt of a response.

ntfy client compatibility: On iOS, the ntfy app may leave an HTTP action notification visible after you tap Allow or Deny, even when the action requests clear: true (upstream ntfy issue #1728). A still-visible notification does not prove whether Nofax recorded a decision: rely on Nofax's terminal allow/deny response or pending/timeout state, not on whether the notification disappears. If you use the ntfy web app instead of the mobile app, HTTP action buttons in notifications are supported in Chrome, Edge, and Opera but not Firefox or Safari; cross-origin callbacks also need the target server to allow CORS (ntfy web-app support).

Windows PowerShell with restricted script execution

If PowerShell reports that npm.ps1 or npx.ps1 cannot be loaded because scripts are disabled, invoke npm's Windows .cmd launchers explicitly. The usual global install creates a nofax.cmd launcher too:

npm.cmd install --global nofax

nofax.cmd init nofax.cmd test

For a one-off local MCP launch without a global Nofax installation, use npx.cmd -y nofax mcp (the final mcp argument is required). An MCP client that launches npx through PowerShell can set its command to npx.cmd with arguments ["-y", "nofax", "mcp"]. These are executable launchers, not a request to disable or bypass your organization's PowerShell execution policy. If executable launches themselves are restricted, follow your administrator's policy instead. See Microsoft's PowerShell execution policy reference.

MCP

Start the local stdio MCP server:

nofax mcp

Connect an MCP client

Claude Code can launch the published local MCP server directly:

claude mcp add nofax -- npx -y nofax mcp

Codex CLI can register the same stdio server:

codex mcp add nofax -- npx -y nofax mcp

Gemini CLI can register it in user settings:

gemini mcp add --scope user --transport stdio nofax npx -- -y nofax mcp

Gemini CLI may mark configured servers Disabled when the current workspace is untrusted. Review and trust only workspaces you control through Gemini's normal trust flow; do not use --trust to bypass MCP tool-call confirmations. Registering an MCP server does not automatically install the separate permission hooks documented below.

VS Code can register Nofax in its user-profile MCP configuration. Open the Command Palette, choose MCP: Open User Configuration, and add this entry to mcp.json:

{

"servers": { "nofax": { "type": "stdio", "command": "npx", "args": ["-y", "nofax", "mcp"] } } }

Merge the nofax entry with any existing servers rather than replacing them. Review VS Code's normal server-trust prompt before starting it; MCP registration does not install separate permission hooks.

For other stdio MCP clients, set the command to npx with arguments ["-y", "nofax", "mcp"]. The final mcp argument is required: running npx -y nofax without it prints the CLI usage and exits instead of starting a server. On Windows, use npx.cmd when a PowerShell script-execution policy prevents the .ps1 shim from running. Complete the Quick start configuration before using notification or approval tools.

Local MCP exposes:

• nofax_notify
• nofax_request_approval
• nofax_request_choice
• nofax_request_refinement
• nofax_wait_for_response
• nofax_get_request
• nofax_list_pending

Interactive requests return a durable request ID. nofax_wait_for_response performs a bounded wait; callers must repeat the wait while the request remains pending rather than infer approval.

Agent integrations

Claude Code

Use Nofax as a local PermissionRequest hook in ~/.claude/settings.json:

{

"hooks": { "PermissionRequest": [ { "matcher": ".*", "hooks": [ { "type": "command", "command": "nofax hook claude" } ] } ] } }

Codex

Codex hooks are enabled by default. Configure ~/.codex/hooks.json:

{

"hooks": { "PermissionRequest": [ { "matcher": ".*", "hooks": [ { "type": "command", "command": "nofax hook codex", "statusMessage": "Waiting for Nofax approval" } ] } ] } }

Restart Codex, run /hooks, and review/trust the exact Nofax hook definition before relying on it. Codex skips non-managed hooks until they are trusted, and a changed hook definition must be reviewed again. If an administrator or local policy has explicitly disabled hooks, re-enable them with [features] hooks = true in ~/.codex/config.toml.

Codex currently evaluates PermissionRequest hooks before its configured approval reviewer. A terminal Nofax Allow/Deny therefore resolves the request before Codex can route it to approvals_reviewer = "auto_review" (or the legacy guardian_subagent value). If you want Nofax to be the human approval surface, use approvals_reviewer = "user"; do not combine this Nofax approval hook with Auto-review/Guardian expecting both reviewers to run. Current Codex hook input does not expose the effective reviewer, so Nofax cannot safely distinguish a user-routed approval from one that Codex intended to auto-review.

PermissionRequest hooks are also serial with Codex's native approval UI: while Nofax is waiting, the normal Codex approval prompt is not simultaneously available. If Nofax returns no decision (for example after timeout or transport failure), Codex falls back to its normal approval flow. Nofax never converts that fallback condition into approval.

Gemini CLI

Current Gemini CLI builds expose a synchronous BeforeTool hook that can allow or deny a tool call. Route selected tools through Nofax in ~/.gemini/settings.json:

{

"hooks": { "BeforeTool": [ { "matcher": "run_shell_command|write_file|replace", "hooks": [ { "name": "nofax-approval", "type": "command", "command": "nofax hook gemini", "timeout": 305000 } ] } ], "Notification": [ { "matcher": "ToolPermission", "hooks": [ { "name": "nofax-notification", "type": "command", "command": "nofax hook gemini" } ] } ] } }

BeforeTool waits for an explicit Nofax Allow/Deny result. A Nofax timeout or transport failure returns Gemini's ask decision, forcing the native interactive confirmation instead of allowing an auto-approval policy to treat the missing Nofax decision as permission. The Notification hook remains advisory and is forwarded only as a phone notification.

Adjust the matcher to the tools you want Nofax to gate. Keep the hook timeout longer than Nofax's configured approval timeout (timeoutSeconds, 300 seconds by default).

Pi (native MCP support)

Pi 1.x has built-in MCP support for local stdio servers; see Pi's official MCP documentation. After nofax init, register and check the Nofax server:

pi mcp add nofax -- npx -y nofax mcp

pi mcp list

Pi's default MCP request timeout is 60 seconds. If you use nofax_wait_for_response with waits longer than that (up to Nofax's 240-second maximum), add "timeout": 300 to the existing nofax entry in ~/.pi/agent/mcp.json. Do not replace unrelated server entries or settings:

{

"mcpServers": { "nofax": { "command": "npx", "args": ["-y", "nofax", "mcp"], "timeout": 300 } } }

Pi's built-in MCP configuration lives in ~/.pi/agent/mcp.json. Third-party extensions that replace /mcp (such as pi-mcp-adapter) take over the interactive MCP integration and may not load that built-in configuration. Verify which MCP implementation your Pi session is using before adding or changing a server; do not disable Pi's permission gates or install a second MCP runtime just for Nofax.

This registers MCP tools, not an automatic permission hook or idle-session wake-up. While a request is pending, the agent must call `nofax_wait_