aicp-cli 0.6.0__tar.gz → 0.7.0__tar.gz

{aicp_cli-0.6.0 → aicp_cli-0.7.0}/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [0.7.0] - 2026-09-17
+
+### 🚀 Features
+
+- **agents:** Add cli and menu editing surface
+
+### 🐛 Bug Fixes
+
+- **menu:** Size panels to their own content
+## [0.6.0] - 2026-09-17
+
+### 📚 Documentation
+
+- **changelog:** Release v0.6.0
 ## [0.5.1] - 2026-09-17
 
 ### 🐛 Bug Fixes

{aicp_cli-0.6.0 → aicp_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: aicp-cli
-Version: 0.6.0
+Version: 0.7.0
 Summary: AI commit + push, with a git-verified result summary
 Project-URL: Repository, https://github.com/weskao/aicp
 Project-URL: Issues, https://github.com/weskao/aicp/issues
@@ -168,6 +168,7 @@ use is the two commands above.
 aicp --doctor --json          # skill-install status for every configured CLI, as JSON
 aicp --install-skills --yes   # install what's missing, upgrade what's outdated
 aicp --install-skills --force # also replace files aicp doesn't recognize
+aicp --agents                 # the agent registry; see Custom agents for its verbs
 ```
 
 `--doctor --json` reports, per CLI and per skill: the target path and whether
@@ -242,12 +243,46 @@ preferences continue to use the config file below.
 
 You can add agents that are not in the built-in registry — or suppress
 built-in ones — without touching the bundled `agents.json` (which package
-upgrades replace). Create `~/.aicp/agents.json` with the same `version: 1`
-/ `agents` envelope. aicp merges it over the built-in registry at startup:
-user-defined entries win on conflict, and an entry with `"disabled": true`
-removes that agent from the chain entirely.
+upgrades replace). Your changes live in `~/.aicp/agents.json`, which aicp
+merges over the built-in registry at startup: your entries win on conflict,
+and an entry with `"disabled": true` removes that agent from the chain.
 
-**Adding a new agent** — example: [MiniMax](https://www.minimaxi.com/) CLI:
+You don't have to write that file by hand. `aicp --agents` edits it for you,
+and so does the **Agents** row of `aicp --config`:
+
+```sh
+aicp --agents                                   # list every agent and where it came from
+aicp --agents disable grok                      # drop one from the chain
+aicp --agents enable grok                       # put it back
+aicp --agents set claude executable=/opt/claude # override one field
+aicp --agents reset claude                      # forget your override
+```
+
+Like every other flag, the leading `--` is optional: `aicp agents disable grok`.
+
+Nothing is written unless the resulting registry passes the same validation
+the next run does, so a typo is refused with the file left exactly as it was —
+`aicp` can never be edited into a state where it won't start. Disabling an
+agent also removes it from a saved `aicp_cli_order`, because an order naming
+an agent that no longer resolves is rejected *in full*, which would silently
+reset a fallback order you picked on purpose. The last remaining agent can't
+be disabled.
+
+**Adding a new agent** — example: [MiniMax](https://www.minimaxi.com/) CLI.
+Every field is required for a name the built-in registry has never heard of:
+
+```sh
+aicp --agents set minimax \
+  executable=minimax \
+  config_dir='~/.minimax' \
+  memory_file=AGENTS.md \
+  skills_dir=skills \
+  skills=safe-git-push \
+  'args=--prompt,{prompt},--yes'
+```
+
+`skills` and `args` are comma-separated; a value that needs a literal comma
+has to go into the file by hand. The equivalent written out:
 
 ```json
 {
@@ -265,51 +300,27 @@ removes that agent from the chain entirely.
 }
 ```
 
-Then add `minimax` anywhere in your preferred fallback order:
+A new agent joins the end of the fallback chain automatically. To put it
+first, use `aicp --swap-ai`, the AI CLI order row of `aicp --config`, or set
+the order yourself:
 
 ```sh
 # ~/.aicp/config.json
 { "aicp_cli_order": "minimax copilot agy codex claude vibe grok" }
 ```
 
-Or set it as an environment variable for one run:
+Or as an environment variable, for one run:
 
 ```sh
 AICP_CLI_ORDER="minimax claude" aicp
 ```
 
-**Disabling a built-in agent** — example: remove `grok` from the chain:
-
-```json
-{
-  "version": 1,
-  "agents": {
-    "grok": { "disabled": true }
-  }
-}
-```
-
-**Overriding a built-in agent's settings** — example: change `claude`'s
-executable path:
-
-```json
-{
-  "version": 1,
-  "agents": {
-    "claude": {
-      "executable": "/opt/homebrew/bin/claude"
-    }
-  }
-}
-```
-
-Only the fields you provide are overridden; unspecified fields keep the
-built-in values. The same agent-field table above applies to user-defined
-entries. Running the chain only needs the `executable` on `PATH`, same as any
-built-in agent (see [Fallback results](#fallback-results-and-quota-limits));
-`config_dir` matters for skill installation — a newly added agent whose
-`config_dir` doesn't exist yet is skipped there until you set it up (as
-above).
+For an agent that already exists, only the fields you provide are overridden;
+unspecified fields keep the built-in values. Running the chain only needs the
+`executable` on `PATH`, same as any built-in agent (see
+[Fallback results](#fallback-results-and-quota-limits)); `config_dir` matters
+for skill installation — a newly added agent whose `config_dir` doesn't exist
+yet is skipped there until you set it up.
 
 The config file lives at `~/.aicp/config.json` (override the path itself
 with `AICP_CONFIG`, which — being the thing that names the file — can only be

{aicp_cli-0.6.0 → aicp_cli-0.7.0}/README.md

@@ -156,6 +156,7 @@ use is the two commands above.
 aicp --doctor --json          # skill-install status for every configured CLI, as JSON
 aicp --install-skills --yes   # install what's missing, upgrade what's outdated
 aicp --install-skills --force # also replace files aicp doesn't recognize
+aicp --agents                 # the agent registry; see Custom agents for its verbs
 ```
 
 `--doctor --json` reports, per CLI and per skill: the target path and whether
@@ -230,12 +231,46 @@ preferences continue to use the config file below.
 
 You can add agents that are not in the built-in registry — or suppress
 built-in ones — without touching the bundled `agents.json` (which package
-upgrades replace). Create `~/.aicp/agents.json` with the same `version: 1`
-/ `agents` envelope. aicp merges it over the built-in registry at startup:
-user-defined entries win on conflict, and an entry with `"disabled": true`
-removes that agent from the chain entirely.
+upgrades replace). Your changes live in `~/.aicp/agents.json`, which aicp
+merges over the built-in registry at startup: your entries win on conflict,
+and an entry with `"disabled": true` removes that agent from the chain.
 
