中文版 | English

AgentRepoRouter

<p align="center"> <img src="images/cover/cover-03-architecture-board.png" alt="AgentRepoRouter Cover" width="100%"> </p>

Repo-aware routing for AI coding CLIs as an installable skill for multiple agent hosts.

AgentRepoRouter installs into OpenClaw, Claude Code, OpenCode, Codex, and Hermes skill locations. It does not replace those tools. It routes tasks to the right repo, preserves each CLI's native agent and skill conventions, and uses structured repo metadata to improve navigation.

Flow Overview

Install and Configuration Generation

flowchart TD
    start["Start scripts/install.sh"] --> env["Check Node.js 18+, Git, and TTY support"]
    env --> hosts["Detect available agent hosts"]
    hosts --> lang["Select skill language: Chinese / English"]
    lang --> mode{"Select install mode"}

    mode -->|Global| global["Write canonical skill directory: ~/.agents/skills/agent-repo-router"]
    mode -->|Single host| single["Write selected host skill directory directly"]
    mode -->|Custom hosts| custom["Write canonical directory and link selected hosts"]

    global --> installHosts["Resolve installHosts"]
    single --> installHosts
    custom --> installHosts

    installHosts --> clis["Select executionClis"]
    clis --> discovery{"Choose project discovery mode"}
    discovery -->|Auto scan| autoScan["Scan local projects and collect repo metadata"]
    discovery -->|Manual| manual["Enter absolute project paths"]

    autoScan --> assets["Detect project-level skills and agents"]
    manual --> assets
    assets --> mapping["Generate schema v2 repo_mappings.json"]
    mapping --> deploy["Deploy SKILL.md and references/guide.*.md"]
    deploy --> links{"Need host symlinks?"}
    links -->|Global / Custom hosts| symlink["Symlink host skill directories to the canonical directory"]
    links -->|Single host| direct["Keep direct host install directory"]
    symlink --> validate["Validate repo_mappings.json"]
    direct --> validate
    validate --> done["Install complete: host can load agent-repo-router"]

Runtime Routing and Execution

flowchart TD
    user["User submits a coding task"] --> host["OpenClaw / Claude Code / OpenCode / Codex / Hermes"]
    host --> skill["Load agent-repo-router Skill"]
    skill --> config["Read references/repo_mappings.json"]
    config --> repoDecision{"Can the target repo be resolved confidently?"}

    repoDecision -->|User specified repo| targetRepo["Use the user-specified repo"]
    repoDecision -->|repo name / alias / task intent match| targetRepo
    repoDecision -->|No reliable match| askRepo["Ask the user for the target repo"]
    askRepo --> targetRepo

    targetRepo --> projectHints["Read aliases, skills, and agents for the repo"]
    projectHints --> projectAssets{"Project-level skill / agent matched?"}

    projectAssets -->|Yes| projectPlan["Compose skill / agent prompt using the native CLI convention"]
    projectAssets -->|No| globalAssets{"Global skill / agent strictly matched?"}
    globalAssets -->|Yes| globalPlan["Attach global capability conservatively"]
    globalAssets -->|No| fallback["Fallback by executionClis order"]

    projectPlan --> chooseCli{"Choose execution CLI"}
    globalPlan --> chooseCli
    fallback --> chooseCli

    chooseCli --> claude["Claude Code: cd repo && claude -p task"]
    chooseCli --> opencode["OpenCode: cd repo && opencode run task"]
    chooseCli --> cursor["Cursor: cd repo && agent -p task"]
    chooseCli --> codex["Codex: cd repo && codex exec task"]
    chooseCli --> hermes["Hermes: cd repo && hermes --oneshot task"]

    claude --> result["Native CLI runs in the target repo and returns the result"]
    opencode --> result
    cursor --> result
    codex --> result
    hermes --> result

Why AgentRepoRouter Exists

Many developers now have more than one coding CLI, more than one repo, and more than one place where custom agents or skills live.

The real problem is often not "how do I run 20 agents in parallel?" It is:

• Which repo should this task run in?
• Which CLI is the best fit for this repo?
• Does this repo already contain a project-level skill or agent I should use first?
• How do I keep one agent-host entry point without flattening away each CLI's native conventions?

AgentRepoRouter is built for that gap.

