From 91328ca7e16c17e382eae25256e61202375dbdc9 Mon Sep 17 00:00:00 2001 From: Alex Clarke Date: Thu, 20 Aug 2026 16:54:19 -0600 Subject: [PATCH] docs: document macros as first-class custom commands MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Covers top-level .name invocation, the new description/isolated macro fields (with the non-isolation persistence, fail-fast, nested-macro, and .exit caveats), workspace .coyote/macros/ + --no-workspace-macros, enabled_macros scoping at global/role/agent/session levels, and .macro enable|disable across the README and every example config. graph.example.yaml gains a note that enabled_macros is ignored in graph configs. CHANGELOG intentionally untouched: it is generated by commitizen at release time from the conventional commit subjects. Implements plans/custom-commands-design.md §8. --- README.md | 5 ++++- config.agent.example.yaml | 2 ++ config.example.yaml | 15 +++++++++++++++ config.macro.example.yaml | 10 ++++++++++ config.role.example.md | 3 +++ graph.example.yaml | 3 +++ 6 files changed, 37 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 4143a81..b9b00df 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,10 @@ Coming from [AIChat](https://github.com/sigoden/aichat)? Follow the [migration g * [Create Custom Bash Tools](https://github.com/Dark-Alex-17/coyote/wiki/Custom-Bash-Tools) * [Bash Prompt Utilities](https://github.com/Dark-Alex-17/coyote/wiki/Bash-Prompt-Helpers) * [First-Class MCP Server Support](https://github.com/Dark-Alex-17/coyote/wiki/MCP-Servers): Easily connect and interact with MCP servers for advanced functionality. -* [Macros](https://github.com/Dark-Alex-17/coyote/wiki/Macros): Automate repetitive tasks and workflows with Coyote "scripts" (macros). +* [Macros](https://github.com/Dark-Alex-17/coyote/wiki/Macros): Automate repetitive tasks and workflows with Coyote "scripts" (macros). Macros are Coyote's custom commands: invoke any macro directly by name (e.g. `.review main`), with tab-completion, right alongside the built-in REPL commands. + * Give a macro a `description` (shown in `.list macros` and completions) and set `isolated: false` to run its steps on the live session, exactly as if you typed them. Note that non-isolated steps are recorded in the session, and mutating steps (`.role`, `.model`, ...) persist after the macro ends — by design. Steps are fail-fast: an error aborts the remaining steps, but completed steps' effects remain. A non-isolated macro step cannot invoke another macro, and a `.exit` step never exits the REPL. + * Commit project-specific macros to `.coyote/macros/` in your repo — they shadow same-named global macros (opt out with `--no-workspace-macros`). + * Scope which macros are invocable with `enabled_macros` in the global config, a role, an agent, or a session (most specific wins; an empty list disables all macros), and toggle at runtime with `.macro enable|disable `. * [RAG](https://github.com/Dark-Alex-17/coyote/wiki/RAG): Retrieval-Augmented Generation for enhanced information retrieval and generation. * [Sessions](https://github.com/Dark-Alex-17/coyote/wiki/Sessions): Manage and persist conversational contexts and settings across multiple interactions. * [Memory](https://github.com/Dark-Alex-17/coyote/wiki/Memory): Persistent file-based memory that survives across sessions. Bootstrap with `coyote --init-memory [global|workspace]`. diff --git a/config.agent.example.yaml b/config.agent.example.yaml index d7c6d5a..c4562df 100644 --- a/config.agent.example.yaml +++ b/config.agent.example.yaml @@ -60,6 +60,8 @@ enabled_skills: # Optional list of skills available when this a inject_skill_instructions: true # Inject a short hint pointing the model at `skill__list` when skills are enabled # (default: true). Suppressed automatically when no skills are available. skill_instructions: null # Custom text for the skill hint (optional; uses built-in default if null) +enabled_macros: # Optional list of macros invocable when this agent is active in the REPL. + - generate-commit-message # An empty list disables all macros. Omit to inherit the role/global default. memory: null # Per-agent memory override (default: inherit). Set to `false` to disable memory # for this agent regardless of workspace/global presence. See the Memory wiki page. diff --git a/config.example.yaml b/config.example.yaml index c93a509..247333a 100644 --- a/config.example.yaml +++ b/config.example.yaml @@ -169,6 +169,21 @@ inject_skill_instructions: true # Inject a short hint pointing the model at `s # effective enabled skill set is non-empty (default: true). skill_instructions: null # Custom text used for the skill hint when injected. If null, uses built-in default. +# ---- Macros ---- +# Macros are Coyote's custom commands: named sequences of REPL commands and prompts, invoked directly by name +# (a macro file named `review.yaml` runs as `.review [args]`; built-in commands always win a name collision). +# Workspace-local macros in `.coyote/macros/` shadow same-named global macros (skip them with --no-workspace-macros). +# See the [Macros documentation](https://github.com/Dark-Alex-17/coyote/wiki/Macros) for more details. +enabled_macros: null # Which macros are invocable by default (no role/agent/session active). null = all visible. + # An empty list means NO macros are invocable. Accepts either a YAML list or a + # comma-separated string. Roles, agents, and sessions may define their own + # `enabled_macros`; the most specific active one wins (session > agent > role > global). + # Example (list form): + # enabled_macros: + # - generate-commit-message + # Example (comma-separated form): + # enabled_macros: generate-commit-message,review + # ---- Auto-Continue (Todo System) ---- # The auto-continue system provides built-in task tracking for improved reliability. # When enabled, the model can create todo lists and the system will automatically diff --git a/config.macro.example.yaml b/config.macro.example.yaml index ba83d07..341e8b4 100644 --- a/config.macro.example.yaml +++ b/config.macro.example.yaml @@ -1,3 +1,13 @@ +description: Demonstrates every macro field # Optional; shown in `.list macros` and in `.` tab-completion. +isolated: true # Optional; 'true' by default. When true, steps run in a forked, + # throwaway context: the exchange and any `.role`/`.model` switches + # vanish when the macro ends. When false, steps run on the LIVE + # session exactly as if you typed them: prompts are recorded, and + # mutating steps (e.g. `.role`, `.model`) PERSIST after the macro + # finishes -- by design. Steps are fail-fast in both modes: an error + # aborts the remaining steps, but completed steps' effects remain. + # A non-isolated macro step cannot invoke another macro, and a + # `.exit` step never exits the REPL. variables: # A list of positional variables that the macro uses - name: positional_1 # The name of the positional variable. default: null # Since no default value is provided, this argument is required; 'null' by default diff --git a/config.role.example.md b/config.role.example.md index ff66eaa..3fabd63 100644 --- a/config.role.example.md +++ b/config.role.example.md @@ -24,6 +24,9 @@ enabled_skills: # Skills available when this role is activ inject_skill_instructions: true # Inject a short hint pointing the model at `skill__list` when skills are enabled # (default: true). Suppressed automatically when no skills are available. skill_instructions: null # Custom text for the skill hint (optional; uses built-in default if null) +enabled_macros: # Macros invocable when this role is active. Accepts a YAML list (preferred) + - generate-commit-message # or a comma-separated string (e.g. `enabled_macros: generate-commit-message,review`). + # An empty list disables all macros. Omit to inherit the global default. memory: null # Per-role memory override (default: inherit). Set to `false` to disable memory # when this role is active. See the Memory wiki page. diff --git a/graph.example.yaml b/graph.example.yaml index f1ea9ae..ece3cda 100644 --- a/graph.example.yaml +++ b/graph.example.yaml @@ -68,6 +68,9 @@ enabled_skills: inject_skill_instructions: true # Inject a hint pointing the model at `skill__list`. Defaults to true; suppressed # automatically when no skills are available. skill_instructions: null # Custom text for the skill hint (optional; uses the built-in default if omitted). +# Note: `enabled_macros` is NOT a graph setting. Graph nodes never dispatch REPL +# commands, so the field is silently ignored in graph configs; scope macros via +# the global config, roles, agents, or sessions instead. conversation_starters: # Suggested prompts surfaced in the UI - "Research the current state of WebAssembly outside the browser"