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.

For more information on Loki's REPL, refer to the REPL documentation.

Quick Links

Macro Definition
- Step Definitions
- Macro Variables
Built-In Macros

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:

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

steps:
  - .file `git diff` -- generate git commit message

Usage:

$ 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 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:

$ 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

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:

$ 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 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 if you're looking for more examples.

generate-commit-message - Generate a Git commit message based on the staged changes in the current directory

4.2 KiB Raw Blame History