A command a person or a repository writes as a markdown file is a row of the command table, in a section of its own, and the harness runs it: the file's prompt, with what follows the name for $ARGUMENTS, goes to the session as input¶
Decision 763 · accepted · 2026-10-03 · issue #124
- Files.
<config>/commands/<name>.md(the user's) and<workspace>/.troupe/commands/<name>.md(the repository's), the shape other tools' command files have: optional frontmatter, then the body. The file name is the command; a name is what an agent's may be, lower-case letters, digits and dashes.descriptionis the summary (the body's first line without one) andargument-hintwhat the usage line says follows the name; other keys are left alone. The workspace's file wins over the user's of the same name, as the skills' layers resolve (700). - In the table. The
customsection, betweenagentsandquit, withsourceuserorprojectand adetailthat names the file, so a person knows where to change it. The files are read whenevercommands.listis asked, so one written a moment ago is listed. A pod reads its own config directory and workspace, as it reads.troupe/agents/there. - A built-in's name stays the built-in's, and so do an alias's and an agent's:
such a file is skipped, with a warning in the daemon's log. A built-in is code in
each client that a person's fingers know, and a repository's file arrives with a
clone; letting
merge.mdturn/mergeinto a prompt would change what a known command does without anyone being told. A name is one row, so a client finds a command by name and nothing has to choose between two. - The harness runs it (
commands.run,control): it finds the name among the session's defined commands, replaces every$ARGUMENTSwith what was typed after it, trimmed — or adds that as a paragraph of its own where the body has no placeholder, so nothing typed is dropped — and sends the result asinput.sendwould, under the samecommand_idand actor. A client keeps no copy of the expansion, so the terminal and the desktop app cannot disagree on what a command sends, and$1or@filelater are one change. Anything else isnot_foundwithkind: "command". - No trust needed. A command is a prompt sent only when somebody types it, and
does nothing the same words typed by hand would not: the turn goes through the
session's approvals as any other. So a workspace's commands are read whether or not
the workspace is trusted (686), as its
.troupe/agents/andAGENTS.mdare. Frontmatter that changed what may run without asking — a tool list, a model on another endpoint, an approval setting — would be a trusted key and is not read.
Governs: apps/troupe_core/lib/troupe/commands.ex, apps/troupe_core/lib/troupe/commands/local.ex, apps/troupe_gateway/lib/troupe/gateway/dispatch.ex, apps/troupe_protocol/lib/troupe/protocol/schema.ex, clients/gui/apps/desktop/src/views/CommandPalette.tsx, clients/tui/lib/troupe/client.ex, clients/tui/lib/troupe/ui/tui/server.ex