oh-my-agent (oma)

English

AI 编程代理的跨代理治理层。为 Claude Code、Gemini CLI、OpenCode、Codex CLI 和 Aider 提供统一的审计日志、策略执行和上下文反馈注入。

给人类用户

发布到 npm 后，复制以下指令给你的 AI 编程代理：

npm install -g oh-my-agent && oma audit install && oma policy init && oma doctor

如果没有 npm，可以从 GitHub 克隆并构建：

git 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

给 AI 代理阅读

如果你是正在阅读本文的 AI 编程代理，请注意以下内容。

• 审计：你的每一次工具调用都会记录到 ~/.oma/audit/。这个日志是所有代理共享的——其他代理可以看到你做过什么。
• 策略：部分命令可能会被策略规则拦截。如果 rm -rf / 被拒绝，那是 oma 的策略执行在起作用。不要重试被拦截的命令。
• 上下文摘要：会话启动时，hook 可能会注入一段 Markdown 摘要，展示其他代理近期的活动。阅读它来了解已经完成的工作。
• MCP 工具：当 oma mcp serve 运行时，你可以查询 oma_audit_recent、oma_audit_search、oma_who_changed、oma_policy_status 和 oma_handoff 来了解其他代理的工作。

功能

• 统一审计 — 所有代理的工具调用统一记录到 ~/.oma/audit/YYYY-MM-DD.jsonl
• 策略执行 — deny/ask 规则跨所有代理拦截危险命令（rm -rf、git push --force 等）
• 上下文反馈 — 在会话启动时注入近期活动摘要，让每个代理知道其他代理做了什么
• MCP 集成 — 通过 MCP 暴露审计和策略工具，代理之间可以互相查询活动
• Aider 摄入 — 解析 ~/.aider.chat.history.md 到统一审计日志（aider 没有原生 hook）
• 零外部依赖 — 完全基于 Go 标准库，无需 go mod download，无供应链风险

支持的代理

| 代理 | 二进制 | 检测方式 | Hook | 事件类型 | |-------|--------|-----------|-------|-------------| | Claude Code | claude | PATH + 标准安装路径 | PreToolUse, PostToolUse, SessionStart, UserPromptSubmit, PermissionRequest | tool.before, tool.after, session.start, prompt.user | | Gemini CLI | gemini | PATH + 标准安装路径 | BeforeTool, AfterTool, SessionStart, UserPromptSubmit | tool.before, tool.after, session.start | | OpenCode | opencode | PATH + npm 全局 + 桌面应用 | PreToolUse, PostToolUse, session.start | tool.before, tool.after | | Codex CLI | codex | PATH + 官方安装路径 | PreToolUse, SessionStart（仅 bash，#16732） | tool.before, session.start | | Aider | aider | PATH + pip 安装路径 | 无（通过 ingest-aider 只读摄入） | tool.before（从聊天历史解析） |

快速开始

# 构建
go build -o oma.exe .

# 检查检测到的代理
oma doctor

# 为所有检测到的代理安装审计 hook
oma audit install

# 生成默认策略
oma policy init

命令

oma doctor

自检诊断：代理检测、hook 配置状态、审计目录、策略文件。

