Skip to content

Adonis0123/adonis-skills / skills/agent-dispatch

agent-dispatch

Flagged

Choose the lightest agent setup for a coding, review, drafting or design-research task: do it yourself, fan out to 2-3 workers with independent parts across the Claude Code, Codex, Grok Build, Cursor or other CLIs and accounts on this machine, run a scoped architecture loop, or send one brief to independent researchers; pick a cross-model reviewer, test budget and cleanup; track dispatched work, external waits and user decisions on a Run Board. Use when work may need delegation, or the user asks to dispatch, fan out, parallelize, run several agents or accounts, get another AI's review or independent design opinions, or asks how dispatched work is going. Chinese triggers: 派活、并行、要不要多开几个 agent、分给多个 Claude 账号 / codex / grok、找另一个 AI 审、对比优秀设计、多方意见、进度看板、派出的任务进行到哪了。Not for unrelated read-only questions, trivial edits, research with no delegation, a single review of an existing diff (agentic-review-handoff), or the machine-wide session list (sideby sessions). Inside another named workflow, only size its workers.

FileKindSize
GLOSSARY.mdmarkdown2.1 KB
SKILL.mdskill md27.8 KB
evals/README.mdmarkdown7.6 KB
evals/README.zh-CN.mdmarkdown7.5 KB
evals/bench/compare.pyscript5.3 KB
evals/bench/run_bench.pyscript12.3 KB
evals/bench/tasks.jsonconfig6.6 KB
evals/bench/test_bench.pyscript4.4 KB
evals/build_plugin_eval.pyscript11.3 KB
evals/evals.jsonconfig31.4 KB
evals/results.mdmarkdown15.8 KB
evals/test_eval_harness.pyscript3.5 KB
evals/trigger-eval-set.jsonconfig1.6 KB
fixtures/probe-full.jsonconfig1.6 KB
fixtures/probe-single.jsonconfig690 B
fixtures/run-midrun/B9.jsonlother191 B
fixtures/run-midrun/deploy-log.txtmarkdown42 B
fixtures/run-midrun/run.jsonconfig1.8 KB
fixtures/run-sessions/B9.jsonlother191 B
fixtures/run-sessions/deploy-log.txtmarkdown42 B
fixtures/run-sessions/ended.jsonlother95 B
fixtures/run-sessions/run.jsonconfig2.1 KB
fixtures/run-sessions/sessions.jsonconfig804 B
fixtures/session-index.jsonconfig401 B
fixtures/sideby-stub/sessions.jsonconfig1.5 KB
fixtures/sideby-stub/sidebyexecutablescript4.1 KB
references/accounts.mdmarkdown10.4 KB
references/context-budget.mdmarkdown2.9 KB
references/fallbacks.mdmarkdown4.7 KB
references/launch.mdmarkdown16.1 KB
references/measure.mdmarkdown3.3 KB
references/research-brief.mdmarkdown1.3 KB
references/run-board.mdmarkdown48.7 KB
references/task-spec.mdmarkdown5.0 KB
scripts/board.cssother12.6 KB
scripts/board_interaction.jsscript3.7 KB
scripts/board_markdown.jsscript2.9 KB
scripts/board_render.pyscript17.2 KB
scripts/dispatch_board.pyscript95.3 KB
scripts/isolated_case.pyscript1.6 KB
scripts/probe_agents.pyscript12.9 KB
scripts/sideby_cli.pyscript3.2 KB
scripts/sideby_sessions.pyscript3.3 KB
scripts/test_billing_and_quota.pyscript10.9 KB
scripts/test_board_interaction.jsscript2.1 KB
scripts/test_board_markdown.jsscript2.9 KB
scripts/test_board_reload_state.jsscript2.7 KB
scripts/test_bug_regressions.pyscript4.7 KB
scripts/test_dispatch_board.pyscript68.9 KB
scripts/test_harness_limits.pyscript11.7 KB
scripts/test_lane_states.pyscript7.5 KB
scripts/test_probe_agents.pyscript19.2 KB
scripts/test_review_fixes.pyscript6.7 KB
scripts/test_rounds_and_watch.pyscript7.3 KB

scripts/probe_agents.py

