{"_id":"@dasooul/oh-my-agent","name":"@dasooul/oh-my-agent","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@dasooul/oh-my-agent","version":"0.1.0","description":"Cross-agent governance layer for AI coding agents — audit, policy, context, MCP","bin":{"oma":"bin/oma.js"},"scripts":{"postinstall":"node bin/build.js","build":"go build -o bin/oma.exe ."},"repository":{"type":"git","url":"git+https://github.com/Dasooul03/oh-my-agent.git"},"publishConfig":{"access":"public"},"keywords":["claude","opencode","codex","gemini","aider","audit","policy"],"license":"MIT","_id":"@dasooul/oh-my-agent@0.1.0","gitHead":"d064679fa60c0b4a334d700b7357ae008f6ba00c","bugs":{"url":"https://github.com/Dasooul03/oh-my-agent/issues"},"homepage":"https://github.com/Dasooul03/oh-my-agent#readme","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-RPQuoiaiUzqoNEuJNOynBEw5KypNS9clxuIYKjMlfXwN+ae4xdLYrBaIvA3PvxWCIdI3GxEsbWnb27jraXjHQQ==","shasum":"2450dc6572a8c26e50ae38cf2f2b41da2f3e7dfc","tarball":"https://registry.npmjs.org/@dasooul/oh-my-agent/-/oh-my-agent-0.1.0.tgz","fileCount":48,"unpackedSize":162164,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIHt94TJ42GQCvXrp7Qv0q8HiU2It0OzHRDV8QwtExm6oAiEArLdm/c6ANQsq25M3N/epCJQCyWPr4uKuBxKkjbUj/rQ="}]},"_npmUser":{"name":"dasooul","email":"daijuyicoding@qq.com"},"directories":{},"maintainers":[{"name":"dasooul","email":"daijuyicoding@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/oh-my-agent_0.1.0_1783094990167_0.906141037315003"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-03T16:09:49.982Z","0.1.0":"2026-07-03T16:09:50.310Z","modified":"2026-07-03T16:09:50.541Z"},"maintainers":[{"name":"dasooul","email":"daijuyicoding@qq.com"}],"description":"Cross-agent governance layer for AI coding agents — audit, policy, context, MCP","homepage":"https://github.com/Dasooul03/oh-my-agent#readme","keywords":["claude","opencode","codex","gemini","aider","audit","policy"],"repository":{"type":"git","url":"git+https://github.com/Dasooul03/oh-my-agent.git"},"bugs":{"url":"https://github.com/Dasooul03/oh-my-agent/issues"},"license":"MIT","readme":"# oh-my-agent (oma)\n\n> [English](README.md)\n\nAI 编程代理的跨代理治理层。为 Claude Code、Gemini CLI、OpenCode、Codex CLI 和 Aider 提供统一的审计日志、策略执行和上下文反馈注入。\n\n---\n\n## 给人类用户\n\n发布到 npm 后，复制以下指令给你的 AI 编程代理：\n\n```\nnpm install -g oh-my-agent && oma audit install && oma policy init && oma doctor\n```\n\n如果没有 npm，可以从 GitHub 克隆并构建：\n\n```\ngit clone https://github.com/Dasooul03/oh-my-agent.git && cd oh-my-agent && go build -o oma.exe . && oma audit install && oma policy init && oma doctor\n```\n\n## 给 AI 代理阅读\n\n> 如果你是正在阅读本文的 AI 编程代理，请注意以下内容。\n\n- **审计**：你的每一次工具调用都会记录到 `~/.oma/audit/`。这个日志是所有代理共享的——其他代理可以看到你做过什么。\n- **策略**：部分命令可能会被策略规则拦截。如果 `rm -rf /` 被拒绝，那是 oma 的策略执行在起作用。不要重试被拦截的命令。\n- **上下文摘要**：会话启动时，hook 可能会注入一段 Markdown 摘要，展示其他代理近期的活动。阅读它来了解已经完成的工作。\n- **MCP 工具**：当 `oma mcp serve` 运行时，你可以查询 `oma_audit_recent`、`oma_audit_search`、`oma_who_changed`、`oma_policy_status` 和 `oma_handoff` 来了解其他代理的工作。\n\n## 功能\n\n- **统一审计** — 所有代理的工具调用统一记录到 `~/.oma/audit/YYYY-MM-DD.jsonl`\n- **策略执行** — deny/ask 规则跨所有代理拦截危险命令（`rm -rf`、`git push --force` 等）\n- **上下文反馈** — 在会话启动时注入近期活动摘要，让每个代理知道其他代理做了什么\n- **MCP 集成** — 通过 MCP 暴露审计和策略工具，代理之间可以互相查询活动\n- **Aider 摄入** — 解析 `~/.aider.chat.history.md` 到统一审计日志（aider 没有原生 hook）\n- **零外部依赖** — 完全基于 Go 标准库，无需 `go mod download`，无供应链风险\n\n## 支持的代理\n\n| 代理 | 二进制 | 检测方式 | Hook | 事件类型 |\n|-------|--------|-----------|-------|-------------|\n| Claude Code | `claude` | PATH + 标准安装路径 | PreToolUse, PostToolUse, SessionStart, UserPromptSubmit, PermissionRequest | `tool.before`, `tool.after`, `session.start`, `prompt.user` |\n| Gemini CLI | `gemini` | PATH + 标准安装路径 | BeforeTool, AfterTool, SessionStart, UserPromptSubmit | `tool.before`, `tool.after`, `session.start` |\n| OpenCode | `opencode` | PATH + npm 全局 + 桌面应用 | PreToolUse, PostToolUse, `session.start` | `tool.before`, `tool.after` |\n| Codex CLI | `codex` | PATH + 官方安装路径 | PreToolUse, SessionStart（仅 bash，[#16732](https://github.com/openai/codex/issues/16732)） | `tool.before`, `session.start` |\n| Aider | `aider` | PATH + pip 安装路径 | 无（通过 `ingest-aider` 只读摄入） | `tool.before`（从聊天历史解析） |\n\n## 快速开始\n\n```bash\n# 构建\ngo build -o oma.exe .\n\n# 检查检测到的代理\noma doctor\n\n# 为所有检测到的代理安装审计 hook\noma audit install\n\n# 生成默认策略\noma policy init\n```\n\n## 命令\n\n### `oma doctor`\n自检诊断：代理检测、hook 配置状态、审计目录、策略文件。\n\n```\n$ oma doctor\n--- Agent Detection ---\n  [claude] Claude Code v2.1.169\n        Path: /usr/local/bin/claude.cmd\n        Hooks: ~/.claude/settings.json (exists)\n  [opencode] OpenCode v1.17.13\n        Path: %LOCALAPPDATA%\\Programs\\@opencode-aidesktop\\OpenCode.exe\n        Hooks: ~/.config/opencode/hook/hooks.yaml (exists)\n  [codex] Codex CLI v0.130.0-alpha.5\n        Path: %LOCALAPPDATA%\\OpenAI\\Codex\\bin\\codex.exe\n        ⚠  bash-only hooks (#16732)\n        Hooks: ~/.codex/config.toml (exists)\n```\n\n### `oma audit`\n\n```bash\n# 安装 hook shim 到检测到的代理（写入 settings.json、config.toml、hooks.yaml）\noma audit install [--agents claude,opencode]\n\n# 移除 hook\noma audit uninstall [--agents claude,opencode]\n\n# 查看最近的审计日志\noma audit log [-n 20] [--agent claude] [--since 24h]\n\n# 用正则搜索审计日志\noma audit grep <pattern>\n\n# 重放会话时间线\noma audit replay <session-id>\n\n# 将 aider 聊天历史摄入审计日志\noma audit ingest-aider [--history ~/.aider.chat.history.md]\n```\n\n### `oma policy`\n\n```bash\n# 生成 ~/.oma/policy.yaml（含默认规则）\noma policy init\n\n# 检查事件（由 hook shim 调用；退出码 0 = 允许，2 = 拦截）\necho '<json>' | oma policy check <agent> <event>\n\n# 安装拦截 hook（替换只审计的 shim）\noma policy install [--agents claude,opencode]\n```\n\n#### 默认策略\n\n```yaml\ndeny:\n  - tool: bash\n    pattern: \"rm -rf\"\n    reason: \"deny rm -rf\"\n  - tool: bash\n    pattern: \"git push --force\"\n    reason: \"deny force push\"\nask:\n  - tool: edit\n    glob: \"**/.env*\"\n    reason: \"ask before editing .env files\"\n  - tool: write\n    glob: \"**/.env*\"\n    reason: \"ask before writing .env files\"\n```\n\n### `oma context`\n\n在每次会话启动时注入近期审计活动的 Markdown 摘要，让每个代理知道其他代理做了什么。\n\n```bash\n# 生成摘要（默认：最近 24 小时）\noma context brief [--cwd DIR] [--since 24h]\n\n# 安装 SessionStart 上下文 hook\noma context install [--agents claude,opencode]\n\n# 移除上下文 hook\noma context uninstall [--agents claude,opencode]\n```\n\n### `oma mcp`\n\n通过[模型上下文协议](https://modelcontextprotocol.io)向代理暴露审计和策略工具。\n\n```bash\n# 启动 MCP 服务器（stdio JSON-RPC）\noma mcp serve\n\n# 安装为代理的 MCP 服务器\noma mcp install [--agents claude,opencode]\n\n# 移除 MCP 配置\noma mcp uninstall\n```\n\n#### MCP 工具\n\n| 工具 | 描述 |\n|------|-------------|\n| `oma_audit_recent` | 最近的审计事件，支持按代理/时间筛选 |\n| `oma_audit_search` | 跨审计日志的正则搜索 |\n| `oma_who_changed` | 查找哪个代理最后修改了某个文件 |\n| `oma_policy_status` | 当前策略规则和最近拦截记录 |\n| `oma_handoff` | 跨代理的会话交接摘要 |\n\n### `oma hook`（内部）\n\n由代理 hook shim 调用。将 hook 事件通过管道送入审计日志。\n\n```bash\necho '<json>' | oma hook ingest claude tool.before\n```\n\n## 架构\n\n```\n                    ┌─────────────────────┐\n                    │   Claude / Gemini    │\n                    │   OpenCode / Codex   │\n                    │          ⋮           │\n                    └──────┬──────┬───────┘\n                           │      │\n              PreToolUse   │      │ PostToolUse\n              SessionStart │      │\n                           ▼      ▼\n                    ┌──────────────────┐\n                    │   oma shim (.ps1) │\n                    │   pipe via stdin  │\n                    └────────┬─────────┘\n                             │\n                    ┌────────▼─────────┐\n                    │   oma ingest     │\n                    │   decode → audit │\n                    └────────┬─────────┘\n                             │\n              ┌──────────────┼──────────────┐\n              ▼              ▼              ▼\n      ┌────────────┐ ┌────────────┐ ┌────────────┐\n      │ audit log  │ │ policy     │ │ mcp serve   │\n      │ ~/.oma/    │ │ check/     │ │ (5 tools)   │\n      │ audit/*    │ │ block      │ │             │\n      └────────────┘ └────────────┘ └────────────┘\n```\n\n所有事件流经 **decoder** 层（按代理规范化），然后到 **sink**（追加式 JSONL），可选的 **policy** 检查可以设置 `blocked` 标记并以退出码 2 退出。\n\n## 配置\n\n### 策略文件：`~/.oma/policy.yaml`\n\n```yaml\ndeny:\n  - tool: bash\n    pattern: \"rm -rf\"\n    reason: \"deny rm -rf\"\nask:\n  - tool: edit\n    glob: \"**/.env*\"\n    reason: \"ask before editing .env files\"\n```\n\n### 代理 Hook 配置文件\n\n| 代理 | 配置文件 | 格式 |\n|-------|-------------|--------|\n| Claude Code | `~/.claude/settings.json` | JSON |\n| OpenCode | `~/.config/opencode/hook/hooks.yaml` | YAML |\n| Codex CLI | `~/.codex/config.toml` | TOML |\n| Gemini CLI | `~/.gemini/settings.json` | JSON |\n\n### 审计日志：`~/.oma/audit/YYYY-MM-DD.jsonl`\n\n```\n{\"ts\":\"2026-07-03T14:54:54Z\",\"agent\":\"claude\",\"event\":\"tool.before\",\"session_id\":\"...\",\"tool\":{\"name\":\"Bash\",\"input\":{\"command\":\"ls -la\"},\"blocked\":false}}\n{\"ts\":\"2026-07-03T14:54:54Z\",\"agent\":\"claude\",\"event\":\"tool.before\",\"session_id\":\"...\",\"tool\":{\"name\":\"Bash\",\"input\":{\"command\":\"rm -rf /\"},\"blocked\":true,\"reason\":\"deny rm -rf\"}}\n```\n\n## 零外部依赖\n\n完全基于 **Go 标准库**构建——无需 `go mod download`，没有依赖膨胀，没有供应链风险。`go build` 即可编译为单个二进制文件。\n\n| 组件 | 说明 |\n|-----------|---------------|\n| `internal/cli/cli.go` | 命令行路由器——子命令分发、帮助输出 |\n| `internal/mcp/` | MCP 服务器——基于 stdio 的 JSON-RPC 协议实现 |\n| `internal/yaml/` | YAML 子集解析器——读取策略文件和 opencode hook 配置 |\n| `internal/toml/` | TOML 子集解析器 + 序列化器——读写 codex 配置 |\n\n## 代理检测\n\n`oma` 按以下顺序检测代理：\n\n1. **PATH 查找** — 通过 `exec.LookPath`\n2. **回退路径** — 来自 `catalog.json`（用户可配置）\n3. **标准平台路径** — 内置的按代理搜索已知安装位置（npm 全局前缀、`%LOCALAPPDATA%`、`~/.codex/.sandbox-bin` 等）\n\n## 已知局限\n\n- **Codex CLI**：hook 支持仅限于 bash 命令（[#16732](https://github.com/openai/codex/issues/16732)）。`apply_patch` 和 `edit` 等工具不会被 hook 捕获——除非通过受监控的工具调用，否则对 `oma` 不可见。\n- **Aider**：没有 hook 系统。唯一的集成方式是事后通过 `oma audit ingest-aider` 摄入 `~/.aider.chat.history.md`，可提供历史可见性但无法实时拦截（aider 不支持策略阻断）。\n","readmeFilename":"README.zh.md","_rev":"1-a19810b796615e2f19fc67339da776f9"}