$ oma doctor
--- Agent Detection ---
  [claude] Claude Code v2.1.169
        Path: /usr/local/bin/claude.cmd
        Hooks: ~/.claude/settings.json (exists)
  [opencode] OpenCode v1.17.13
        Path: %LOCALAPPDATA%\Programs\@opencode-aidesktop\OpenCode.exe
        Hooks: ~/.config/opencode/hook/hooks.yaml (exists)
  [codex] Codex CLI v0.130.0-alpha.5
        Path: %LOCALAPPDATA%\OpenAI\Codex\bin\codex.exe
        ⚠  bash-only hooks (#16732)
        Hooks: ~/.codex/config.toml (exists)

oma audit

# 安装 hook shim 到检测到的代理（写入 settings.json、config.toml、hooks.yaml）
oma audit install [--agents claude,opencode]

# 移除 hook
oma audit uninstall [--agents claude,opencode]

# 查看最近的审计日志
oma audit log [-n 20] [--agent claude] [--since 24h]

# 用正则搜索审计日志
oma audit grep <pattern>

# 重放会话时间线
oma audit replay <session-id>

# 将 aider 聊天历史摄入审计日志
oma audit ingest-aider [--history ~/.aider.chat.history.md]

oma policy

# 生成 ~/.oma/policy.yaml（含默认规则）
oma policy init

# 检查事件（由 hook shim 调用；退出码 0 = 允许，2 = 拦截）
echo '<json>' | oma policy check <agent> <event>

# 安装拦截 hook（替换只审计的 shim）
oma policy install [--agents claude,opencode]

默认策略

deny:
  - tool: bash
    pattern: "rm -rf"
    reason: "deny rm -rf"
  - tool: bash
    pattern: "git push --force"
    reason: "deny force push"
ask:
  - tool: edit
    glob: "**/.env*"
    reason: "ask before editing .env files"
  - tool: write
    glob: "**/.env*"
    reason: "ask before writing .env files"

oma context

在每次会话启动时注入近期审计活动的 Markdown 摘要，让每个代理知道其他代理做了什么。

# 生成摘要（默认：最近 24 小时）
oma context brief [--cwd DIR] [--since 24h]

# 安装 SessionStart 上下文 hook
oma context install [--agents claude,opencode]

# 移除上下文 hook
oma context uninstall [--agents claude,opencode]

oma mcp

通过模型上下文协议向代理暴露审计和策略工具。

# 启动 MCP 服务器（stdio JSON-RPC）
oma mcp serve

# 安装为代理的 MCP 服务器
oma mcp install [--agents claude,opencode]

# 移除 MCP 配置
oma mcp uninstall

MCP 工具

| 工具 | 描述 | |------|-------------| | oma_audit_recent | 最近的审计事件，支持按代理/时间筛选 | | oma_audit_search | 跨审计日志的正则搜索 | | oma_who_changed | 查找哪个代理最后修改了某个文件 | | oma_policy_status | 当前策略规则和最近拦截记录 | | oma_handoff | 跨代理的会话交接摘要 |

oma hook（内部）

由代理 hook shim 调用。将 hook 事件通过管道送入审计日志。

echo '<json>' | oma hook ingest claude tool.before

架构

                    ┌─────────────────────┐
                    │   Claude / Gemini    │
                    │   OpenCode / Codex   │
                    │          ⋮           │
                    └──────┬──────┬───────┘
                           │      │
              PreToolUse   │      │ PostToolUse
              SessionStart │      │
                           ▼      ▼
                    ┌──────────────────┐
                    │   oma shim (.ps1) │
                    │   pipe via stdin  │
                    └────────┬─────────┘
                             │
                    ┌────────▼─────────┐
                    │   oma ingest     │
                    │   decode → audit │
                    └────────┬─────────┘
                             │
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
      ┌────────────┐ ┌────────────┐ ┌────────────┐
      │ audit log  │ │ policy     │ │ mcp serve   │
      │ ~/.oma/    │ │ check/     │ │ (5 tools)   │
      │ audit/*    │ │ block      │ │             │
      └────────────┘ └────────────┘ └────────────┘

所有事件流经 decoder 层（按代理规范化），然后到 sink（追加式 JSONL），可选的 policy 检查可以设置 blocked 标记并以退出码 2 退出。

配置

策略文件：~/.oma/policy.yaml

deny:
  - tool: bash
    pattern: "rm -rf"
    reason: "deny rm -rf"
ask:
  - tool: edit
    glob: "**/.env*"
    reason: "ask before editing .env files"

代理 Hook 配置文件

| 代理 | 配置文件 | 格式 | |-------|-------------|--------| | Claude Code | ~/.claude/settings.json | JSON | | OpenCode | ~/.config/opencode/hook/hooks.yaml | YAML | | Codex CLI | ~/.codex/config.toml | TOML | | Gemini CLI | ~/.gemini/settings.json | JSON |

审计日志：~/.oma/audit/YYYY-MM-DD.jsonl

{"ts":"2026-07-03T14:54:54Z","agent":"claude","event":"tool.before","session_id":"...","tool":{"name":"Bash","input":{"command":"ls -la"},"blocked":false}}
{"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"}}

零外部依赖

完全基于 Go 标准库构建——无需 go mod download，没有依赖膨胀，没有供应链风险。go build 即可编译为单个二进制文件。

| 组件 | 说明 | |-----------|---------------| | internal/cli/cli.go | 命令行路由器——子命令分发、帮助输出 | | internal/mcp/ | MCP 服务器——基于 stdio 的 JSON-RPC 协议实现 | | internal/yaml/ | YAML 子集解析器——读取策略文件和 opencode hook 配置 | | internal/toml/ | TOML 子集解析器 + 序列化器——读写 codex 配置 |

代理检测

oma 按以下顺序检测代理：

1. PATH 查找 — 通过 exec.LookPath
2. 回退路径 — 来自 catalog.json（用户可配置）
3. 标准平台路径 — 内置的按代理搜索已知安装位置（npm 全局前缀、%LOCALAPPDATA%、~/.codex/.sandbox-bin 等）

已知局限

• Codex CLI：hook 支持仅限于 bash 命令（#16732）。apply_patch 和 edit 等工具不会被 hook 捕获——除非通过受监控的工具调用，否则对 oma 不可见。
• Aider：没有 hook 系统。唯一的集成方式是事后通过 oma audit ingest-aider 摄入 ~/.aider.chat.history.md，可提供历史可见性但无法实时拦截（aider 不支持策略阻断）。