View on GitHub
#!/usr/bin/env python3
"""Report which coding-agent CLIs this machine can dispatch to.

Discovers accounts from an accounts file, an optional multi-account manager,
or PATH lookup, then applies the user's account allow-list. Prints JSON only:
products, usable accounts, distinct quota pools, per-account launch commands,
how many sessions each pool may run, and the fallback the coordinator should
apply. Never prints emails, tokens, or credentials.
"""

from __future__ import annotations

import json
import os
import shutil
from typing import Callable
from sideby_sessions import SessionReader
from sideby_cli import read_json

# product id -> CLI binaries that provide it
PRODUCTS = {
    "claude": ["claude"],
    "codex": ["codex"],
    "grok": ["grok"],
    "cursor": ["cursor-agent"],
    "antigravity": ["agy"],
    "gemini": ["gemini"],
    "opencode": ["opencode"],
}
CODE_PRODUCTS = ("claude", "codex", "grok", "cursor", "opencode", "gemini")
# preferred for long-form drafting; any code product can draft as a fallback
DRAFTING_PRODUCTS = ("antigravity",)

ADAPTERS: list[Callable[[], tuple[list[dict], str] | None]] = []


def register_adapter(fn: Callable[[], tuple[list[dict], str] | None]) -> Callable[[], tuple[list[dict], str] | None]:
    ADAPTERS.append(fn)
    return fn


def get_accounts_file_path() -> str:
    env_path = os.environ.get("AGENT_DISPATCH_ACCOUNTS")
    if env_path:
        return os.path.expanduser(env_path)
    xdg_config = os.environ.get("XDG_CONFIG_HOME")
    if xdg_config:
        return os.path.join(os.path.expanduser(xdg_config), "agent-dispatch", "accounts.json")
    return os.path.expanduser("~/.config/agent-dispatch/accounts.json")


def read_accounts_file(path: str | None = None) -> dict | None:
    if path is None:
        path = get_accounts_file_path()
    if not os.path.isfile(path):
        return None
    try:
        with open(path, "r", encoding="utf-8") as f:
            data = json.load(f)
    except (OSError, ValueError):
        return None
    return data if isinstance(data, dict) else None


def from_accounts_file(path: str | None = None, data: dict | None = None) -> list[dict] | None:
    if data is None:
        data = read_accounts_file(path)
    if data is None:
        return None

    raw_accounts = data.get("accounts")
    if not isinstance(raw_accounts, list):
        return None

    accounts = []
    for idx, item in enumerate(raw_accounts):
        if not isinstance(item, dict):
            continue
        product = item.get("product")
        command = item.get("command")
        if not product or not command or not isinstance(product, str) or not isinstance(command, str):
            continue
        product = product.strip().lower()
        command = command.strip()
        pool = item.get("pool")
        if pool is not None and isinstance(pool, str) and pool.strip():
            pool_val = pool.strip()
        else:
            # missing pool means its own pool
            pool_val = f"{product}:own:{idx}"
        account_id = item.get("id")
        if not isinstance(account_id, str) or not account_id.strip():
            account_id = command
        accounts.append(
            {
                "id": account_id.strip(),
                "product": product,
                "command": command,
                "pool": pool_val,
            }
        )
    return accounts


def parse_allow(raw: object) -> list[str]:
    """Accept a list or a comma/space separated string of account ids."""
    if isinstance(raw, str):
        items = raw.replace(",", " ").split()
    elif isinstance(raw, list):
        items = [x for x in raw if isinstance(x, str)]
    else:
        return []
    return [x.strip() for x in items if x.strip()]


def get_allow(file_data: dict | None) -> list[str]:
    # env is the user's per-run instruction, so it wins over the file
    env_allow = parse_allow(os.environ.get("AGENT_DISPATCH_ALLOW", ""))
    if env_allow:
        return env_allow
    return parse_allow((file_data or {}).get("allow"))


# Pools bound quota, not concurrency: a busy account still takes another
# headless session while its quota allows. The batch cap keeps L2 at 3 workers.
DEFAULT_SESSIONS_PER_POOL = 3
DEFAULT_BATCH_CAP = 3