Positioning

The best way to understand AgentRepoRouter is:

• OpenClaw, Claude Code, OpenCode, Codex, or Hermes can host the skill.
• AgentRepoRouter is the routing layer for coding work.
• Claude Code, OpenCode, Cursor, Codex, and Hermes stay as the execution backends.

This means AgentRepoRouter is intentionally lighter than a full orchestration runtime. It focuses on entry, routing, repo selection, and native CLI invocation rather than boards, worktrees, PR lifecycle automation, or parallel swarms.

Research Conclusion

This round of repo research led to three practical conclusions:

• AgentRepoRouter's value is not "beating" heavy orchestrators. Its value is being the thin but useful layer that makes agent hosts repo-aware and CLI-aware for real coding tasks.
• The most important differentiator is preserving native CLI ecosystems instead of inventing a new abstraction that hides them.
• With aliases, detected project skills, and detected project agents now embedded in repo_mappings.json, AgentRepoRouter is no longer just a thin prompt wrapper. It becomes structured routing context that supported hosts can navigate reliably.

Quick Start

# Install from GitHub
curl -fsSL https://raw.githubusercontent.com/wufei-png/AgentRepoRouter/main/scripts/install.sh | bash

# Or local install
bash scripts/install.sh

# Non-interactive install with explicit repositories
bash scripts/install.sh --yes --language zh --repo /absolute/path/to/repo --hosts codex --execution-clis codex

# Non-interactive install by scanning a repository prefix
bash scripts/install.sh --yes --auto-scan --scan-root /absolute/path/to/repos --scan-depth 5 --hosts all --execution-clis all

# Review repo aliases and detected project assets
vim ~/.agents/skills/agent-repo-router/references/repo_mappings.json

# Start your host, for example OpenClaw
openclaw

Runtime Shape

User
  -> OpenClaw / Claude Code / OpenCode / Codex / Hermes
  -> Router Skill
  -> repo match via repo name / alias / task intent
  -> project-level skill / agent hints from repo_mappings.json
  -> direct native CLI execution

What Exists Today

• scripts/install.sh checks Node.js 18+ and Git, then detects supported agent hosts.
• The installer lets you choose language, install mode, install hosts, and execution CLIs separately.
• Default install mode is global: write once to ~/.agents/skills/agent-repo-router and symlink detected hosts.
• Single-host mode installs directly into the selected host skill directory.
• Custom-host mode writes the canonical global copy and symlinks selected hosts.
• Project discovery supports auto scan, repeated --repo arguments, manual absolute paths, and configurable scan depth. Auto scan defaults to depth 5; scripts can use --scan-depth N or AGENT_REPO_ROUTER_SCAN_MAX_DEPTH=N.
• Non-interactive installs support --yes, --language zh|en, --install-mode global|single|custom, --hosts, --execution-clis, --existing backup|skip|overwrite, --repo, --auto-scan, and --scan-root.
• --hosts all means all detected install hosts; if none are detected, the installer falls back to the Codex canonical target. Explicit host names are allowed even when the host CLI is not detected.
• --execution-clis all means all detected execution CLIs in the fixed order claude-code,opencode,cursor,codex,hermes; explicitly listed execution CLIs must be installed.
• Reinstalls default to --existing backup, which moves real old install

targets under ${TMPDIR:-/tmp}/agent-repo-router-skill-backups/install-* and creates a fresh repo_mappings.json instead of merging aliases. Existing symlink install targets are unlinked and recreated, not backed up.

• The generated repo config includes aliases, detected project-level skills, and detected project-level agents.
• The installer writes schema v2 repo_mappings.json with installMode, installHosts, and executionClis.
• The repo includes unit, integration, and E2E tests plus opt-in live OpenClaw E2E coverage.

Design Principles

1. Host-Native Installation

AgentRepoRouter is delivered as a skill, not as another daemon or control plane. It can be installed directly for one host or installed once globally and linked into multiple host skill directories.

2. Repo Metadata Is First-Class

Routing quality depends on repo context. repo_mappings.json is therefore not just a list of paths. It is a small routing catalog:

{
  "schemaVersion": 2,
  "installMode": "global",
  "installHosts": ["global", "openclaw", "claude-code", "opencode", "codex", "hermes"],
  "executionClis": ["claude-code", "opencode", "cursor", "codex", "hermes"],
  "repos": [
    {
      "name": "example-backend",
      "path": "/path/to/backend",
      "aliases": ["backend", "api"],
      "skills": {
        "claude-code": [
          {
            "name": "build_and_test",
            "description": "Run build and tests before finishing changes."
          }
        ]
      },
      "agents": {
        "claude-code": [
          {
            "name": "bugfix",
            "description": "Fix bugs and regressions with targeted changes."
          }
        ]
      }
    }
  ]
}

3. Preserve Native CLI Conventions

Each CLI already has its own invocation model and project asset conventions. AgentRepoRouter keeps those differences visible and uses them rather than hiding them.

• Claude Code: claude -p "task" or claude --agent <name> "task"
• OpenCode: opencode run "task" with prompt-based agent selection
• Cursor: agent -p "task" with prompt-based agent selection
• Codex: codex exec "task" with project-level .agents/skills/, .codex/agents/, and AGENTS.md
• Hermes: hermes --oneshot "task" with Hermes skill conventions

4. Project-Level Assets Come Before Global Defaults

If a repo already has a project-level skill or agent, that should be treated as a strong hint before any global helper is attached.

5. Explicit Fallback Beats Hidden Magic

If nothing matches reliably, AgentRepoRouter falls back using the executionClis order in repo_mappings.json. The behavior stays inspectable and predictable.

Why The Current Schema Matters

The newer aliases and detected skills and agents fields directly improve routing in ways the earlier minimal schema could not:

• aliases lets the host match user language to repo nicknames such as api, docs, or admin.
• skills gives the router project-level capability hints before the CLI even starts.
• agents gives the router project-level specialist hints without forcing weak global matches.
• The references/ folder keeps the runtime skill short while moving longer CLI conventions into explicit reference docs.

Comparison

The projects below are good comparison points, but they optimize for different layers of the stack.

Highlights

• Multi-host deployment: install once globally and link detected hosts, or install directly for one host.
• Repo-aware navigation: repo names, aliases, and task intent all contribute to routing.
• Structured project hints: detected project-level skills and agents are stored in config instead of living only in prompt text.
• Low lock-in: the execution step is still the original CLI, not a custom wrapper protocol.
• Native conventions preserved: AgentRepoRouter adapts to Claude Code, OpenCode, Cursor, Codex, and Hermes instead of pretending they are identical.
• Short runtime skill, longer references: the active SKILL.md stays readable while references/ holds the detailed conventions.
• Installer plus validation: repo config is generated and validated automatically.
• Tested baseline: the repo includes unit, integration, E2E, and opt-in live tests.

Supported CLIs

Install Targets

Codex's current public Agent Skills manual lists user skills under $HOME/.agents/skills; ~/.codex/skills is not the user skill discovery path for this installer.

Codex also officially supports codex exec -C /path/to/repo "task". AgentRepoRouter documentation still uses cd /path && ... examples so the routing pattern stays uniform across CLIs.

Example

User: "Fix the auth bug in the api project, use the repo's build_and_test skill."

Router:
1. Match repo alias `api` -> `example-backend`
2. Read detected project skills -> `build_and_test`
3. Read detected project agents -> `bugfix`
4. Choose the best native CLI path
5. Execute directly in the target repo

When AgentRepoRouter Is The Right Tool

Use AgentRepoRouter when you want:

• an existing agent host as the entry point
• multiple repos and multiple coding CLIs
• routing that respects project-level skills and agents
• a lighter layer than full agent swarms or kanban orchestrators

Pair AgentRepoRouter with other tools when needed:

• use MCO when you want the same task reviewed by multiple CLIs in parallel
• use agtx or Agent Orchestrator when you want worktree-heavy lifecycle automation
• use metaswarm when you want a much more opinionated SDLC process

Documentation

• CLAUDE.md - Full project context
• docs/ARCHITECTURE.md - Current architecture and runtime conventions
• docs/PRODUCT.md - Future roadmap, not current implementation
• docs/advertisement/why-agent-repo-router.md - Recommendation article for potential users
• docs/plans/migration/plan.md - Migration history and implementation plan
• legacy/README.md - Archived legacy materials