cc-relay 0.1.0__tar.gz

cc_relay-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ty
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cc_relay-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: cc-relay
+Version: 0.1.0
+Summary: Intelligent interrupt layer for Claude — learns when to ask, when to proceed
+License: MIT
+Project-URL: Homepage, https://github.com/solost23/relay
+Project-URL: Repository, https://github.com/solost23/relay
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anthropic>=0.102.0
+Requires-Dist: mcp[cli]>=1.27.1
+Requires-Dist: plyer>=2.1.0
+Provides-Extra: macos
+Requires-Dist: pyobjus>=1.2.4; extra == "macos"
+Dynamic: license-file
+
+# Relay
+
+Relay 是一个 Claude Code 智能中断层。它通过 hook 拦截每次工具调用，结合历史审批记录和风险评估，自动决定哪些操作直接执行、哪些需要暂停等你确认，并在需要确认时发送桌面通知。
+
+**核心价值：** 让 AI 任务在后台跑，只在真正需要你决策时才打断你。
+
+[English](README.en.md) | [日本語](README.ja.md) | [한국어](README.ko.md)
+
+## 工作原理
+
+```
+Claude 准备执行工具（Write、Bash、Edit 等）
+    ↓
+PreToolUse hook 触发 → relay hook pre
+    ↓
+查询历史批准率 + 评估风险等级
+    ↓
+allow → 工具直接执行，自动记录为已批准
+ask   → 工具暂停，发送桌面通知，Claude Code 弹出确认提示
+    ↓
+用户确认后 Claude 继续，PostToolUse hook 记录结果
+    ↓
+历史积累 → 下次同类操作判断更准确
+```
+
+## 决策逻辑
+
+| 条件 | 结果 |
+|---|---|
+| 高风险操作（删文件、force push、drop 表、写系统路径） | 始终拦截 |
+| 低风险 + 历史批准率 ≥ 90% | 始终直接执行 |
+| 该类型操作首次出现（无历史） | 低风险直接执行，其他拦截一次建立基线 |
+| 其他情况 | 历史批准率 < 80% 则拦截 |
+
+操作类型按路径和命令细分，各自独立积累批准率：
+
+| 操作类型 | 说明 | 风险 |
+|---|---|---|
+| `file_write:system` | 写入 `/etc/`、`/usr/` 等系统路径 | 高 |
+| `file_write:config` | 写入 `.env`、`.yaml`、`.toml` 等配置文件 | 中 |
+| `file_write:code` | 写入普通代码文件 | 中 |
+| `bash_write:git` | git commit / push / merge | 中 |
+| `bash_write:package_manager` | pip / uv / npm 安装 | 中 |
+| `bash_write:shell` | mv / cp / chmod 等 shell 操作 | 中 |
+| `file_delete` | rm、drop table 等删除操作 | 高 |
+| `bash_read` / `file_read` | 只读操作 | 低 |
+
+## 安装
+
+**全局安装**（推荐）——将以下内容添加到 **`~/.claude.json`** 的 `mcpServers` 字段：
+
+```json
+{
+  "mcpServers": {
+    "relay": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["cc-relay"]
+    }
+  }
+}
+```
+
+**项目级安装**——在项目根目录创建 **`.mcp.json`**：
+
+```json
+{
+  "mcpServers": {
+    "relay": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["cc-relay"]
+    }
+  }
+}
+```
+
+重启 Claude Code。Relay 会在首次启动时自动将 hook 注册到 `~/.claude/settings.json`，之后所有工具调用都会经过 relay 的决策层。
+
+## 卸载
+
+```bash
+uvx cc-relay --uninstall
+```
+
+## 通知支持
+
+通知文字会根据系统语言自动切换，目前支持中文、英文、日文、韩文。
+
+| 平台 | 实现 | 说明 |
+|---|---|---|
+| macOS | `osascript` | 系统内置，开箱即用 |
+| Linux | `notify-send` | 需要桌面环境，Ubuntu/GNOME 默认已有 |
+| Windows | `plyer` | 开箱即用 |
+
+## MCP 工具（可选）
+
+安装 hook 后 relay 已经自动工作，不需要额外配置。但如果你想查看统计数据，可以在 Claude Code 里调用 `relay__get_stats_tool` 查看审批统计。
+
+## 已知限制
+
+Relay hook 在 `--dangerously-skip-permissions` 模式下不生效（该模式完全跳过 hook 机制）。
+
+## 本地开发
+
+```bash
+git clone https://github.com/solost23/cc-relay
+cd cc-relay
+uv sync
+uv run pytest
+uv run mcp dev relay/server.py
+```
+

