Skip to content

agents

agents

Lists installed AI coding agents, sets the default, and locates their mounts.

Three leaf verbs:

  • terok agents list [--all] — print the roster (agents only, or agents + tools when --all is passed).
  • terok agents set [SELECTION] — write the global default to config.yml under image.agents. Interactive picker when SELECTION is omitted; same comma-list grammar that terok image build --agents and the new-project wizard accept.
  • terok agents dir [AGENT] — print the shared agent-config mounts directory (or one agent's subdirectory), surfacing the otherwise-hidden ~/.local/share/terok/…/mounts/ where skills and per-agent settings live.

register(subparsers)

Register the agents group with list + set subverbs.

Source code in src/terok/cli/commands/agents.py 
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
    """Register the ``agents`` group with ``list`` + ``set`` subverbs."""
    p = subparsers.add_parser(
        "agents",
        help="Inspect the agent roster and set the global default selection",
        description=(
            "List the AI coding agents and tools the executor knows about, "
            "or set the global default selection in config.yml under "
            "image.agents."
        ),
    )
    sub = p.add_subparsers(dest="agents_cmd")

    p_list = sub.add_parser(
        "list",
        help="List available AI coding agents",
        description=(
            "List the AI coding agents and tools the executor knows about. "
            "Use the printed names with ``image.agents`` in project.yml or "
            "``--agents`` on ``terok task run``."
        ),
    )
    p_list.add_argument(
        "--all",
        action="store_true",
        help="Include non-agent tool entries (e.g. gh, glab, sidecar tools)",
    )

    p_set = sub.add_parser(
        "set",
        help="Set the global image.agents default (interactive when no arg)",
        description=(
            "Write the agent selection to the global config.yml under "
            "image.agents.  Validated against the installed roster before "
            "the file is touched.  Interactive picker when SELECTION is "
            "omitted."
        ),
    )
    p_set.add_argument(
        "selection",
        nargs="?",
        default=None,
        help=(
            'Agent selection in the executor\'s canonical grammar: "all", '
            'a comma list ("claude,vibe"), or "all,-name" to exclude one '
            '("all,-vibe").  Interactive picker when omitted.'
        ),
    )

    p_dir = sub.add_parser(
        "dir",
        help="Print the shared agent-config mounts directory (or one agent's subdir)",
        description=(
            "Print the host directory that holds the per-agent config mounts "
            "bind-mounted into task containers.  With an AGENT, print that "
            "agent's config subdirectory (e.g. _claude-config) instead."
        ),
    )
    p_dir.add_argument(
        "agent",
        nargs="?",
        default=None,
        help="Optional agent name; print its config-mount subdirectory",
    )

dispatch(args)

Handle terok agents …. Returns True if handled.

Source code in src/terok/cli/commands/agents.py 
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
def dispatch(args: argparse.Namespace) -> bool:
    """Handle ``terok agents …``.  Returns True if handled."""
    if args.cmd != "agents":
        return False

    sub = getattr(args, "agents_cmd", None)
    if sub is None:
        # Bare ``terok agents`` — print the group's help so users see the verbs.
        print(
            "usage: terok agents {list,set,dir} ...\n\n"
            "  list  List available AI coding agents\n"
            "  set   Set the global image.agents default in config.yml\n"
            "  dir   Print the shared agent-config mounts directory\n",
            file=sys.stderr,
        )
        return True

    if sub == "list":
        _print_roster(show_all=getattr(args, "all", False))
        return True
    if sub == "set":
        _set_global_default(selection=getattr(args, "selection", None))
        return True
    if sub == "dir":
        _print_mounts_dir(agent=getattr(args, "agent", None))
        return True
    return False