From 7e8dc41308a41c2c860ff45e1413c5a6710855b2 Mon Sep 17 00:00:00 2001 From: Alex Clarke Date: Mon, 18 May 2026 15:08:39 -0600 Subject: [PATCH] feat: documented the new .install commands --- MCP-Servers.md | 6 ++++++ Macros.md | 4 ++++ REPL.md | 22 ++++++++++++++++++++++ Tools.md | 5 +++++ 4 files changed, 37 insertions(+) diff --git a/MCP-Servers.md b/MCP-Servers.md index 54573b2..50b46fe 100644 --- a/MCP-Servers.md +++ b/MCP-Servers.md @@ -134,6 +134,12 @@ Loki ships with a `functions/mcp.json` file that includes some useful MCP server * [slack](https://github.com/korotovsky/slack-mcp-server) - Interact with Slack * [ddg-search](https://github.com/nickclyde/duckduckgo-mcp-server) - Perform web searches with the DuckDuckGo search engine +The `mcp.json` file is created from a bundled template on first run and is never overwritten afterward. It is your own +configuration to edit freely. To discard your changes and restore the bundled template (for example, to pick up new +default servers after a Loki update), run `loki --install mcp_config` (or `.install mcp_config` in the REPL). **This is +destructive:** it replaces your entire `mcp.json`, including your configured servers and any secret references in them, +with the bundled template. + # Loki Configuration MCP servers, like tools, can be used in a handful of contexts: * Inside a session diff --git a/Macros.md b/Macros.md index d01314c..4f79994 100644 --- a/Macros.md +++ b/Macros.md @@ -92,3 +92,7 @@ on how to make your own macros, so be sure to check out the [built-in macro defi looking for more examples. * `generate-commit-message` - Generate a Git commit message based on the staged changes in the current directory + +Built-in macros are written to your macros directory on first run and never overwritten afterward, so your edits are +preserved across Loki updates. To discard local changes and reinstall the built-in macros from the current Loki build, +run `loki --install macros` (or `.install macros` in the REPL). Macros you created yourself are not affected. diff --git a/REPL.md b/REPL.md index cb2c825..d367edb 100644 --- a/REPL.md +++ b/REPL.md @@ -232,6 +232,28 @@ directory or file corresponding to the target entity. You can use it to delete t * `.delete rag` - Delete select RAGs * `.delete agent-data` - Delete select agent's configurations and all tools +## `.install` - Reinstall bundled assets +Loki's built-in agents, macros, and tool functions (and an MCP config template) are written to your configuration +directory on first run and are **not** overwritten afterward, so your local edits survive Loki updates. The `.install` +command force-overwrites a category of bundled assets with the versions packaged in the current Loki build. This is useful +when an update ships improved built-ins you want to adopt. + +| Command | Description | +|-----------------------|----------------------------------------------------------------------| +| `.install agents` | Reinstall the built-in agents | +| `.install macros` | Reinstall the built-in macros | +| `.install functions` | Reinstall the built-in tool functions (leaves your `mcp.json` alone) | +| `.install mcp_config` | Replace `mcp.json` with the bundled template (see warning below) | + +The same operation is available from the command line: `loki --install ` (e.g. `loki --install agents`). + +`.install` prompts for confirmation before overwriting anything. Assets you created yourself are never touched. Only +Loki's own bundled assets are replaced. + +**Warning:** `.install mcp_config` is destructive in a way the others are not. It replaces your entire `mcp.json` +(your configured MCP servers and any secret references in them) with Loki's bundled template. The other categories +only overwrite Loki's built-in assets and leave your custom ones alone. + ## `.info` - Display information about the current mode The `.info` command provides useful information about different modes that Loki may be operating in. It's helpful if you want a quick understanding of the system info, a role's configuration, an agent's configuration, etc. diff --git a/Tools.md b/Tools.md index 996a092..11ddf88 100644 --- a/Tools.md +++ b/Tools.md @@ -47,6 +47,11 @@ be enabled/disabled can be found in the [Configuration](#configuration) section Details on what configuration, if any, is necessary for each tool can be found inside the tool file definition itself. +Built-in tools are written to your functions directory on first run and never overwritten afterward, so your edits are +preserved across Loki updates. To discard local changes and reinstall the built-in tools from the current Loki build, +run `loki --install functions` (or `.install functions` in the REPL). Tools you created yourself are not affected, and +your `mcp.json` is left untouched. Use `loki --install mcp_config` to reset that separately. + # Configuration Tools can be used in a handful of contexts: * Inside a session