cc_relay-0.1.0/README.md

@@ -0,0 +1,113 @@
+# Relay
+
+Relay 是一个 Claude Code 智能中断层。它通过 hook 拦截每次工具调用，结合历史审批记录和风险评估，自动决定哪些操作直接执行、哪些需要暂停等你确认，并在需要确认时发送桌面通知。
+
+**核心价值：** 让 AI 任务在后台跑，只在真正需要你决策时才打断你。
+
+[English](README.en.md) | [日本語](README.ja.md) | [한국어](README.ko.md)
+
+## 工作原理
+
+```
+Claude 准备执行工具（Write、Bash、Edit 等）
+    ↓
+PreToolUse hook 触发 → relay hook pre
+    ↓
+查询历史批准率 + 评估风险等级
+    ↓
+allow → 工具直接执行，自动记录为已批准
+ask   → 工具暂停，发送桌面通知，Claude Code 弹出确认提示
+    ↓
+用户确认后 Claude 继续，PostToolUse hook 记录结果
+    ↓
+历史积累 → 下次同类操作判断更准确
+```
+
+## 决策逻辑
+
+| 条件 | 结果 |
+|---|---|
+| 高风险操作（删文件、force push、drop 表、写系统路径） | 始终拦截 |
+| 低风险 + 历史批准率 ≥ 90% | 始终直接执行 |
+| 该类型操作首次出现（无历史） | 低风险直接执行，其他拦截一次建立基线 |
+| 其他情况 | 历史批准率 < 80% 则拦截 |
+
+操作类型按路径和命令细分，各自独立积累批准率：
+
+| 操作类型 | 说明 | 风险 |
+|---|---|---|
+| `file_write:system` | 写入 `/etc/`、`/usr/` 等系统路径 | 高 |
+| `file_write:config` | 写入 `.env`、`.yaml`、`.toml` 等配置文件 | 中 |
+| `file_write:code` | 写入普通代码文件 | 中 |
+| `bash_write:git` | git commit / push / merge | 中 |
+| `bash_write:package_manager` | pip / uv / npm 安装 | 中 |
+| `bash_write:shell` | mv / cp / chmod 等 shell 操作 | 中 |
+| `file_delete` | rm、drop table 等删除操作 | 高 |
+| `bash_read` / `file_read` | 只读操作 | 低 |
+
+## 安装
+
+**全局安装**（推荐）——将以下内容添加到 **`~/.claude.json`** 的 `mcpServers` 字段：
+
+```json
+{
+  "mcpServers": {
+    "relay": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["cc-relay"]
+    }
+  }
+}
+```
+
+**项目级安装**——在项目根目录创建 **`.mcp.json`**：
+
+```json
+{
+  "mcpServers": {
+    "relay": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["cc-relay"]
+    }
+  }
+}
+```
+
+重启 Claude Code。Relay 会在首次启动时自动将 hook 注册到 `~/.claude/settings.json`，之后所有工具调用都会经过 relay 的决策层。
+
+## 卸载
+
+```bash
+uvx cc-relay --uninstall
+```
+
+## 通知支持
+
+通知文字会根据系统语言自动切换，目前支持中文、英文、日文、韩文。
+
+| 平台 | 实现 | 说明 |
+|---|---|---|
+| macOS | `osascript` | 系统内置，开箱即用 |
+| Linux | `notify-send` | 需要桌面环境，Ubuntu/GNOME 默认已有 |
+| Windows | `plyer` | 开箱即用 |
+
+## MCP 工具（可选）
+
+安装 hook 后 relay 已经自动工作，不需要额外配置。但如果你想查看统计数据，可以在 Claude Code 里调用 `relay__get_stats_tool` 查看审批统计。
+
+## 已知限制
+
+Relay hook 在 `--dangerously-skip-permissions` 模式下不生效（该模式完全跳过 hook 机制）。
+
+## 本地开发
+
+```bash
+git clone https://github.com/solost23/cc-relay
+cd cc-relay
+uv sync
+uv run pytest
+uv run mcp dev relay/server.py
+```
+