def get_sessions_per_pool(file_data: dict | None) -> tuple[int, bool]:
    """Return (sessions per pool, whether the user set it explicitly)."""
    for raw in (os.environ.get("AGENT_DISPATCH_SESSIONS_PER_POOL"), (file_data or {}).get("sessions_per_pool")):
        if raw is None or raw == "":
            continue
        try:
            value = int(raw)
        except (TypeError, ValueError):
            continue
        if value >= 1:
            return value, True
    return DEFAULT_SESSIONS_PER_POOL, False


def parse_aliases(raw: object) -> dict[str, str]:
    """Map short command -> account id; values are an id or {"account": id, ...}."""
    if not isinstance(raw, dict):
        return {}
    aliases = {}
    for short, target in raw.items():
        if isinstance(target, dict):
            target = target.get("account")
        if isinstance(short, str) and isinstance(target, str) and target.strip():
            aliases[short.strip()] = target.strip()
    return aliases


def from_sideby_aliases() -> dict[str, str]:
    """Short commands such as cc001 -> claude:001, from sideby's config."""
    if not shutil.which("sideby"):
        return {}
    data = read_json(['config', 'get', 'aliases'], timeout=20)
    return parse_aliases(data['value']) if data is not None else {}


def get_aliases(file_data: dict | None) -> dict[str, str]:
    # the accounts file wins over the manager for the same short name
    return {**from_sideby_aliases(), **parse_aliases((file_data or {}).get("aliases"))}


def is_allowed(product: str, account: dict, allow: list[str]) -> bool:
    keys = {product, account["id"], account["command"]}
    return any(entry in keys for entry in allow)


@register_adapter
def from_sideby() -> tuple[list[dict], str] | None:
    """Read accounts from sideby multi-account manager if available."""
    if not shutil.which("sideby"):
        return None
    data = read_json(['list'], timeout=20)
    if data is None:
        return None
    accounts = []
    for acc in data.get("accounts", []):
        if not isinstance(acc, dict):
            continue
        # subscription logins only: API-key accounts bill per call, so the
        # coordinator should not fan out to them without the user asking
        if not acc.get("hostInstalled") or acc.get("login") != "logged-in" or acc.get("kind") == "api":
            continue
        family = acc.get("family")
        ref = acc.get("ref")
        if not family or not ref:
            continue
        # accounts sharing one login share one quota pool
        pool = min([ref, *acc.get("sameLogin", [])])
        accounts.append(
            {
                "id": ref,
                "product": family,
                # trailing "--" passes host args through, e.g. `<command> -p ...`
                "command": f"sideby run {ref} --",
                "pool": pool,
            }
        )
    if not accounts:
        return None
    return accounts, "sideby"


