Skip to content
Back to search

agent-hub

Sync global instructions, skills, and MCP server configs across Claude Code, Codex, and Antigravity/Gemini from one canonical hub directory.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/flyingrobots--agent-hub/badge.svg)](/listings/flyingrobots--agent-hub)

HTML

<a href="/listings/flyingrobots--agent-hub"><img src="/api/listings/flyingrobots--agent-hub/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/flyingrobots/agent-hub.git
cd agent-hub
./install.sh
export PATH="$HOME/.local/bin:$PATH"   # add to ~/.zshrc or ~/.bashrc

What `./install.sh` does (and does **not** do): - Copies the runtime into `~/.agent-hub/` with an `.agent-hub-runtime` marker and symlinks `~/.local/bin/sync-agents`. - **Never supplies global `--force`**. If `~/.agents/skills/agent-hub` already exists and differs from the bundled copy, it is **preserved** and a conflict is reported. Pass `./install.sh --force-skill` to replace *only* the bundled `agent-hub` skill (never authorizing MCP or symlink replacement), or `--no-skill` / `--no-sync` to skip skill installation or target sync. - **Prefix & shim guards**: Refuses to replace `/`, `$HOME`, any prefix overlapping your hub directory, any populated `--prefix` lacking a valid `.agent-hub-runtime` marker (or verified baseline checksums), or an unrecognized file at `~/.local/bin/sync-agents` unless explicitly overridden (`--replace-runtime`, which moves the previous prefix aside as a backup, or `--replace-bin`).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 192 lines
  1. # agent-hub
  2. Maintain global instructions (`AGENTS.md`), skills (`skills/`), and MCP server definitions (`mcp/`) in **one canonical directory** (default `~/.agents/`) and project them predictably into each local AI coding agent's configuration.
  3. Keep your personal `~/.agents/` directory in its own private git repo while installing the `agent-hub` runtime cleanly into `~/.agent-hub/` (decoupled from your source checkout) and storing machine-local ownership state under XDG state (`~/.local/state/agent-hub/`).
  4. ---
  5. ## Supported Targets & Status
  6. | Target | Rules | Skills | MCP Config | Notes |
  7. | --- | --- | --- | --- | --- |
  8. | **Claude Code** | `~/.claude/CLAUDE.md` | `~/.claude/skills/<name>` | `~/.claude.json` (`mcpServers`) | Supports `stdio`, `http` (streamable HTTP), `sse` |
  9. | **Codex** | `~/.codex/AGENTS.md` | `~/.codex/skills/<name>` | `~/.codex/config.toml` (`[mcp_servers.*]`) | Supports `stdio`, `http` (streamable HTTP); rejects active `sse` |
  10. | **Antigravity** | `~/.gemini/GEMINI.md`, `~/.gemini/config/AGENTS.md` | `~/.gemini/skills/<name>` | `~/.gemini/config/mcp_config.json` (`mcpServers`) | Override key: `antigravity`. Supports `stdio`, `http` (`serverUrl`); rejects active `sse` |
  11. | **OpenCode** | `~/.config/opencode/AGENTS.md` | `~/.config/opencode/skills/<name>` | — | Rules + per-skill symlinks only |
  12. | **Cursor** | `~/.cursor/AGENTS.md` *(unverified / experimental)* | `~/.cursor/skills/<name>` | — | Cursor docs describe project `AGENTS.md` and settings-based User Rules; global `~/.cursor/AGENTS.md` effect is unverified |
  13. | **Gemini CLI** | — | — | **Not supported** | Gemini CLI uses `~/.gemini/settings.json` (`url` = SSE, `httpUrl` = streamable HTTP) and is not currently targeted |
  14. > **Important:** Structural synchronization verifies filesystem links, serialized JSON/TOML, and ownership state — it does not prove that a downstream agent application loaded and honored the configuration at runtime.
  15. ---
  16. ## Prerequisites & First-Use Setup
  17. ### Prerequisites
  18. - **Bun** (required upfront for `sync-agents`; tested on Bun `1.4.2`; `--help` and `--print-dir` work without Bun)
  19. - **Git**, **`unzip`**, **`tar`** (required when installing skills from git URLs, `.bundle`, `.zip`/`.skill`, or tarballs)
  20. - Supported platforms: **macOS** and **Linux** (uses OS advisory `flock(2)` for cooperating writer exclusion)
  21. ### 1. Create your canonical hub (first time)
  22. ```bash
  23. mkdir -p ~/.agents/skills ~/.agents/mcp
  24. printf '# Global Agent Instructions\n' > ~/.agents/AGENTS.md
  25. ```
  26. ### 2. Install the `agent-hub` runtime
  27. ```bash
  28. git clone https://github.com/flyingrobots/agent-hub.git
  29. cd agent-hub
  30. ./install.sh
  31. export PATH="$HOME/.local/bin:$PATH" # add to ~/.zshrc or ~/.bashrc
  32. ```
  33. What `./install.sh` does (and does **not** do):
  34. - Copies the runtime into `~/.agent-hub/` with an `.agent-hub-runtime` marker and symlinks `~/.local/bin/sync-agents`.
  35. - **Never supplies global `--force`**. If `~/.agents/skills/agent-hub` already exists and differs from the bundled copy, it is **preserved** and a conflict is reported. Pass `./install.sh --force-skill` to replace *only* the bundled `agent-hub` skill (never authorizing MCP or symlink replacement), or `--no-skill` / `--no-sync` to skip skill installation or target sync.
  36. - **Prefix & shim guards**: Refuses to replace `/`, `$HOME`, any prefix overlapping your hub directory, any populated `--prefix` lacking a valid `.agent-hub-runtime` marker (or verified baseline checksums), or an unrecognized file at `~/.local/bin/sync-agents` unless explicitly overridden (`--replace-runtime`, which moves the previous prefix aside as a backup, or `--replace-bin`).
  37. ### 3. Configure your hub directory
  38. `sync-agents` resolves and canonicalizes the hub path to a real absolute path in precedence order:
  39. 1. `--dir <path>` CLI flag
  40. 2. `$AGENTS_DIR` environment variable
  41. 3. `${XDG_CONFIG_HOME:-$HOME/.config}/agent-hub/config.json` (`"agentsDir"`)
  42. 4. Default: `~/.agents`
  43. ---
  44. ## Canonical Hub Layout
  45. ```text
  46. ~/.agents/ # Your personal config (private git repo; no machine state stored here)
  47. ├── AGENTS.md # Shared global instructions
  48. ├── skills/
  49. │ └── <skill-name>/
  50. │ └── SKILL.md # Plus optional references/, scripts/, assets
  51. └── mcp/
  52. └── <server-name>/
  53. ├── mcp.json # Canonical MCP server spec (+ optional inline overrides)
  54. └── <agent>/mcp.json # Optional per-agent override (antigravity | claude | codex)
  55. ```
  56. ### Canonical `mcp.json` Format & Transport Semantics
  57. ```json
  58. {
  59. "mcp": {
  60. "transport": "stdio",
  61. "command": "/opt/homebrew/bin/shadcn",
  62. "args": ["mcp"]
  63. },
  64. "overrides": {
  65. "codex": {
  66. "env": { "MODE": "codex" }
  67. }
  68. }
  69. }
  70. ```
  71. Remote server example (SSE enabled for Claude, omitted for adapters that do not support SSE):
  72. ```json
  73. {
  74. "mcp": {
  75. "transport": "sse",
  76. "url": "https://example.com/mcp/sse",
  77. "headers": { "Authorization": "Bearer ${TOKEN}" }
  78. },
  79. "overrides": {
  80. "antigravity": { "disabled": true },
  81. "codex": { "disabled": true }
  82. }
  83. }
  84. ```
  85. Rules:
  86. - **Explicit transport**: `command` infers `"transport": "stdio"` if omitted. A remote `url` **must** explicitly set `"transport": "http"` (streamable HTTP) or `"transport": "sse"`.
  87. - **Disabled-first precedence**: `"disabled": true` is evaluated *before* active transport validation and omits the server uniformly from that adapter (`antigravity`, `claude`, or `codex`).
  88. - **Transport-family switching**: Overriding a remote base with a `stdio` override (or vice versa) cleanly clears opposite-family inherited fields (`url`/`headers` vs `command`/`args`/`env`).
  89. - **Override precedence**: base `mcp.json` -> inline `overrides.<agent>` -> `<agent>/mcp.json`. Legacy `gemini` override keys/directories fail with a migration message pointing to `antigravity`.
  90. ---
  91. ## Usage
  92. ```bash
  93. # Sync instructions, skills, and MCP configs
  94. sync-agents
  95. # Inspect observed state, intended state, ownership basis, and reasons (read-only)
  96. sync-agents --explain
  97. # Preview planned changes (leaves final hub, targets, state, journals, and locks untouched)
  98. sync-agents --dry-run
  99. # Verify targets, ownership ledger, and recovery state are completely clean (exits 1 on any drift)
  100. sync-agents --check
  101. # Install a skill from a directory, Git URL, .bundle, .zip/.skill, or tarball
  102. sync-agents --skill https://github.com/owner/repo.git
  103. # Update an already-installed skill ONLY (never forces MCP or symlink replacement)
  104. sync-agents --force-skill --skill https://github.com/owner/repo.git
  105. # Adopt unmanaged identical symlinks, MCP entries, or strictly equivalent files/dirs
  106. sync-agents --adopt
  107. # Retire an unverified legacy v1 .mcp-managed.json claim while retaining a personal entry
  108. sync-agents --disown-legacy claude:personal-server
  109. ```
  110. > **Dry-run note:** `--dry-run`, `--check`, and `--explain` never modify final destinations, ownership state, journals, or lock files. When `--dry-run` is combined with `--skill <git-url|archive>`, the source is unpacked into a temporary directory under `$TMPDIR` to inspect `SKILL.md` and cleaned up on exit.
  111. ---
  112. ## Safety, Ownership & Recovery Model
  113. ### Explicit Ownership Ledger (XDG State)
  114. Machine-local ownership records live under `${XDG_STATE_HOME:-$HOME/.local/state}/agent-hub/` (never inside your git-tracked `~/.agents/`):
  115. - `state-<hub-hash>.json` — v2 ownership ledger with monotonic `generation`, tracking every managed symlink (`target`, `basis`) and managed MCP entry (`configPath`, content `digest`, `basis`).
  116. - `journal-<hub-hash>.json` — active write-ahead recovery journal present only while a target mutation is in flight.
  117. - `apply.lock` — persistent inode locked via OS-held advisory `flock(2)` during `apply` (never unlinked; released automatically by the kernel on process exit or `SIGKILL`).
  118. Key safety guarantees:
  119. - **No inferred ownership**: A symlink's existence, a hub path prefix, or a disabled canonical MCP entry never grants ownership. Unmanaged entries are preserved and reported as conflicts.
  120. - **Strict adoption-equivalence contract (`--adopt`)**: Replacing a non-symlink file or directory with a symlink requires exact equality across **all** entries (including `.git`, dotfiles, and empty directories), object kinds (refusing FIFOs, sockets, and device nodes), file bytes, full permission/special mode bits (`mode & 0o7777`), `uid`/`gid`, hardlink guard (`nlink === 1`), literal symlink targets (refusing escaping relative symlinks), and extended attributes (names **and raw byte values**) + ACLs on macOS (and on Linux when `getfattr`/`getfacl` are installed; when absent on Linux, xattrs/ACLs are outside host verification). Explicitly non-preserved properties under `--adopt`: file timestamps (`atime`/`mtime`/`ctime`/`birthtime`) and inode/dirent identity.
  121. - **TOML-aware Codex editing + semantic guard**: Codex `config.toml` edits use a TOML 1.0 lexical scanner (preserving multiline strings, comments, and unrelated tables), refuse unsupported inline/dotted `mcp_servers` representations before writing, and verify deep semantic equality of every unrelated parsed value before touching disk.
  122. - **Preflight & freshness verification**: Phase 1 validates everything before Phase 2 starts. A preflight conflict causes no new Phase 2 target or ledger changes (any Phase 0 recovery performed earlier in the run is reported separately). Immediately before each Phase 2 mutation, the live snapshot (contents, mode, uid/gid, or full tree equivalence digest) is re-verified against the planned snapshot; drifted targets are preserved and the stale write is refused.
  123. - **Write-ahead recovery & durability scope**: Every target mutation writes a recovery journal before modifying the target and clears it only after the corresponding ledger update completes. On restart, Phase 0 reconciles interrupted operations (including target-written/state-unsaved and mid-swap directory replacements) or stops safely preserving evidence if the target changed ambiguously. **Scope:** Intended recovery guarantees cover **process interruption and ordinary I/O failures**; machine crash / power-loss durability is unverified and outside this guarantee.
  124. - **Concurrency scope**: Cooperating `sync-agents` writers (even across different hubs) are serialized by `flock(2)`. Against non-cooperating external agent applications, snapshot verification prevents applying stale plans, while POSIX check-then-rename still leaves an open window against simultaneous external writes.
  125. ### Migrating from Legacy v1 `.mcp-managed.json`
  126. Existing `<hub>/.mcp-managed.json` (v1) manifests are treated conservatively as **unverified provenance**:
  127. 1. **Identical existing entries**: Run `sync-agents --adopt` once to record verified v2 ownership in XDG state without rewriting configs.
  128. 2. **Absent targets** (disabled or removed): Automatically retired into v2 state on the next ordinary `sync-agents` run (reported as ledger-only drift by `--check` until applied).
  129. 3. **Retaining a personal entry without ownership**: Withdraw or rename the conflicting canonical `<hub>/mcp/<name>` directory (note: this affects all adapters), then run `sync-agents --disown-legacy <agent>:<name>` to retire the legacy claim without touching your target config.
  130. 4. **Replacing or deleting**: Pass `--force` explicitly after inspecting the conflict.
  131. ---
  132. ## Development & Tests
  133. ```bash
  134. bun test
  135. ```
  136. Promote reviewed changes from your dev checkout to `~/.agent-hub/`:
  137. ```bash
  138. ./install.sh
  139. ```
  140. ## License
  141. [Apache-2.0](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.