cc_relay-0.1.0/cc_relay.egg-info/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: cc-relay
+Version: 0.1.0
+Summary: Intelligent interrupt layer for Claude — learns when to ask, when to proceed
+License: MIT
+Project-URL: Homepage, https://github.com/solost23/relay
+Project-URL: Repository, https://github.com/solost23/relay
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anthropic>=0.102.0
+Requires-Dist: mcp[cli]>=1.27.1
+Requires-Dist: plyer>=2.1.0
+Provides-Extra: macos
+Requires-Dist: pyobjus>=1.2.4; extra == "macos"
+Dynamic: license-file
+
+# Relay
+
+Relay 是一个 Claude Code 智能中断层。它通过 hook 拦截每次工具调用，结合历史审批记录和风险评估，自动决定哪些操作直接执行、哪些需要暂停等你确认，并在需要确认时发送桌面通知。
+
+**核心价值：** 让 AI 任务在后台跑，只在真正需要你决策时才打断你。
+
+[English](README.en.md) | [日本語](README.ja.md) | [한국어](README.ko.md)
+
+## 工作原理
+
+```
+Claude 准备执行工具（Write、Bash、Edit 等）
+    ↓
+PreToolUse hook 触发 → relay hook pre
+    ↓
+查询历史批准率 + 评估风险等级
+    ↓
+allow → 工具直接执行，自动记录为已批准
+ask   → 工具暂停，发送桌面通知，Claude Code 弹出确认提示
+    ↓
+用户确认后 Claude 继续，PostToolUse hook 记录结果
+    ↓
+历史积累 → 下次同类操作判断更准确
+```
+
+## 决策逻辑
+
+| 条件 | 结果 |
+|---|---|
+| 高风险操作（删文件、force push、drop 表、写系统路径） | 始终拦截 |
+| 低风险 + 历史批准率 ≥ 90% | 始终直接执行 |
+| 该类型操作首次出现（无历史） | 低风险直接执行，其他拦截一次建立基线 |
+| 其他情况 | 历史批准率 < 80% 则拦截 |
+
+操作类型按路径和命令细分，各自独立积累批准率：
+
+| 操作类型 | 说明 | 风险 |
+|---|---|---|
+| `file_write:system` | 写入 `/etc/`、`/usr/` 等系统路径 | 高 |
+| `file_write:config` | 写入 `.env`、`.yaml`、`.toml` 等配置文件 | 中 |
+| `file_write:code` | 写入普通代码文件 | 中 |
+| `bash_write:git` | git commit / push / merge | 中 |
+| `bash_write:package_manager` | pip / uv / npm 安装 | 中 |
+| `bash_write:shell` | mv / cp / chmod 等 shell 操作 | 中 |
+| `file_delete` | rm、drop table 等删除操作 | 高 |
+| `bash_read` / `file_read` | 只读操作 | 低 |
+
+## 安装
+
+**全局安装**（推荐）——将以下内容添加到 **`~/.claude.json`** 的 `mcpServers` 字段：
+
+```json
+{
+  "mcpServers": {
+    "relay": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["cc-relay"]
+    }
+  }
+}
+```
+
+**项目级安装**——在项目根目录创建 **`.mcp.json`**：
+
+```json
+{
+  "mcpServers": {
+    "relay": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["cc-relay"]
+    }
+  }
+}
+```
+
+重启 Claude Code。Relay 会在首次启动时自动将 hook 注册到 `~/.claude/settings.json`，之后所有工具调用都会经过 relay 的决策层。
+
+## 卸载
+
+```bash
+uvx cc-relay --uninstall
+```
+
+## 通知支持
+
+通知文字会根据系统语言自动切换，目前支持中文、英文、日文、韩文。
+
+| 平台 | 实现 | 说明 |
+|---|---|---|
+| macOS | `osascript` | 系统内置，开箱即用 |
+| Linux | `notify-send` | 需要桌面环境，Ubuntu/GNOME 默认已有 |
+| Windows | `plyer` | 开箱即用 |
+
+## MCP 工具（可选）
+
+安装 hook 后 relay 已经自动工作，不需要额外配置。但如果你想查看统计数据，可以在 Claude Code 里调用 `relay__get_stats_tool` 查看审批统计。
+
+## 已知限制
+
+Relay hook 在 `--dangerously-skip-permissions` 模式下不生效（该模式完全跳过 hook 机制）。
+
+## 本地开发
+
+```bash
+git clone https://github.com/solost23/cc-relay
+cd cc-relay
+uv sync
+uv run pytest
+uv run mcp dev relay/server.py
+```
+

cc_relay-0.1.0/cc_relay.egg-info/SOURCES.txt

@@ -0,0 +1,23 @@
+LICENSE
+README.md
+pyproject.toml
+cc_relay.egg-info/PKG-INFO
+cc_relay.egg-info/SOURCES.txt
+cc_relay.egg-info/dependency_links.txt
+cc_relay.egg-info/entry_points.txt
+cc_relay.egg-info/requires.txt
+cc_relay.egg-info/top_level.txt
+relay/__init__.py
+relay/__main__.py
+relay/assessor.py
+relay/db.py
+relay/decision.py
+relay/hook.py
+relay/installer.py
+relay/notifier.py
+relay/server.py
+tests/test_assessor.py
+tests/test_db.py
+tests/test_hook.py
+tests/test_installer.py
+tests/test_server.py

cc_relay-0.1.0/cc_relay.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

cc_relay-0.1.0/cc_relay.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+relay = relay.server:main

cc_relay-0.1.0/cc_relay.egg-info/requires.txt

@@ -0,0 +1,6 @@
+anthropic>=0.102.0
+mcp[cli]>=1.27.1
+plyer>=2.1.0
+
+[macos]
+pyobjus>=1.2.4

cc_relay-0.1.0/cc_relay.egg-info/top_level.txt

@@ -0,0 +1 @@
+relay

cc_relay-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "cc-relay"
+version = "0.1.0"
+description = "Intelligent interrupt layer for Claude — learns when to ask, when to proceed"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.12"
+dependencies = [
+    "anthropic>=0.102.0",
+    "mcp[cli]>=1.27.1",
+    "plyer>=2.1.0",
+]
+
+[project.optional-dependencies]
+macos = ["pyobjus>=1.2.4"]
+
+[project.urls]
+Homepage = "https://github.com/solost23/relay"
+Repository = "https://github.com/solost23/relay"
+
+[project.scripts]
+relay = "relay.server:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+]

cc_relay-0.1.0/relay/__main__.py

