From 23e2c1144fe0f0d8c4eea18954e57a47436f2093 Mon Sep 17 00:00:00 2001
From: Alex Clarke <alex.j.tusa@gmail.com>
Date: Fri, 7 Nov 2025 13:40:48 -0700
Subject: [PATCH] docs: created docs for Loki's macro system

---
 docs/MACROS.md | 103 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 103 insertions(+)
 create mode 100644 docs/MACROS.md

diff --git a/docs/MACROS.md b/docs/MACROS.md
new file mode 100644
index 0000000..a90aafe
--- /dev/null
+++ b/docs/MACROS.md
@@ -0,0 +1,103 @@
+# Macros
+Macros are essentially Loki "scripts"; that is, a predefined sequence of REPL commands that automate repetitive tasks or
+workflows. Macros run in isolated environments, ensuring that the macros don't inherit any pre-existing role, session, 
+RAG, or agent state, and they will not affect your current context. 
+
+This isolation ensures that your workspace remains clean and unaffected by macro operations.
+
+![Macro Example](./images/macros/macros-example.gif)
+
+For more information on Loki's REPL, refer to the [REPL](./REPL.md) documentation.
+
+## Quick Links
+<!--toc:start-->
+- [Macro Definition](#macro-definition)
+  - [Step Definitions](#step-definitions)
+  - [Macro Variables](#macro-variables)
+- [Built-In Macros](#built-in-macros)
+<!--toc:end-->
+
+---
+
+## Macro Definition
+Macros are defined as YAML files in the `macros` subdirectory of your Loki configuration directory. The Loki configuration 
+directory can vary between systems, so to find the location of your macros config directory, you can use the following 
+command:
+
+```shell
+loki --info | grep 'macros_dir' | awk '{print $2}'
+```
+
+Macro definitions are broken into two parts: the `steps` of the macro, and an optional `variables` section that lets 
+users pass in variables to alter the behavior of the macro at runtime.
+
+### Step Definitions
+The step definitions for a macro are straightforward: They are simply the exact commands you would otherwise type in the
+REPL. 
+
+**Example: Macro to generate a git commit message**
+`macros/generate-commit-message.yaml`
+```yaml
+steps:
+  - .file `git diff` -- generate git commit message
+```
+Usage:
+```shell
+$ loki --macro generate-commit-message
+>> .file `git diff` -- generate a git commit message
+Add documentation on macros
+```
+
+For a full example configuration, refer to the [example macro configuration file](../config.macro.example.yaml) in the root of this project.
+
+### Macro Variables
+Sometimes it's useful to be able to modify the behavior of a macro at runtime. This is achieved with the `variables` 
+array of the macro definition.
+
+To pass variables to a macro, since they are just Loki scripts, the syntax is the same as it is for any other scripting 
+language: You just pass them alongside your invocation.
+
+**Example:**
+```shell
+$ loki --macro example-variable-macro first_argument second_argument
+```
+
+Each variable in the `variables` array has the following properties:
+* `name` (Required): the name of the variable, which can be referenced in the actual steps of the macro using the 
+  `{{name}}` syntax.
+* `default` (Optional): A default value for the variable if no value is specified. If no default value is defined, and 
+  no value is provided for the variable at runtime, Loki will error out.
+* `rest` (Optional, Boolean): When set to `true`, this variable will collect all remaining arguments passed to the 
+  macro. This behavior is only applicable when the variable is the last variable in the list. By default, this is 
+  `false`.
+
+The `variables` array is order-dependent; that is to say that all arguments passed to the macro are positional. So be
+careful about the ordering if that is important to your macro's invocation.
+
+**Example: Simple variable example to invoke an agent**
+`macros/invoke-agent.yaml`
+```yaml
+variables:
+  - name: agent                 # No default value means this must be defined at runtime
+  - name: args
+    rest: true                  # All remaining arguments to the macro are collected into this variable
+    default: What can you do?   # This is used if no value is passed at runtime
+steps:
+  - .agent {{agent}}
+  - '{{args}}'
+```
+Usage:
+```shell
+$ loki --macro invoke-agent sql
+# or
+$ loki --macro invoke-agent sql What tables are available?
+```
+
+For a full example configuration, refer to the [example macro configuration file](../config.macro.example.yaml) in the root of this project.
+
+## Built-In Macros
+Loki comes packaged with some useful built-in macros. These are also good examples if you're looking for more examples 
+on how to make your own macros, so be sure to check out the [built-in macro definitions](../assets/macros) if you're 
+looking for more examples.
+
+* `generate-commit-message` - Generate a Git commit message based on the staged changes in the current directory