cc-relay 0.3.0

Intelligent interrupt layer for Claude Code and Codex — learns when to ask, when to proceed

cc-relay

An adaptive interrupt layer for Claude Code and Codex. Relay intercepts tool calls via hooks, learns from your approval history, and automatically decides what to let through — only interrupting you when a real decision is needed, and sending a desktop notification so you're never left wondering why the task stalled.

The key idea: other permission tools use static rules or call an LLM on every action. Relay tracks your actual approval rate per action type and adapts over time. After you approve git commit ten times, it stops asking. High-risk operations always interrupt — everything else gets quieter as you use it.

中文 | 日本語 | 한국어

Why cc-relay

	Static allowlists	LLM classifier	cc-relay
Setup	Manual rule maintenance	API key required	Zero config
Learns from you	No	No	Yes
Cost per decision	Free	~$0.001/call	Free
Adapts to your workflow	No	No	Yes
Works offline	Yes	No	Yes

How it works

The agent is about to execute a tool (Write, Bash, Edit, shell command, etc.)
    ↓
PreToolUse hook fires → relay hook pre
    ↓
Look up historical approval rate + assess risk level
    ↓
allow → tool executes immediately, auto-recorded as approved
interrupt → tool pauses or is blocked, desktop notification sent, client asks for your decision
    ↓
User confirms → agent continues, PostToolUse marks record as approved
User rejects  → session ends
    ↓
Stop hook fires → marks pending records as rejected + sends completion notification
    ↓
History accumulates → same action type gets quieter over time

Decision logic

Condition	Result
High-risk (delete files, force push, drop table, system paths)	Always interrupt
Low risk, effective weight < 4	Auto-approve (no baseline needed)
Low risk, effective weight ≥ 4, approval rate ≥ 90%	Auto-approve
Medium risk, effective weight < 7	Interrupt to build baseline
Medium risk, effective weight ≥ 7, approval rate ≥ 85%	Auto-approve
Everything else	Interrupt

Approval rates use exponential time decay (half-life: 7 days) — recent decisions carry more weight than old ones. If you start rejecting an action you previously always approved, the weighted approval rate drops quickly and Relay starts interrupting again within days. Old approvals fade naturally, so the system never gets permanently locked into auto-approve.

Action type	Description	Risk
file_write:system	Write to /etc/, /usr/, etc.	High
file_write:config	Write to .env, .yaml, .toml, etc.	Medium
file_write:code	Write to regular code files	Medium
bash_write:git	git commit / push / merge	Medium
bash_write:package_manager	pip / uv / npm installs	Medium
bash_write:shell	mv / cp / chmod and other shell ops	Medium
file_delete	rm, drop table, and other deletions	High
bash_read / file_read	Read-only operations	Low

Installation

Relay supports both Claude Code and Codex. Add the MCP server to your agent config; on first startup, Relay installs hooks for both clients:

• Claude Code hooks: ~/.claude/settings.json
• Codex hooks: ~/.codex/config.toml

Claude Code global config — add to the mcpServers field in ~/.claude.json:

{
  "mcpServers": {
    "relay": {
      "type": "stdio",
      "command": "uvx",
      "args": ["cc-relay@latest"]
    }
  }
}

Codex global config — add to ~/.codex/config.toml:

[mcp_servers.relay]
type = "stdio"
command = "uvx"
args = ["cc-relay@latest"]

Restart your agent. Relay starts as an MCP server and runs --install-all behavior automatically, so both Claude Code and Codex hooks are kept up to date.

Uninstall

uvx cc-relay --uninstall-all

Notification support

Relay sends two types of desktop notifications. Text auto-switches based on system language (Chinese, English, Japanese, Korean).

• Interrupt: when an action needs your approval — prompts you to return to the terminal
• Completion: when the agent finishes responding — so you know the task is done even if you stepped away

Platform	Implementation	Notes
macOS	osascript	Built-in, works out of the box
Linux	notify-send	Requires desktop environment (default on Ubuntu/GNOME)
Windows	plyer	Works out of the box

MCP tools

Once installed, Relay works automatically. You can also call these tools directly inside Claude Code or Codex:

Tool	Description
relay__get_stats_tool	View approval statistics for all action types
relay__get_recent_decisions_tool	View recent decision history for a specific action type
relay__reset_action_type_tool	Clear history for an action type and rebuild baseline

CLI

# Install / uninstall both Claude Code and Codex hooks
uvx cc-relay --install-all
uvx cc-relay --uninstall-all

# Advanced: manage one client only
uvx cc-relay --install
uvx cc-relay --install-codex
uvx cc-relay --uninstall
uvx cc-relay --uninstall-codex

# View recent decisions for an action type (default 20)
uvx cc-relay --history bash_write:git
uvx cc-relay --history file_write:code 50

# Clear all history for an action type
uvx cc-relay --reset bash_write:git

Known limitations

Relay hooks do not fire in --dangerously-skip-permissions mode (that mode bypasses the hook mechanism entirely).

Local development

git clone https://github.com/solost23/cc-relay
cd cc-relay
uv sync
uv run pytest
uv run mcp dev cc_relay/server.py