@@ -0,0 +1,43 @@
+import sys
+
+
+def main() -> None:
+    args = sys.argv[1:]
+
+    if not args:
+        # Default: start MCP server
+        from relay.server import main as serve
+        serve()
+        return
+
+    cmd = args[0]
+
+    if cmd == "--install":
+        from relay.installer import install
+        install()
+
+    elif cmd == "--uninstall":
+        from relay.installer import uninstall
+        uninstall()
+
+    elif cmd == "hook" and len(args) >= 2:
+        from relay.db import init_db
+        init_db()
+        subcommand = args[1]
+        if subcommand == "pre":
+            from relay.hook import run_pre_tool_use
+            run_pre_tool_use()
+        elif subcommand == "post":
+            from relay.hook import run_post_tool_use
+            run_post_tool_use()
+        else:
+            print(f"Unknown hook subcommand: {subcommand}", file=sys.stderr)
+            sys.exit(1)
+
+    else:
+        print(f"Usage: relay [--install | --uninstall | hook pre | hook post]", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

cc_relay-0.1.0/relay/assessor.py

@@ -0,0 +1,86 @@
+_HIGH_RISK_TYPES = {
+    "file_delete",
+    "db_drop",
+    "git_reset",
+    "git_force_push",
+    "git_rebase",
+    "git_amend",
+    "rm_rf",
+    "process_kill",
+    "file_write:system",
+    "env_write",
+    "secret_write",
+    "permission_change",
+    "network_send",
+    "ci_cd_modify",
+    "cron_write",
+}
+
+_LOW_RISK_TYPES = {
+    "file_read",
+    "bash_read",
+    "git_log",
+    "git_status",
+    "git_diff",
+    "db_read",
+    "list_files",
+}
+
+_MEDIUM_RISK_TYPES = {
+    "file_write:code",
+    "file_write:config",
+    "file_create",
+    "db_write",
+    "db_update",
+    "bash_write:git",
+    "bash_write:package_manager",
+    "bash_write:shell",
+    "network_request",
+    # legacy — kept for existing DB records
+    "file_write",
+    "git_commit",
+    "git_push",
+    "bash_write",
+}
+
+
+def assess_risk(action_type: str, action_description: str) -> dict:
+    """Return risk_level, reversible flag, and reason for the given action."""
+    t = action_type.lower()
+
+    if t in _HIGH_RISK_TYPES:
+        return {
+            "risk_level": "high",
+            "reversible": False,
+            "reason": f"Action type '{action_type}' is destructive and not reversible.",
+        }
+
+    if t in _LOW_RISK_TYPES:
+        return {
+            "risk_level": "low",
+            "reversible": True,
+            "reason": f"Action type '{action_type}' is read-only and safe.",
+        }
+
+    if t in _MEDIUM_RISK_TYPES:
+        return {
+            "risk_level": "medium",
+            "reversible": True,
+            "reason": f"Action type '{action_type}' modifies state but is generally recoverable.",
+        }
+
+    # Heuristic fallback: scan description for danger words
+    danger_words = {"delete", "remove", "drop", "truncate", "force", "overwrite", "rm"}
+    desc_lower = action_description.lower()
+    if any(w in desc_lower for w in danger_words):
+        return {
+            "risk_level": "high",
+            "reversible": False,
+            "reason": "Description contains potentially destructive keywords.",
+        }
+
+    return {
+        "risk_level": "medium",
+        "reversible": True,
+        "reason": f"Unknown action type '{action_type}'; defaulting to medium risk.",
+    }

cc_relay-0.1.0/relay/db.py

@@ -0,0 +1,96 @@
+import sqlite3
+from pathlib import Path
+
+_DEFAULT_DB = Path.home() / ".relay" / "decisions.db"
+
+
+def _db_path(path: Path | None) -> Path:
+    return path if path is not None else _DEFAULT_DB
+
+
+def init_db(db_path: Path | None = None) -> Path:
+    p = _db_path(db_path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    with sqlite3.connect(p) as conn:
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS decisions (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                action_type TEXT NOT NULL,
+                action_description TEXT NOT NULL,
+                decision TEXT NOT NULL,
+                risk_level TEXT NOT NULL,
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+            )
+        """)
+    return p
+
+
+def record_decision(
+    action_type: str,
+    action_description: str,
+    decision: str,
+    risk_level: str,
+    db_path: Path | None = None,
+) -> None:
+    with sqlite3.connect(_db_path(db_path)) as conn:
+        conn.execute(
+            "INSERT INTO decisions (action_type, action_description, decision, risk_level) VALUES (?, ?, ?, ?)",
+            (action_type, action_description, decision, risk_level),
+        )
+
+
+_APPROVAL_RATE_WINDOW = 50  # only consider the most recent N decisions per action type
+
+
+def get_approval_rate(action_type: str, db_path: Path | None = None) -> float:
+    with sqlite3.connect(_db_path(db_path)) as conn:
+        rows = conn.execute(
+            "SELECT decision FROM decisions WHERE action_type = ? ORDER BY created_at DESC, id DESC LIMIT ?",
+            (action_type, _APPROVAL_RATE_WINDOW),
+        ).fetchall()
+        if not rows:
+            return 0.5
+        approved = sum(1 for (d,) in rows if d == "approved")
+        return approved / len(rows)
+
+
+def get_stats(db_path: Path | None = None) -> dict:
+    """Return approval stats for all action types plus total decision count."""
+    with sqlite3.connect(_db_path(db_path)) as conn:
+        conn.row_factory = sqlite3.Row
+        total = conn.execute("SELECT COUNT(*) FROM decisions").fetchone()[0]
+        rows = conn.execute("""
+            SELECT
+                action_type,
+                COUNT(*) AS total,
+                SUM(CASE WHEN decision = 'approved' THEN 1 ELSE 0 END) AS approved
+            FROM decisions
+            GROUP BY action_type
+            ORDER BY total DESC
+        """).fetchall()
+        by_type = [
+            {
+                "action_type": r["action_type"],
+                "total": r["total"],
+                "approved": r["approved"],
+                "approval_rate": round(r["approved"] / r["total"], 3),
+            }
+            for r in rows
+        ]
+        return {"total_decisions": total, "by_action_type": by_type}
+
+
+def get_recent_decisions(
+    action_type: str, limit: int = 20, db_path: Path | None = None
+) -> list[dict]:
+    with sqlite3.connect(_db_path(db_path)) as conn:
+        conn.row_factory = sqlite3.Row
+        rows = conn.execute(
+            """
+            SELECT action_type, action_description, decision, risk_level, created_at
+            FROM decisions WHERE action_type = ?
+            ORDER BY created_at DESC, id DESC LIMIT ?
+            """,
+            (action_type, limit),
+        ).fetchall()
+        return [dict(r) for r in rows]