Content
# oh-my-agent (oma)
> [中文版](README.zh.md)
Cross-agent governance layer for AI coding agents. Unified audit logging, policy enforcement, and context feedback across Claude Code, Gemini CLI, OpenCode, Codex CLI, and Aider.
---
## For Humans
After publishing to npm, copy and paste this to your AI coding agent:
```
npm install -g oh-my-agent && oma audit install && oma policy init && oma doctor
```
If npm is not available, clone from GitHub and build:
```
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
```
## For AI Agents
> If you are an AI coding agent reading this file, here is what you need to know.
- **Audit**: Every tool call you make is recorded to `~/.oma/audit/`. This log is shared across all agents — other agents can see what you did.
- **Policy**: Some commands may be blocked by policy rules. If `rm -rf /` is denied, that is oma's policy enforcement. Do not retry blocked commands.
- **Context brief**: At session start, your hook may inject a markdown summary of recent activity from other agents. Read it to understand what has already been done.
- **MCP tools**: When `oma mcp serve` is running, you can query `oma_audit_recent`, `oma_audit_search`, `oma_who_changed`, `oma_policy_status`, and `oma_handoff` to learn about other agents' work.
## Features
- **Unified Audit** — all tool calls from every agent record to `~/.oma/audit/YYYY-MM-DD.jsonl`
- **Policy Enforcement** — deny/ask rules block dangerous commands (`rm -rf`, `git push --force`, etc.) across every agent
- **Context Feedback** — injects recent activity summary into session starts, so each agent knows what others have done
- **MCP Integration** — expose audit & policy tools via MCP so agents can query each other's activity
- **Aider Ingestion** — parse `~/.aider.chat.history.md` into the unified audit log (aider has no native hooks)
- **Zero Dependencies** — built with Go stdlib only, no `go mod download`, no supply chain risk
## Supported Agents
| Agent | Binary | Detection | Hooks | Event Types |
|-------|--------|-----------|-------|-------------|
| Claude Code | `claude` | PATH + standard install paths | PreToolUse, PostToolUse, SessionStart, UserPromptSubmit, PermissionRequest | `tool.before`, `tool.after`, `session.start`, `prompt.user` |
| Gemini CLI | `gemini` | PATH + standard install paths | BeforeTool, AfterTool, SessionStart, UserPromptSubmit | `tool.before`, `tool.after`, `session.start` |
| OpenCode | `opencode` | PATH + npm global + desktop app | PreToolUse, PostToolUse, `session.start` | `tool.before`, `tool.after` |
| Codex CLI | `codex` | PATH + official installer path | PreToolUse, SessionStart (bash-only, [#16732](https://github.com/openai/codex/issues/16732)) | `tool.before`, `session.start` |
| Aider | `aider` | PATH + pip install paths | None (read-only via `ingest-aider`) | `tool.before` (parsed from chat history) |
## Quick Start
```bash
# Build
go build -o oma.exe .
# Check what's detected
oma doctor
# Install audit hooks for all detected agents
oma audit install
# Generate default policy
oma policy init
```
## Commands
### `oma doctor`
Self-diagnostics: agent detection, hook config status, audit directory, and policy file.
```
$ 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`
```bash
# Install hook shims into detected agents (writes settings.json, config.toml, hooks.yaml)
oma audit install [--agents claude,opencode]
# Remove hooks
oma audit uninstall [--agents claude,opencode]
# View recent audit log
oma audit log [-n 20] [--agent claude] [--since 24h]
# Search audit log with regex
oma audit grep <pattern>
# Replay a session timeline
oma audit replay <session-id>
# Ingest aider chat history into audit log
oma audit ingest-aider [--history ~/.aider.chat.history.md]
```
### `oma policy`
```bash
# Generate ~/.oma/policy.yaml with defaults
oma policy init
# Check an event (called by hook shims; exit 0 = allow, 2 = block)
echo '<json>' | oma policy check <agent> <event>
# Install blocking hooks (replaces audit-only shims)
oma policy install [--agents claude,opencode]
```
#### Default Policy
```yaml
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`
Injects a markdown summary of recent audit activity into each agent's session start hook, so every agent knows what others have been doing.
```bash
# Generate a brief (default: last 24h)
oma context brief [--cwd DIR] [--since 24h]
# Install SessionStart context hooks
oma context install [--agents claude,opencode]
# Remove context hooks
oma context uninstall [--agents claude,opencode]
```
### `oma mcp`
Exposes audit and policy to agents via the [Model Context Protocol](https://modelcontextprotocol.io).
```bash
# Start MCP server (stdio JSON-RPC)
oma mcp serve
# Install as agent MCP server
oma mcp install [--agents claude,opencode]
# Remove MCP config
oma mcp uninstall
```
#### MCP Tools
| Tool | Description |
|------|-------------|
| `oma_audit_recent` | Recent audit events, optional agent/time filter |
| `oma_audit_search` | Regex search across audit logs |
| `oma_who_changed` | Find which agent last touched a file |
| `oma_policy_status` | Current policy rules and recent blocks |
| `oma_handoff` | Cross-agent handoff summary for a session |
### `oma hook` (internal)
Called by agent hook shims. Pipes hook events into the audit log.
```bash
echo '<json>' | oma hook ingest claude tool.before
```
## Architecture
```
┌─────────────────────┐
│ 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 │ │ │
└────────────┘ └────────────┘ └────────────┘
```
All events flow through the **decoder** layer (per-agent normalization), then to **sink** (append-only JSONL), with optional **policy** check that can set the `blocked` flag and exit 2.
## Configuration
### Policy: `~/.oma/policy.yaml`
```yaml
deny:
- tool: bash
pattern: "rm -rf"
reason: "deny rm -rf"
ask:
- tool: edit
glob: "**/.env*"
reason: "ask before editing .env files"
```
### Agent Hook Files
| Agent | Config File | Format |
|-------|-------------|--------|
| 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 |
### Audit Log: `~/.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"}}
```
## Zero Dependencies
Built entirely with **Go's standard library** — no `go mod download`, no dependency bloat, no supply chain risk. Single-binary build with `go build` just works.
| Component | What it does |
|-----------|---------------|
| `internal/cli/cli.go` | Command-line router — subcommand dispatch, help output |
| `internal/mcp/` | MCP server — stdio JSON-RPC protocol implementation |
| `internal/yaml/` | YAML subset parser — reads policy files and opencode hooks config |
| `internal/toml/` | TOML subset parser + serializer — reads/writes codex config |
## Agent Detection
`oma` detects agents by:
1. **PATH lookup** via `exec.LookPath`
2. **Fallback paths** from `catalog.json` (user-configurable)
3. **Standard platform paths** — built-in per-agent search of well-known installation locations (npm global prefix, `%LOCALAPPDATA%`, `~/.codex/.sandbox-bin`, etc.)
## Limitations
- **Codex CLI**: hook support limited to bash commands only ([#16732](https://github.com/openai/codex/issues/16732)). Tools like `apply_patch` and `edit` are not captured by hooks — they remain invisible to `oma` unless you also pipe their invocation through a monitored tool.
- **Aider**: has no hook system. The only integration path is post-hoc ingestion of `~/.aider.chat.history.md` via `oma audit ingest-aider`, which provides historical visibility but not real-time intercept (no policy blocking for aider).
