{"id":51525677,"url":"https://github.com/hongphuc5497/agent-ops","last_synced_at":"2026-07-08T21:01:37.462Z","repository":{"id":358705963,"uuid":"1242689656","full_name":"hongphuc5497/agent-ops","owner":"hongphuc5497","description":"Integration-first operating protocol for AI coding agents — coordinate Codex, OpenCode, Augment, OpenClaw, Hermes through repo-native files","archived":false,"fork":false,"pushed_at":"2026-07-05T17:35:23.000Z","size":285,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-05T19:09:45.213Z","etag":null,"topics":["agent-ops","ai-coding-agents","augment","claude-code","codex","coordination","git-native","hermes","integration-first","openclaw","opencode","protocol"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hongphuc5497.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"docs/supported-integrations.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-18T16:55:59.000Z","updated_at":"2026-07-05T17:35:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hongphuc5497/agent-ops","commit_stats":null,"previous_names":["hongphuc5497/agent-ops"],"tags_count":10,"template":true,"template_full_name":null,"purl":"pkg:github/hongphuc5497/agent-ops","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hongphuc5497%2Fagent-ops","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hongphuc5497%2Fagent-ops/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hongphuc5497%2Fagent-ops/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hongphuc5497%2Fagent-ops/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hongphuc5497","download_url":"https://codeload.github.com/hongphuc5497/agent-ops/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hongphuc5497%2Fagent-ops/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35278166,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-08T02:00:06.796Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-ops","ai-coding-agents","augment","claude-code","codex","coordination","git-native","hermes","integration-first","openclaw","opencode","protocol"],"created_at":"2026-07-08T21:01:36.863Z","updated_at":"2026-07-08T21:01:37.448Z","avatar_url":"https://github.com/hongphuc5497.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agent Ops\n\nIntegration-first operating protocol for AI coding agents. Coordinate Codex,\nOpenCode, Augment, OpenClaw, Hermes, and future MCP tools through repo-native\nfiles. The default workflow is file-only; the optional kanban UI runs as a\nlocalhost-only server when you ask for it.\n\n[📖 Case Study: How I Stopped AI Agents From Fighting My Repo](docs/case-study.md)\n\n## 60-Second Start\n\n```bash\n# One command: install, pick your agents, learn the protocol via a guided task\nnpx @hongphuc5497/agent-ops@latest init --interactive\n```\n\nOr step by step:\n\n```bash\n# Optional: install globally so `agent-ops` / `ao` are on your PATH\nnpm install -g @hongphuc5497/agent-ops@latest\n\n# Seed into an existing repo (npx works without a global install too)\ncd /path/to/your-project\nnpx @hongphuc5497/agent-ops@latest init\n\n# Check it works\nagent-ops check\n\n# Drop a guided demo task to learn claim / delegate / finish\nagent-ops tutorial\n\n# Open the local task board\nagent-ops kanban\n\n# Teach Codex the protocol\nagent-ops install codex\n```\n\n### Coordinate two agents (the whole point)\n\n```bash\n# In your repo, once:\nnpx @hongphuc5497/agent-ops@latest init\nagent-ops hook install                 # blocks commits that touch another agent's claims\n\n# Wire each agent in natively over MCP (no CLI shelling needed):\nclaude mcp add agent-ops -- npx -y @hongphuc5497/agent-ops@latest mcp\n# codex: add to ~/.codex/config.toml —\n#   [mcp_servers.agent-ops]\n#   command = \"npx\"\n#   args = [\"-y\", \"@hongphuc5497/agent-ops@latest\", \"mcp\", \"--repo\", \"/abs/path/to/repo\"]\n\n# Give each agent an identity (per-process, so a shared checkout stays safe):\nAGENT_OPS_OWNER=claude claude    # or: git config agent-ops.owner \u003cname\u003e as human fallback\nAGENT_OPS_OWNER=codex codex\n```\n\nFrom there both agents see the same `status`, claim files as native tools,\nand the pre-commit hook enforces claims instead of trusting etiquette.\n\n**Why not git worktrees?** Worktrees isolate agents by copying the checkout —\nyou pay branch juggling, merge conflicts at the end, and lose the shared dev\nserver. Agent Ops keeps one checkout with visible ownership and blocked\nconflicting commits. See `.ai/DECISIONS.md` for the full rationale.\n\n## The Protocol\n\nEvery agent reads the same repo-native state before editing:\n\n```bash\nagent-ops status                              # Who owns the active task?\nagent-ops start \"fix auth bug\" --owner Codex # Lock a task\nagent-ops claim \"src/auth/**\"                # Claim files before editing\nagent-ops check                              # Verify protocol health\nagent-ops doctor                             # Diagnostics for bug reports\nagent-ops claim --release \"src/auth/**\"     # Crash recovery: drop stale claims\nagent-ops finish done --verification \"...\"   # Complete with evidence\nagent-ops hook install                       # Enforce claims at commit time\nagent-ops kanban --no-open                   # Open a command-backed board\n```\n\nHuman commands: `agent-ops help`, `agent-ops version`, `agent-ops tutorial`.\nAgents can also use the repo-local `./scripts/ao` wrapper after initialization —\nor skip the shell entirely and connect over MCP (`agent-ops mcp`).\n\n## What It Coordinates\n\n| Concern | File | Machine-Readable |\n|---------|------|:---:|\n| Active task owner | `.ai/state/active-task.json` | ✓ |\n| File ownership claims | `.ai/state/file-claims.json` | ✓ |\n| Agent handoffs | `.ai/state/handoffs.jsonl` | ✓ |\n| Task records | `.ai/tasks/*.md` + archive JSON | ✓ |\n| Routing rules | `.ai/ROUTING.md` | — |\n| Architecture decisions | `.ai/DECISIONS.md` | — |\n| Shared protocol | `.ai/protocol.md` | — |\n\n## Agent Integrations\n\nOne command teaches each agent the protocol:\n\n```bash\nagent-ops install list        # Show supported integrations\nagent-ops install codex       # Appends to AGENTS.md\nagent-ops install opencode    # Appends to instructions.md\nagent-ops install augment     # Appends discovery guide\nagent-ops install openclaw    # Appends review rules\nagent-ops install hermes      # Appends monitor rules\n```\n\nRepo-local only — no global config mutated.\n\nInstall support is different from live coordination. The install script writes\nthe files an agent reads; `.ai/ROUTING.md`, `.ai/TASK.md`, and `ao` define what that\nagent may do once work starts. See the [supported integrations matrix](docs/supported-integrations.md).\n\n## Kanban UI\n\n```bash\nagent-ops kanban\nagent-ops kanban --no-open\nagent-ops kanban --port 4783\n```\n\nThe board reads the same protocol files as the CLI and writes only through\nAgent Ops commands. It can create backlog or active tasks, update task metadata,\nclaim files for the active task, and finish or park the active task. V1 is\nintentionally local-only and does not include drag-and-drop; Agent Ops still\nallows exactly one active owner at a time.\n\nThe server binds `127.0.0.1`, rejects non-loopback `Host` headers, and (since\n0.2.0) requires a per-process CSRF token on every mutating request — a\ndrive-by POST from any other page the user has open is rejected even on\nloopback.\n\n## Reliability\n\nSince 0.2.0, every state mutation is safe for concurrent agents:\n\n- **State locking** — `claim`, `start`, `finish`, `handoff`, `delegate` all\n  hold an exclusive POSIX advisory lock. Two agents racing the same path\n  produce exactly one winner; the other gets a structured `claim conflict`.\n  Where locking is unavailable (Windows), mutations are refused with a clear\n  error instead of silently racing — `AGENT_OPS_UNSAFE_NO_LOCK=1` overrides\n  for single-agent use; read-only commands always work.\n- **Crash recovery** — a crashed agent's claims are surfaced by\n  `agent-ops doctor` (stale + orphan detection) and dropped with\n  `agent-ops claim --release \u003cpaths\u003e`; releasing another agent's claims\n  requires `--force --reason` and is audited to the handoff log.\n- **Enforcement** — `agent-ops hook install` adds a pre-commit hook that\n  blocks commits touching files claimed by a different agent, turning claims\n  from etiquette into a guarantee. Identity comes from `AGENT_OPS_OWNER`\n  (per-process) or `git config agent-ops.owner` (human fallback).\n- **Atomic writes** — `.ai/state/*.json` is written via temp file + `fsync`\n  + `os.replace`. A crash mid-write cannot leave a half-written claim.\n- **Structural validation** — corrupt state files surface a typed `problems`\n  list with a `remedy` hint instead of a stack trace.\n- **`agent-ops doctor`** — paste-it-into-a-bug-report diagnostic.\n\n## CI \u0026 Notifications\n\nGitHub Actions workflows run on every PR and daily:\n\n| Workflow | Trigger | Failure Alert |\n|----------|---------|:---:|\n| `agent-ops-check.yml` | PR, push to main | Telegram |\n| `stale-task-monitor.yml` | Daily 9AM UTC | Telegram |\n\nSet `TELEGRAM_BOT_TOKEN` + `TELEGRAM_CHAT_ID` secrets for notifications.\nSlack via `SLACK_WEBHOOK_URL` (optional).\n\n## What This Isn't\n\n- ❌ Not a hosted service or cloud dashboard\n- ❌ Not an agent framework or orchestration runtime\n- ❌ No package dependencies beyond Node, Python 3, and bash — the MCP\n  server is hand-rolled stdio JSON-RPC, zero runtime deps\n\n## Dogfooded On\n\n| Repo | Stack | Status |\n|------|-------|--------|\n| `personal-landing-page` | Next.js 16 / TS / Vercel | ✓ Active |\n| `github-digest` | Python / Playwright | ✓ Active |\n| `AutoCreateVideo` | Node / TypeScript / Vitest | ✓ Active |\n| `vite-virtual-cafe` | Remix / Vite / Playwright | ✓ Active |\n| `skills` | Markdown / shell / Python validators | ✓ Active |\n| `zsh-dotfiles` | Shell / dotfiles | ✓ Active |\n| `vibe-coding-learning` | Static learning repo | ✓ Active |\n| `prompt-enhancer` | Python / stdlib CLI | ✓ Active |\n| `MiroFish` | Flask / Python + Node frontend | ✓ Active |\n| `obsidian-wiki` | Markdown / Python scripts | ✓ Active |\n| `TradingAgents` | Python / finance analysis | ✓ Active |\n\n[Read the full dogfooding log](.ai/memory/phase3-dogfooding-log.md)\n\n## Verify\n\n```bash\nagent-ops check\n```\n\n## Milestones\n\n[GitHub Milestones](https://github.com/hongphuc5497/agent-ops/milestones) · [CHANGELOG](CHANGELOG.md)\n\n1. ✓ MVP — Agent Integration Protocol\n2. ✓ Consolidate \u0026 Self-Bootstrap\n3. ✓ Dogfood \u0026 Document\n4. ✓ Package \u0026 Distribute (v0.1.0)\n5. ✓ Reliability hardening — locking, atomic writes, CSRF, doctor (v0.2.0)\n6. ✓ Onboarding velocity — interactive init, tutorial, reads/writes matrix (v0.3.0)\n7. ✓ Smarter routing — per-repo `.ai/routing.json` overrides (v0.4.0) — see [docs/routing.md](docs/routing.md)\n8. ✓ Consolidated layout — `TASK.md` / `ROUTING.md` / `DECISIONS.md` and `integrations/` moved into `.ai/`; `agent-ops upgrade` auto-migrates (v0.5.0)\n9. ✓ Adoption release — MCP server, pre-commit claim enforcement, crash recovery, honest cross-platform locking (v0.6.0)\n\n## Demo\n\nTwo agents, one repo, no stepped-on toes — in five commands:\n\n```bash\ncd ~/my-project\nnpx @hongphuc5497/agent-ops@latest init                              # install protocol files\nagent-ops hook install                                               # claims now block conflicting commits\nclaude mcp add agent-ops -- npx -y @hongphuc5497/agent-ops@latest mcp   # Claude gets native tools\nAGENT_OPS_OWNER=claude claude                                        # terminal 1: Claude, with identity\nAGENT_OPS_OWNER=codex codex                                          # terminal 2: Codex, with identity\n```\n\nWhat happens next, with zero extra ceremony:\n\n```bash\n# Claude (via MCP tools, no shell needed):\n#   start \"add dark mode\" → claim \"src/theme/*\"\n\n# Codex tries to edit the same files:\n$ git commit -m \"tweak theme\"\n# ✗ blocked: src/theme/tokens.ts is claimed by claude\n#   (task: add dark mode — ask the owner, `claim --release` if stale,\n#    or AGENT_OPS_SKIP_HOOK=1 to bypass once)\n\n# Claude's session crashes mid-task? Recover in two commands:\nagent-ops doctor                              # → flags the orphaned claims\nagent-ops claim --release \"src/theme/*\"       # → Codex can proceed\n\n# Finish with evidence — the archive keeps the audit trail:\nagent-ops finish done --verification \"npm test\"\n```\n\nPrefer the guided path? `npx @hongphuc5497/agent-ops@latest init --interactive`\npicks your agents and seeds a tutorial task; `agent-ops kanban` shows the\nboard. CI catches stale tasks daily, Telegram on failure.\n\n[Full Setup Guide](docs/SETUP.md) · [Plug-and-Play Guide](docs/plug-and-play.md) · [Supported Integrations](docs/supported-integrations.md) · [Case Study](docs/case-study.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhongphuc5497%2Fagent-ops","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhongphuc5497%2Fagent-ops","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhongphuc5497%2Fagent-ops/lists"}