def probe(sessions=None) -> dict:
    found: dict[str, list[dict]] = {}
    sources: list[str] = []
    file_data = read_accounts_file()

    # 1. Accounts file
    file_accounts = from_accounts_file(data=file_data)
    if file_accounts:
        sources.append("accounts_file")
        for acc in file_accounts:
            prod = acc["product"]
            found.setdefault(prod, [])
            if not any(existing["command"] == acc["command"] for existing in found[prod]):
                found[prod].append({"id": acc["id"], "command": acc["command"], "pool": acc["pool"]})

    # 2. Multi-account manager adapter(s)
    for adapter in ADAPTERS:
        res = adapter()
        if res:
            mgr_accounts, mgr_source = res
            if mgr_accounts:
                sources.append(mgr_source)
                for acc in mgr_accounts:
                    prod = acc["product"]
                    found.setdefault(prod, [])
                    if not any(existing["command"] == acc["command"] for existing in found[prod]):
                        found[prod].append({"id": acc["id"], "command": acc["command"], "pool": acc["pool"]})

    # 3. PATH lookup as last resort
    for product, bins in PRODUCTS.items():
        if product in found and found[product]:
            continue
        binary = next((b for b in bins if shutil.which(b)), None)
        if binary:
            found[product] = [{"id": binary, "command": binary, "pool": binary}]

    # 4. The user's allow-list overrides discovery
    allow = get_allow(file_data)
    allow_unmatched: list[str] = []
    if allow:
        aliases = get_aliases(file_data)
        # short commands such as cc001 resolve to their account id
        resolved = {entry: aliases.get(entry, entry) for entry in allow}
        matched: set[str] = set()
        for product in list(found):
            kept = []
            for acc in found[product]:
                keys = {product, acc["id"], acc["command"]}
                if is_allowed(product, acc, list(resolved.values())):
                    kept.append(acc)
                    matched.update(e for e, target in resolved.items() if target in keys)
            if kept:
                found[product] = kept
            else:
                del found[product]
        allow_unmatched = [e for e in allow if e not in matched]
    sessions_per_pool, sessions_per_pool_explicit = get_sessions_per_pool(file_data)

    if "accounts_file" in sources:
        source = "accounts_file"
    elif sources:
        source = sources[0]
    else:
        source = "path"

    products = {
        p: {
            "accounts": found[p],
            "quota_pools": len({a["pool"] for a in found[p]}),
        }
        for p in sorted(found.keys())
    }
    code = [p for p in CODE_PRODUCTS if p in products]
    pools = sum(products[p]["quota_pools"] for p in code)

    if sessions is None:
        sessions = SessionReader().read()
    account_pools = {a["id"]: a["pool"] for p in code for a in found[p]}
    busy_sessions = {pool: [] for pool in account_pools.values()}
    # LiveSession has no interactive/worker flag. Conservatively reserve every busy
    # session, except explicitly identified sessions belonging to this Run.
    owned = set(parse_allow(os.environ.get("AGENT_DISPATCH_OWNED_SESSIONS", "")))
    coordinator = (os.environ.get("AGENT_DISPATCH_COORDINATOR_SESSION")
                   or os.environ.get("CLAUDE_CODE_SESSION_ID")
                   or os.environ.get("CODEX_THREAD_ID"))
    if coordinator:
        owned.add(coordinator)
    for session in (sessions or {}).get("sessions", []):
        pool = account_pools.get(session.get("account"))
        sid = session.get("sessionId")
        if pool and sid not in owned and session.get("status") == "busy" and sid not in busy_sessions[pool]:
            busy_sessions[pool].append(sid)
    available_slots = {pool: max(0, sessions_per_pool - len(rows)) for pool, rows in busy_sessions.items()}
    capacity = max(0, sum(available_slots.values()) - 1)
    fallback = []
    for pool, rows in busy_sessions.items():
        if rows:
            fallback.append(f"{pool}: {len(rows)} busy user sessions reserved; {available_slots[pool]} worker slots available")
    if sessions and sessions.get("problems"):
        fallback.append("sideby sessions reported problems; occupancy may be incomplete")
    if len(code) < 2:
        fallback.append(
            "single-product: reviewer is a fresh session of the same product "
            "that sees only the diff and spec, never the writer's conversation"
        )
    if pools < 2 and sessions_per_pool < 2:
        fallback.append("one quota pool: L2 runs workers one after another, not in parallel")
    elif pools < 2:
        fallback.append("one quota pool: parallel sessions all share one rate limit")
    if "antigravity" not in products:
        fallback.append("no drafting agent: coordinator writes articles itself with the writing skills")

    return {
        "source": source,
        "products": products,
        "code_products": code,
        "drafting_agents": [p for p in DRAFTING_PRODUCTS if p in products],
        "allow": allow,
        "allow_unmatched": allow_unmatched,
        "sessions_per_pool": sessions_per_pool,
        "busy_sessions": busy_sessions,
        "available_slots": available_slots,
        # pools bound quota, sessions_per_pool bounds concurrency; the
        # coordinator holds one session slot, its own pool may host workers.
        # Only a user-set limit above 1 lifts the batch cap of 3.
        "max_parallel_workers": max(
            0,
            capacity
            if sessions_per_pool_explicit and sessions_per_pool > 1
            else min(DEFAULT_BATCH_CAP, capacity),
        ),
        "fallback": fallback,
    }


def main() -> None:
    result = probe()
    print(json.dumps(result, ensure_ascii=False, indent=2))


if __name__ == "__main__":
    main()
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 197kUpdated Claude CodeCodexVerifiedInstall