-**Adding a new agent** — example: [MiniMax](https://www.minimaxi.com/) CLI:
+You don't have to write that file by hand. `aicp --agents` edits it for you,
+and so does the **Agents** row of `aicp --config`:
+
+```sh
+aicp --agents                                   # list every agent and where it came from
+aicp --agents disable grok                      # drop one from the chain
+aicp --agents enable grok                       # put it back
+aicp --agents set claude executable=/opt/claude # override one field
+aicp --agents reset claude                      # forget your override
+```
+
+Like every other flag, the leading `--` is optional: `aicp agents disable grok`.
+
+Nothing is written unless the resulting registry passes the same validation
+the next run does, so a typo is refused with the file left exactly as it was —
+`aicp` can never be edited into a state where it won't start. Disabling an
+agent also removes it from a saved `aicp_cli_order`, because an order naming
+an agent that no longer resolves is rejected *in full*, which would silently
+reset a fallback order you picked on purpose. The last remaining agent can't
+be disabled.
+
+**Adding a new agent** — example: [MiniMax](https://www.minimaxi.com/) CLI.
+Every field is required for a name the built-in registry has never heard of:
+
+```sh
+aicp --agents set minimax \
+  executable=minimax \
+  config_dir='~/.minimax' \
+  memory_file=AGENTS.md \
+  skills_dir=skills \
+  skills=safe-git-push \
+  'args=--prompt,{prompt},--yes'
+```
+
+`skills` and `args` are comma-separated; a value that needs a literal comma
+has to go into the file by hand. The equivalent written out:
 
 ```json
 {
@@ -253,51 +288,27 @@ removes that agent from the chain entirely.
 }
 ```
 
-Then add `minimax` anywhere in your preferred fallback order:
+A new agent joins the end of the fallback chain automatically. To put it
+first, use `aicp --swap-ai`, the AI CLI order row of `aicp --config`, or set
+the order yourself:
 
 ```sh
 # ~/.aicp/config.json
 { "aicp_cli_order": "minimax copilot agy codex claude vibe grok" }
 ```
 
-Or set it as an environment variable for one run:
+Or as an environment variable, for one run:
 
 ```sh
 AICP_CLI_ORDER="minimax claude" aicp
 ```
 
-**Disabling a built-in agent** — example: remove `grok` from the chain:
-
-```json
-{
-  "version": 1,
-  "agents": {
-    "grok": { "disabled": true }
-  }
-}
-```
-
-**Overriding a built-in agent's settings** — example: change `claude`'s
-executable path:
-
-```json
-{
-  "version": 1,
-  "agents": {
-    "claude": {
-      "executable": "/opt/homebrew/bin/claude"
-    }
-  }
-}
-```
-
-Only the fields you provide are overridden; unspecified fields keep the
-built-in values. The same agent-field table above applies to user-defined
-entries. Running the chain only needs the `executable` on `PATH`, same as any
-built-in agent (see [Fallback results](#fallback-results-and-quota-limits));
-`config_dir` matters for skill installation — a newly added agent whose
-`config_dir` doesn't exist yet is skipped there until you set it up (as
-above).
+For an agent that already exists, only the fields you provide are overridden;
+unspecified fields keep the built-in values. Running the chain only needs the
+`executable` on `PATH`, same as any built-in agent (see
+[Fallback results](#fallback-results-and-quota-limits)); `config_dir` matters
+for skill installation — a newly added agent whose `config_dir` doesn't exist
+yet is skipped there until you set it up.
 
 The config file lives at `~/.aicp/config.json` (override the path itself
 with `AICP_CONFIG`, which — being the thing that names the file — can only be

{aicp_cli-0.6.0 → aicp_cli-0.7.0}/pyproject.toml

@@ -2,7 +2,7 @@
 # PyPI distribution name only — the `aicp` name was taken in 2021 by an
 # unrelated project. The command, import path and repo stay `aicp`.
 name = "aicp-cli"
-version = "0.6.0"
+version = "0.7.0"
 description = "AI commit + push, with a git-verified result summary"
 readme = "README.md"
 requires-python = ">=3.10"

aicp_cli-0.7.0/src/aicp/agentcfg.py

@@ -0,0 +1,168 @@
+"""Editing ``~/.aicp/agents.json`` — the write side of :mod:`aicp.agents`.
+
+Kept out of that module on purpose. Every aicp run imports ``agents`` (the
+roster is built from it at import time) and nothing here runs unless
+``--agents`` or the config menu's Agents row is used; separating them also
+keeps ``agents`` free of an :mod:`aicp.config` import, which would be a cycle
+— config's roster comes from agents.
+
+**Nothing reaches disk until the whole candidate registry has passed the same
+validation the next run will do.** A refused edit leaves the previous file
+byte-identical, so a typo can never leave aicp unable to start.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Sequence
+from dataclasses import dataclass, fields
+from pathlib import Path
+
+from . import agents, config
+
+__all__ = ["EDITABLE", "STATE_LABELS", "VERBS", "AgentEditError", "Change", "apply"]
+
+
+class AgentEditError(ValueError):
+    """A refused edit. Nothing was written."""
+
+
+#: Which of the settable fields are comma-separated lists.
+LIST_FIELDS = ("skills", "args")
+#: Fields ``set`` accepts — read off :class:`~aicp.agents.Agent` rather than
+#: listed again, so a field added there is settable the same day. ``disabled``
+#: is not one of them: it is what the enable/disable verbs write.
+EDITABLE = tuple(field.name for field in fields(agents.Agent))
+
+VERBS = ("list", "enable", "disable", "set", "reset")
+
+#: Display text per :func:`aicp.agents.inventory` state, as ``(msgid,
+#: english)`` — the menu translates with its live language, the CLI with the
+#: resolved one, both off this single table.
+STATE_LABELS = {
+    agents.BUILT_IN: ("agents_state_builtin", "built-in"),
+    agents.OVERRIDDEN: ("agents_state_overridden", "overridden"),
+    agents.ADDED: ("agents_state_added", "added"),
+    agents.DISABLED: ("agents_state_disabled", "disabled"),
+}
+
+
+@dataclass(frozen=True)
+class Change:
+    """What :func:`apply` did."""
+
+    name: str
+    #: ``enabled`` / ``disabled`` / ``updated`` / ``reset`` / ``removed``.
+    #: ``reset`` reverts to a built-in definition; ``removed`` is the same
+    #: verb applied to an agent that only ever existed in the user file.
+    verb: str
+    #: The registry's names after the change, in resolution order.
+    names: tuple[str, ...]
+    #: Names dropped from a saved ``AICP_CLI_ORDER`` to keep it loadable.
+    pruned: tuple[str, ...]
+
+
+def parse_fields(assignments: Sequence[str]) -> dict[str, object]:
+    """``["executable=x", "args=--p,{prompt}"]`` -> a registry entry fragment."""
+    parsed: dict[str, object] = {}
+    for item in assignments:
+        key, sep, raw = item.partition("=")
+        if not sep or key not in EDITABLE:
+            raise AgentEditError(
+                f"expected key=value, key one of {', '.join(EDITABLE)} — got: {item}"
+            )
+        # A list field splits on commas, so a value that needs a literal comma
+        # has to be written into the file by hand. Nothing in a CLI invocation
+        # or a skill name has ever needed one.
+        parsed[key] = [part for part in raw.split(",") if part] if key in LIST_FIELDS else raw
+    return parsed
+
+
+def _prune_chain(names: tuple[str, ...], config_path: Path | str | None) -> tuple[str, ...]:
+    """Drop names the registry no longer has from a saved ``AICP_CLI_ORDER``.
+
+    Without this, disabling an agent leaves an unknown name in the saved
+    order and :func:`aicp.config.resolve_cli_chain` refuses the whole line —
+    silently resetting a hand-picked fallback order to the default roster.
+    """
+    saved = config.load_config(config_path).get("AICP_CLI_ORDER", "")
+    listed = saved.split()
+    dropped = tuple(name for name in listed if name not in names)
+    if dropped:
+        config.persist_key(
+            "AICP_CLI_ORDER", " ".join(n for n in listed if n in names), config_path
+        )
+    return dropped
+
+
+def apply(
+    verb: str,
+    name: str,
+    assignments: Sequence[str] = (),
+    *,
+    home: Path | None = None,
+    config_path: Path | str | None = None,
+) -> Change:
+    """Run *verb* against ``~/.aicp/agents.json`` and report what changed.
+
+    ``enable`` clears a ``disabled`` flag, ``disable`` sets one, ``set``
+    merges ``key=value`` fields, ``reset`` drops the whole user entry.
+    """
+    if verb not in VERBS or verb == "list":
+        raise AgentEditError(f"unknown agents verb: {verb}")
+    path = agents.user_registry_path(home)
+    try:
+        entries = agents.read_user_entries(path)
+    except (OSError, ValueError, TypeError, json.JSONDecodeError) as exc:
+        raise AgentEditError(f"{path} is unreadable ({exc}) — fix or delete it first") from exc
+
+    builtin = agents.load_agents(agents.BUILTIN_PATH)
+    known = {*builtin, *entries}
+    if verb != "set" and name not in known:
+        raise AgentEditError(f"unknown agent: {name} (known: {' '.join(sorted(known))})")
+
+    candidate = {key: dict(value) for key, value in entries.items()}
+    entry = candidate.setdefault(name, {})
+    if verb == "disable":
+        entry["disabled"] = True
+    elif verb == "enable":
+        entry.pop("disabled", None)
+    elif verb == "set":
+        if not assignments:
+            raise AgentEditError(f"set needs at least one key=value for {name}")
+        # Editing a disabled agent's fields would otherwise look like it did
+        # nothing: `disabled` drops the name before any of them are read.
+        if entry.get("disabled") is True:
+            raise AgentEditError(f"{name} is disabled — enable it first, then set its fields")
+        entry.update(parse_fields(assignments))
+    else:  # reset
+        candidate.pop(name)
+    # An entry that says nothing is not an override; leaving it behind would
+    # also crash the loader, which requires a full definition for a name the
+    # built-in registry has never heard of.
+    if not candidate.get(name, {"x": 1}):
+        candidate.pop(name)
+
+    try:
+        merged = agents.merge_entries(builtin, candidate, path)
+    except (ValueError, TypeError) as exc:
+        raise AgentEditError(str(exc)) from exc
+    if not merged:
+        raise AgentEditError(f"refusing to disable {name}: it is the last agent left")
+
+    if candidate:
+        if not config._write_json_private(path, {"version": 1, "agents": candidate}):
+            raise AgentEditError(f"failed to write {path}")
+    else:
+        # An empty `agents` object is rejected on read, so "no overrides left"
+        # has to be spelled as "no file" rather than an empty one.
+        path.unlink(missing_ok=True)
+
+    names = tuple(merged)
+    if verb == "reset":
+        applied = "reset" if name in merged else "removed"
+    elif verb == "set":
+        applied = "updated" if name in known else "added"
+    else:
+        applied = {"enable": "enabled", "disable": "disabled"}[verb]
+    return Change(name, applied, names, _prune_chain(names, config_path))

{aicp_cli-0.6.0 → aicp_cli-0.7.0}/src/aicp/agents.py

@@ -101,11 +101,19 @@ def load_agents(path: Path) -> dict[str, Agent]:
     return {name: _build_agent(path, name, entry, base=None) for name, entry in entries.items()}
 
 
-def merge_user_agents(agents: dict[str, Agent], path: Path) -> dict[str, Agent]:
-    """Overlay ``path``'s entries onto *agents*: partial overrides for known
-    names, full entries for new ones, ``disabled: true`` to drop a name."""
+def merge_entries(
+    agents: dict[str, Agent], entries: dict[str, dict], path: Path
+) -> dict[str, Agent]:
+    """Overlay raw *entries* onto *agents*: partial overrides for known names,
+    full entries for new ones, ``disabled: true`` to drop a name.
+
+    Takes the entries rather than a file so :mod:`aicp.agentcfg` can validate
+    a candidate registry it has not written yet — the whole reason an edit can
+    be refused without touching what is already on disk. *path* only names the
+    source in error messages.
+    """
     merged = dict(agents)
-    for name, entry in _read_registry(path).items():
+    for name, entry in entries.items():
         if not isinstance(entry, dict):
             raise TypeError(f"{path}: {name}: expected an agent object")
         if entry.get("disabled") is True:
@@ -115,8 +123,64 @@ def merge_user_agents(agents: dict[str, Agent], path: Path) -> dict[str, Agent]:
     return merged
 
 
+def merge_user_agents(agents: dict[str, Agent], path: Path) -> dict[str, Agent]:
+    """:func:`merge_entries` over the registry file at *path*."""
+    return merge_entries(agents, _read_registry(path), path)
+
+
+BUILTIN_PATH = Path(__file__).with_name("agents.json")
+
+
+def user_registry_path(home: Path | None = None) -> Path:
+    """Where a user's own overrides live. One place, so the reader, the writer
+    and the tests can never disagree about it."""
+    return (home or Path.home()) / ".aicp" / "agents.json"
+
+
+def read_user_entries(path: Path) -> dict[str, dict]:
+    """The user file's raw entries, or ``{}`` when there is no file."""
+    return _read_registry(path) if path.is_file() else {}
+
+
+#: What :func:`inventory` says about a name. Stable ids, not display text —
+#: ``agentcfg.STATE_LABELS`` maps them to translatable strings.
+BUILT_IN = "builtin"
+OVERRIDDEN = "overridden"
+ADDED = "added"
+DISABLED = "disabled"
+
+
+@dataclass(frozen=True)
+class AgentRow:
+    """One line of :func:`inventory`."""
+
+    name: str
+    executable: str
+    state: str
+
+
+def inventory(home: Path | None = None) -> list[AgentRow]:
+    """Every agent name aicp knows of, built-in order first, and where it
+    came from. Disabled names are listed too — hiding them is how someone
+    loses the ability to turn one back on."""
+    path = user_registry_path(home)
+    builtin = load_agents(BUILTIN_PATH)
+    entries = read_user_entries(path)
+    merged = merge_entries(builtin, entries, path)
+    rows = []
+    for name in [*builtin, *(n for n in entries if n not in builtin)]:
+        entry = entries.get(name)
+        if entry is not None and entry.get("disabled") is True:
+            base = builtin.get(name)
+            rows.append(AgentRow(name, base.executable if base else "—", DISABLED))
+        else:
+            state = BUILT_IN if entry is None else (OVERRIDDEN if name in builtin else ADDED)
+            rows.append(AgentRow(name, merged[name].executable, state))
+    return rows
+
+
 def _load_user_overrides(agents: dict[str, Agent], home: Path | None = None) -> dict[str, Agent]:
-    path = (home or Path.home()) / ".aicp" / "agents.json"
+    path = user_registry_path(home)
     if not path.is_file():
         return agents
     try:
@@ -126,7 +190,7 @@ def _load_user_overrides(agents: dict[str, Agent], home: Path | None = None) ->
         return agents
 
 
-AGENTS = _load_user_overrides(load_agents(Path(__file__).with_name("agents.json")))
+AGENTS = _load_user_overrides(load_agents(BUILTIN_PATH))
 
 
 def executable(name: str) -> str:

{aicp_cli-0.6.0 → aicp_cli-0.7.0}/src/aicp/cli.py

@@ -36,7 +36,19 @@ from collections.abc import Sequence
 from pathlib import Path
 from typing import NoReturn
 
-from . import __version__, config, gitflow, i18n, menu, notify, present, runner, skills
+from . import (
+    __version__,
+    agentcfg,
+    agents,
+    config,
+    gitflow,
+    i18n,
+    menu,
+    notify,
+    present,
+    runner,
+    skills,
+)
 from ._utils import BLUE, BOLD, CYAN, DIM, GREEN, MAGENTA, RED, RESET, YELLOW, have
 from .agents import executable
 from .contracts import ROSTER
@@ -201,7 +213,19 @@ def _normalize_argv(argv: Sequence[str], parser: argparse.ArgumentParser) -> lis
         for opt in action.option_strings
         if opt.startswith("--")
     }
-    return [f"--{arg}" if arg in long_flags else arg for arg in argv]
+    normalized: list[str] = []
+    for i, arg in enumerate(argv):
+        if arg in long_flags:
+            normalized.append(f"--{arg}")
+        elif arg.startswith("-"):
+            normalized.append(arg)
+        else:
+            # The first bare word that names no flag begins the operands
+            # (`aicp agents disable <name>`), and an agent that happens to be
+            # called "json" must not be rewritten into --json.
+            normalized.extend(argv[i:])
+            break
+    return normalized
 
 
 def build_parser() -> argparse.ArgumentParser:
@@ -245,6 +269,13 @@ def build_parser() -> argparse.ArgumentParser:
         "--doctor", action="store_true",
         help=t("help_doctor", "report where each vendored skill stands for each CLI"),
     )
+    parser.add_argument(
+        "--agents", nargs="*", metavar="ARG",
+        help=t(
+            "help_agents",
+            "list the agent registry; or enable/disable/set/reset one in ~/.aicp/agents.json",
+        ),
+    )
     parser.add_argument("--json", action="store_true", help=t("help_json", "--doctor as JSON"))
     parser.add_argument(
         "--install-skills", action="store_true",
@@ -273,6 +304,61 @@ def _doctor(*, as_json: bool) -> int:
     return 0
 
 
+def _agents_list() -> int:
+    rows = [
+        (row.name, f"{row.executable}  {DIM}·  {t(*agentcfg.STATE_LABELS[row.state])}{RESET}")
+        for row in agents.inventory()
+    ]
+    _echo(present.render(rows, t("agents_title", "AGENTS")))
+    _dim(t("agents_hint", "  aicp --agents set <name> executable=… · disable <name> · reset <name>"))
+    return 0
+
+
+def _agents(argv: Sequence[str]) -> int:
+    """``--agents`` and its verbs. Writes nothing on any error path."""
+    verb, rest = (argv[0] if argv else "list"), list(argv[1:])
+    if verb == "list":
+        return _agents_list()
+    if verb not in agentcfg.VERBS:
+        print(
+            f"{RED}"
+            + t("agents_bad_verb", "✗ unknown agents verb: %s (use: %s)", verb, " ".join(agentcfg.VERBS))
+            + RESET,
+            file=sys.stderr,
+        )
+        return 1
+    if not rest:
+        print(
+            f"{RED}" + t("agents_needs_name", "✗ %s needs an agent name", verb) + RESET,
+            file=sys.stderr,
+        )
+        return 1
+    try:
+        change = agentcfg.apply(verb, rest[0], rest[1:])
+    except agentcfg.AgentEditError as exc:
+        print(f"{RED}✗ {exc}{RESET}", file=sys.stderr)
+        return 1
+    done = {
+        "enabled": ("agents_done_enabled", "✓ %s enabled"),
+        "disabled": ("agents_done_disabled", "✓ %s disabled"),
+        "updated": ("agents_done_updated", "✓ %s updated"),
+        "added": ("agents_done_added", "✓ %s added"),
+        "reset": ("agents_done_reset", "✓ %s reset to its built-in definition"),
+        "removed": ("agents_done_removed", "✓ %s removed"),
+    }[change.verb]
+    print(f"{GREEN}{t(*done, change.name)}{RESET}")
+    if change.pruned:
+        _dim(
+            t(
+                "agents_pruned",
+                "  dropped from the saved CLI order: %s",
+                " ".join(change.pruned),
+            )
+        )
+    _dim(t("agents_next_run", "  the next aicp run uses it"))
+    return 0
+
+
 def _install_skills(*, yes: bool, force: bool) -> int:
     if not yes:
         rows = [(f"{s.cli} · {s.skill}", s.state) for s in skills.full_status()]
@@ -576,6 +662,8 @@ def _dispatch(args: argparse.Namespace) -> int:
 
     if args.doctor:
         return _doctor(as_json=args.json)
+    if args.agents is not None:
+        return _agents(args.agents)
     if args.install_skills:
         return _install_skills(yes=args.yes, force=args.force)
     if args.config: