build: Removed unnecessary Language import for Windows systems

Decompose God-Config struct into focused state architecture with MCP SSE support and comprehensive tests

.github/PULL_REQUEST_TEMPLATE/pull_request_template.md

@@ -0,0 +1,11 @@
+### AI assistance (if any):
+- List tools here and files touched by them
+
+### Authorship & Understanding
+
+- [ ] I wrote or heavily modified this code myself
+- [ ] I understand how it works end-to-end
+- [ ] I can maintain this code in the future
+- [ ] No undisclosed AI-generated code was used
+- [ ] If AI assistance was used, it is documented below
+

.gitignore

@@ -2,5 +2,6 @@
 /tmp
 /.env
 !cli/**
-/.idea/
+.idea/
 /loki.iml
+/.idea/

.idea/.gitignore

@@ -1,10 +0,0 @@
-# Default ignored files
-/shelf/
-/workspace.xml
-# Editor-based HTTP Client requests
-/httpRequests/
-# Datasource local storage ignored files
-/dataSources/
-/dataSources.local.xml
-# Zeppelin ignored files
-/ZeppelinRemoteNotebooks/

.loki-project.json

@@ -0,0 +1 @@
+{"type":"rust","build":"cargo build","test":"cargo test","check":"cargo check","_detected_by":"heuristic","_cached_at":"2026-04-13T13:36:33-06:00"}

CHANGELOG.md

@@ -1,3 +1,117 @@
+## v0.3.0 (2026-04-02)
+
+### Feat
+
+- Added `todo__clear` function to the todo system and updated REPL commands to have a .clear todo as well for significant changes in agent direction
+- Added available tools to prompts for sisyphus and code-reviewer agent families
+- Added available tools to coder prompt
+- Improved token efficiency when delegating from sisyphus -> coder
+- modified sisyphus agents to use the new ddg-search MCP server for web searches instead of built-in model searches
+- Added support for specifying a custom response to multiple-choice prompts when nothing suits the user's needs
+- Supported theming in the inquire prompts in the REPL
+- Added the duckduckgo-search MCP server for searching the web (in addition to the built-in tools for web searches)
+- Support for Gemini OAuth
+- Support authenticating or refreshing OAuth for supported clients from within the REPL
+- Allow first-runs to select OAuth for supported providers
+- Support OAuth authentication flows for Claude
+- Improved MCP server spinup and spindown when switching contexts or settings in the REPL: Modify existing config rather than stopping all servers always and re-initializing if unnecessary
+- Allow the explore agent to run search queries for understanding docs or API specs
+- Allow the oracle to perform web searches for deeper research
+- Added web search support to the main sisyphus agent to answer user queries
+- Created a CodeRabbit-style code-reviewer agent
+- Added configuration option in agents to indicate the timeout for user input before proceeding (defaults to 5 minutes)
+- Added support for sub-agents to escalate user interaction requests from any depth to the parent agents for user interactions
+- built-in user interaction tools to remove the need for the list/confirm/etc prompts in prompt tools and to enhance user interactions in Loki
+- Experimental update to sisyphus to use the new parallel agent spawning system
+- Added an agent configuration property that allows auto-injecting sub-agent spawning instructions (when using the built-in sub-agent spawning system)
+- Auto-dispatch support of sub-agents and support for the teammate pattern between subagents
+- Full passive task queue integration for parallelization of subagents
+- Implemented initial scaffolding for built-in sub-agent spawning tool call operations
+- Initial models for agent parallelization
+- Added interactive prompting between the LLM and the user in Sisyphus using the built-in Bash utils scripts
+
+### Fix
+
+- Clarified user text input interaction
+- recursion bug with similarly named Bash search functions in the explore agent
+- updated the error for unauthenticated oauth to include the REPL .authenticated command
+- Corrected a bug in the coder agent that wasn't outputting a summary of the changes made, so the parent Sisyphus agent has no idea if the agent worked or not
+- Claude code system prompt injected into claude requests to make them valid once again
+- Do not inject tools when models don't support them; detect this conflict before API calls happen
+- The REPL .authenticate command works from within sessions, agents, and roles with pre-configured models
+- Implemented the path normalization fix for the oracle and explore agents
+- Updated the atlassian MCP server endpoint to account for future deprecation
+- Fixed a bug in the coder agent that was causing the agent to create absolute paths from the current directory
+- the updated regex for secrets injection broke MCP server secrets interpolation because the regex greedily matched on new lines, replacing too much content. This fix just ignores commented out lines in YAML files by skipping commented out lines.
+- Don't try to inject secrets into commented-out lines in the config
+- Removed top_p parameter from some agents so they can work across model providers
+- Improved sub-agent stdout and stderr output for users to follow
+- Inject agent variables into environment variables for global tool calls when invoked from agents to modify global tool behavior
+- Removed the unnecessary execute_commands tool from the oracle agent
+- Added auto_confirm to the coder agent so sub-agent spawning doesn't freeze
+- Fixed a bug in the new supervisor and todo built-ins that was causing errors with OpenAI models
+- Added condition to sisyphus to always output a summary to clearly indicate completion
+- Updated the sisyphus prompt to explicitly tell it to delegate to the coder agent when it wants to write any code at all except for trivial changes
+- Added back in the auto_confirm variable into sisyphus
+- Removed the now unnecessary is_stale_response that was breaking auto-continuing with parallel agents
+- Bypassed enabled_tools for user interaction tools so if function calling is enabled at all, the LLM has access to the user interaction tools when in REPL mode
+- When parallel agents run, only write to stdout from the parent and only display the parent's throbber
+- Forgot to implement support for failing a task and keep all dependents blocked
+- Clean up orphaned sub-agents when the parent agent
+- Fixed the bash prompt utils so that they correctly show output when being run by a tool invocation
+- Forgot to automatically add the bidirectional communication back up to parent agents from sub-agents (i.e. need to be able to check inbox and send messages)
+- Agent delegation tools were not being passed into the {{__tools__}} placeholder so agents weren't delegating to subagents
+
+### Refactor
+
+- Made the oauth module more generic so it can support loopback OAuth (not just manual)
+- Changed the default session name for Sisyphus to temp (to require users to explicitly name sessions they wish to save)
+- Updated the sisyphus agent to use the built-in user interaction tools instead of custom bash-based tools
+- Cleaned up some left-over implementation stubs
+
+## v0.2.0 (2026-02-14)
+
+### Feat
+
+- Simplified sisyphus prompt to improve functionality
+- Supported the injection of RAG sources into the prompt, not just via the `.sources rag` command in the REPL so models can directly reference the documents that supported their responses
+- Created the Sisyphus agent to make Loki function like Claude Code, Gemini, Codex, etc.
+- Created the Oracle agent to handle high-level architectural decisions and design questions about a given codebase
+- Updated the coder agent to be much more task-focused and to be delegated to by Sisyphus
+- Created the explore agent for exploring codebases to help answer questions
+- Use the official atlassian MCP server for the jira-helper agent
+- Created fs_glob to enable more targeted file exploration utilities
+- Created a new tool 'fs_grep' to search a given file's contents for relevant lines to reduce token usage for smaller models
+- Created the new fs_read tool to enable controlled reading of a file
+- Let agent level variables be defined to bypass guard protections for tool invocations
+- Implemented a built-in task management system to help smaller LLMs complete larger multistep tasks and minimize context drift
+- Improved tool and MCP invocation error handling by returning stderr to the model when it is available
+- Added variable interpolation for conversation starters in agents
+- Implemented retry logic for failed tool invocations so the LLM can learn from the result and try again; Also implemented chain loop detection to prevent loops
+- Added gemini-3-pro to the supported vertexai models
+- Added an environment variable that lets users bypass guard operations in bash scripts. This is useful for agent routing
+- Added support for thought-signatures for Gemini 3+ models
+
+### Fix
+
+- Improved continuation prompt to not make broad todo-items
+- Allow auto-continuation to work in agents after a session is compressed and if there's still unfinish items in the to-do list
+- fs_ls and fs_cat outputs should always redirect to "$LLM_OUTPUT" including on errors.
+- Claude tool calls work incorrectly when tool doesn't require any arguments or flags; would provide an empty JSON object or error on no args
+- Fixed a bug where --agent-variable values were not being passed to the agents
+
+## v0.1.3 (2025-12-13)
+
+### Feat
+
+- Improved MCP implementation to minimize the tokens needed to utilize it so it doesn't quickly overwhelm the token space for a given model
+
+## v0.1.2 (2025-11-08)
+
+### Refactor
+
+- Gave the GitHub MCP server a default placeholder value that doesn't require the vault
+
 ## v0.1.1 (2025-11-08)
 
 ## v0.1.0 (2025-11-07)

CONTRIBUTING.md

@@ -48,7 +48,8 @@ cz commit
 1. Clone this repo
 2. Run `cargo test` to set up hooks
 3. Make changes
-4. Run the application using `make run` or `cargo run`
+4. Run the application using `just run` or `just run`
+   - Install `just` (`cargo install just`) if you haven't already to use the [justfile](./justfile) in this project.
 5. Commit changes. This will trigger pre-commit hooks that will run format, test and lint. If there are errors or 
    warnings from Clippy, please fix them.
 6. Push your code to a new branch named after the feature/bug/etc. you're adding. This will trigger pre-push hooks that 
@@ -75,6 +76,13 @@ Then, you can run workflows locally without having to commit and see if the GitH
 act -W .github/workflows/release.yml --input_type bump=minor
 ```
 
+ ## Authorship Policy
+
+All code in this repository is written and reviewed by humans. AI-generated code (e.g., Copilot, ChatGPT,
+Claude, etc.) is not permitted unless explicitly disclosed and approved.
+
+Submissions must certify that the contributor understands and can maintain the code they submit.
+
 ## Questions? Reach out to me!
 If you encounter any questions while developing Loki, please don't hesitate to reach out to me at 
 alex.j.tusa@gmail.com. I'm happy to help contributors in any way I can, regardless of if they're new or experienced!

CREDITS.md

@@ -0,0 +1,31 @@
+# Credits
+
+## AIChat
+Loki originally started as a fork of the fantastic
+[AIChat CLI](https://github.com/sigoden/aichat). The initial goal was simply
+to fix a bug in how MCP servers worked with AIChat, allowing different MCP
+servers to be specified per agent. Since then, Loki has evolved far beyond
+its original scope and grown into a passion project with a life of its own.
+
+Today, Loki includes first-class MCP server support (for both local and remote
+servers), a built-in vault for interpolating secrets in configuration files,
+built-in agents and macros, dynamic tab completions, integrated custom
+functions (no external `argc` dependency), improved documentation, and much
+more with many more ideas planned for the future.
+
+Loki is now developed and maintained as an independent project. Full credit
+for the original foundation goes to the developers of the wonderful
+AIChat project.
+
+This project is not affiliated with or endorsed by the AIChat maintainers.
+
+## AIChat
+
+Loki originally began as a fork of [AIChat CLI](https://github.com/sigoden/aichat),
+created and maintained by the AIChat contributors.
+
+While Loki has since diverged significantly and is now developed as an
+independent project, its early foundation and inspiration came from the
+AIChat project.
+
+AIChat is licensed under the MIT License.

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "loki-ai"
-version = "0.1.1"
+version = "0.3.0"
 edition = "2024"
 authors = ["Alex Clarke <alex.j.tusa@gmail.com>"]
 description = "An all-in-one, batteries included LLM CLI Tool"
@@ -10,7 +10,7 @@ repository = "https://github.com/Dark-Alex-17/loki"
 categories = ["command-line-utilities"]
 readme = "README.md"
 license = "MIT"
-rust-version = "1.89.0"
+rust-version = "1.95.0"
 exclude = [".github", "CONTRIBUTING.md"]
 
 [dependencies]
@@ -18,10 +18,11 @@ anyhow = "1.0.69"
 bytes = "1.4.0"
 clap = { version = "4.5.40", features = ["cargo", "derive", "wrap_help"] }
 dirs = "6.0.0"
+dunce = "1.0.5"
 futures-util = "0.3.29"
-inquire = "0.7.0"
+inquire = "0.9.4"
 is-terminal = "0.4.9"
-reedline = "0.40.0"
+reedline = "0.47.0"
 serde = { version = "1.0.152", features = ["derive"] }
 serde_json = { version = "1.0.93", features = ["preserve_order"] }
 serde_yaml = "0.9.17"
@@ -33,11 +34,7 @@ tokio = { version = "1.34.0", features = [
   "rt-multi-thread",
   "full",
 ] }
-tokio-graceful = "0.2.2"
-tokio-stream = { version = "0.1.15", default-features = false, features = [
-  "sync",
-] }
-crossterm = "0.28.1"
+crossterm = "0.29.0"
 chrono = "0.4.23"
 bincode = { version = "2.0.0", features = [
   "serde",
@@ -50,7 +47,7 @@ nu-ansi-term = "0.50.0"
 async-trait = "0.1.74"
 textwrap = "0.16.0"
 ansi_colours = "1.2.2"
-reqwest-eventsource = "0.6.0"
+eventsource-stream = "0.2.3"
 log = "0.4.28"
 log4rs = { version = "1.4.0", features = ["file_appender"] }
 shell-words = "1.1.0"
@@ -58,20 +55,14 @@ sha2 = "0.10.8"
 unicode-width = "0.2.0"
 async-recursion = "1.1.1"
 http = "1.1.0"
-http-body-util = "0.1"
-hyper = { version = "1.0", features = ["full"] }
-hyper-util = { version = "0.1", features = ["server-auto", "client-legacy"] }
-time = { version = "0.3.36", features = ["macros"] }
 indexmap = { version = "2.2.6", features = ["serde"] }
 hmac = "0.12.1"
 aws-smithy-eventstream = "0.60.4"
 urlencoding = "2.1.3"
-unicode-segmentation = "1.11.0"
 json-patch = { version = "4.0.0", default-features = false }
 bitflags = "2.5.0"
 path-absolutize = "3.1.1"
 hnsw_rs = "0.3.0"
-rayon = "1.10.0"
 uuid = { version = "1.9.1", features = ["v4"] }
 scraper = { version = "0.23.1", default-features = false, features = [
   "deterministic",
@@ -88,23 +79,41 @@ duct = "1.0.0"
 argc = "1.23.0"
 strum_macros = "0.27.2"
 indoc = "2.0.6"
-rmcp = { version = "0.6.1", features = ["client", "transport-child-process"] }
+rmcp = { version = "1.5.0", features = [
+  "client",
+  "transport-child-process",
+  "transport-streamable-http-client-reqwest",
+  "reqwest-native-tls",
+] }
 num_cpus = "1.17.0"
-rustpython-parser = "0.4.0"
-rustpython-ast = "0.4.0"
+tree-sitter = "0.26.8"
+tree-sitter-python = "0.25.0"
+tree-sitter-typescript = "0.23"
 colored = "3.0.0"
 clap_complete = { version = "4.5.58", features = ["unstable-dynamic"] }
-gman = "0.2.3"
+gman = "0.4.1"
 clap_complete_nushell = "4.5.9"
+open = "5"
+rand = { version = "0.10.0", features = ["default"] }
+url = "2.5.8"
+self_update = { version = "0.44", default-features = false, features = [
+  "reqwest",
+  "rustls",
+  "archive-tar",
+  "compression-flate2",
+  "archive-zip",
+  "compression-zip-deflate",
+] }
 
 [dependencies.reqwest]
-version = "0.12.0"
+version = "0.13.3"
 features = [
   "json",
   "multipart",
+  "stream",
+  "form",
   "socks",
-  "rustls-tls",
-  "rustls-tls-native-roots",
+  "rustls",
 ]
 default-features = false
 
@@ -114,7 +123,7 @@ default-features = false
 features = ["parsing", "regex-onig", "plist-load"]
 
 [target.'cfg(target_os = "macos")'.dependencies]
-crossterm = { version = "0.28.1", features = ["use-dev-tty"] }
+crossterm = { version = "0.29.0", features = ["use-dev-tty"] }
 
 [target.'cfg(target_os = "linux")'.dependencies]
 arboard = { version = "3.3.0", default-features = false, features = [
@@ -126,7 +135,7 @@ arboard = { version = "3.3.0", default-features = false }
 
 [dev-dependencies]
 pretty_assertions = "1.4.0"
-rand = "0.9.0"
+serial_test = "3"
 
 [[bin]]
 name = "loki"

README.md

@@ -1,7 +1,6 @@
 # Loki: All-in-one, batteries-included LLM CLI Tool
 
 ![Test](https://github.com/Dark-Alex-17/loki/actions/workflows/ci.yaml/badge.svg)
-![LOC](https://tokei.rs/b1/github/Dark-Alex-17/loki?category=code)
 [![crates.io link](https://img.shields.io/crates/v/loki-ai.svg)](https://crates.io/crates/loki-ai)
 ![Release](https://img.shields.io/github/v/release/Dark-Alex-17/loki?color=%23c694ff)
 ![Crate.io downloads](https://img.shields.io/crates/d/loki-ai?label=Crate%20downloads)
@@ -11,66 +10,47 @@ Loki is an all-in-one, batteries-included, LLM CLI tool featuring Shell Assistan
 Agents, and More.
 
 It is designed to include a number of useful agents, roles, macros, and more so users can get up and running with Loki 
-in as little time as possible.
+in as little time as possible. You can also install entire bundles of agents, roles, macros, tools, and MCP servers from 
+any git repository — see [Sharing Configurations](#sharing-configurations).
 
-![Agent example](./docs/images/agents/sql.gif)
+![Agent example](https://raw.githubusercontent.com/wiki/Dark-Alex-17/loki/images/agents/sql.gif)
 
-Coming from [AIChat](https://github.com/sigoden/aichat)? Follow the [migration guide](./docs/AICHAT-MIGRATION.md) to get started.
+Coming from [AIChat](https://github.com/sigoden/aichat)? Follow the [migration guide](https://github.com/Dark-Alex-17/loki/wiki/AIChat-Migration) to get started.
 
 ## Quick Links
-* [AIChat Migration Guide](./docs/AICHAT-MIGRATION.md): Coming from AIChat? Follow the migration guide to get started.
-* [History](#history): A history of how Loki came to be.
+* [AIChat Migration Guide](https://github.com/Dark-Alex-17/loki/wiki/AIChat-Migration): Coming from AIChat? Follow the migration guide to get started.
 * [Installation](#install): Install Loki
 * [Getting Started](#getting-started): Get started with Loki by doing first-run setup steps.
-* [REPL](./docs/REPL.md): Interactive Read-Eval-Print Loop for conversational interactions with LLMs and Loki.
-  * [Custom REPL Prompt](./docs/REPL-PROMPT.md): Customize the REPL prompt to provide useful contextual information.
-* [Vault](./docs/VAULT.md): Securely store and manage sensitive information such as API keys and credentials.
-* [Shell Integrations](./docs/SHELL-INTEGRATIONS.md): Seamlessly integrate Loki with your shell environment for enhanced command-line assistance.
-* [Function Calling](./docs/function-calling/TOOLS.md#Tools): Leverage function calling capabilities to extend Loki's functionality with custom tools
-    * [Creating Custom Tools](./docs/function-calling/CUSTOM-TOOLS.md): You can create your own custom tools to enhance Loki's capabilities.
-        * [Create Custom Python Tools](./docs/function-calling/CUSTOM-TOOLS.md#custom-python-based-tools)
-        * [Create Custom Bash Tools](./docs/function-calling/CUSTOM-BASH-TOOLS.md)
-            * [Bash Prompt Utilities](./docs/function-calling/BASH-PROMPT-HELPERS.md)
-* [First-Class MCP Server Support](./docs/function-calling/MCP-SERVERS.md): Easily connect and interact with MCP servers for advanced functionality.
-* [Macros](./docs/MACROS.md): Automate repetitive tasks and workflows with Loki "scripts" (macros).
-* [RAG](./docs/RAG.md): Retrieval-Augmented Generation for enhanced information retrieval and generation.
-* [Sessions](/docs/SESSIONS.md): Manage and persist conversational contexts and settings across multiple interactions.
-* [Roles](./docs/ROLES.md): Customize model behavior for specific tasks or domains.
-* [Agents](/docs/AGENTS.md): Leverage AI agents to perform complex tasks and workflows.
-* [Environment Variables](./docs/ENVIRONMENT-VARIABLES.md): Override and customize your Loki configuration at runtime with environment variables.
-* [Client Configurations](./docs/clients/CLIENTS.md): Configuration instructions for various LLM providers.
-    * [Patching API Requests](./docs/clients/PATCHES.md): Learn how to patch API requests for advanced customization.
-* [Custom Themes](./docs/THEMES.md): Change the look and feel of Loki to your preferences with custom themes.
-
----
-
-## History
-Loki originally started as a fork of the fantastic [AIChat CLI](https://github.com/sigoden/aichat). The purpose was to 
-simply fix a bug in how MCP servers worked with AIChat so that I could specify different ones for agents. However, it 
-has since evolved far beyond that and become a passion project with a life of its own!
-
-Loki now has first class MCP server support (with support for local and remote servers alike), a built-in vault for 
-interpolating secrets in configuration files, built-in agents, built-in macros, dynamic tab completions, integrated
-custom functions (no `argc` dependency), improved documentation, and much more with many more plans for the future!
-
-The original kudos goes out to all the developers of the wonderful AIChat project!
-
----
+* [Sharing Configurations](https://github.com/Dark-Alex-17/loki/wiki/Sharing-Configurations): Install bundles of agents, roles, macros, tools, and MCP servers from any git repo, and share your own.
+* [REPL](https://github.com/Dark-Alex-17/loki/wiki/REPL): Interactive Read-Eval-Print Loop for conversational interactions with LLMs and Loki.
+  * [Custom REPL Prompt](https://github.com/Dark-Alex-17/loki/wiki/REPL-Prompt): Customize the REPL prompt to provide useful contextual information.
+* [Vault](https://github.com/Dark-Alex-17/loki/wiki/Vault): Securely store and manage sensitive information such as API keys and credentials.
+* [Shell Integrations](https://github.com/Dark-Alex-17/loki/wiki/Shell-Integrations): Seamlessly integrate Loki with your shell environment for enhanced command-line assistance.
+* [Function Calling](https://github.com/Dark-Alex-17/loki/wiki/Tools): Leverage function calling capabilities to extend Loki's functionality with custom tools
+    * [Creating Custom Tools](https://github.com/Dark-Alex-17/loki/wiki/Custom-Tools): You can create your own custom tools to enhance Loki's capabilities.
+        * [Create Custom Python Tools](https://github.com/Dark-Alex-17/loki/wiki/Custom-Tools#custom-python-based-tools)
+        * [Create Custom TypeScript Tools](https://github.com/Dark-Alex-17/loki/wiki/Custom-Tools#custom-typescript-based-tools)
+        * [Create Custom Bash Tools](https://github.com/Dark-Alex-17/loki/wiki/Custom-Bash-Tools)
+            * [Bash Prompt Utilities](https://github.com/Dark-Alex-17/loki/wiki/Bash-Prompt-Helpers)
+* [First-Class MCP Server Support](https://github.com/Dark-Alex-17/loki/wiki/MCP-Servers): Easily connect and interact with MCP servers for advanced functionality.
+* [Macros](https://github.com/Dark-Alex-17/loki/wiki/Macros): Automate repetitive tasks and workflows with Loki "scripts" (macros).
+* [RAG](https://github.com/Dark-Alex-17/loki/wiki/RAG): Retrieval-Augmented Generation for enhanced information retrieval and generation.
+* [Sessions](https://github.com/Dark-Alex-17/loki/wiki/Sessions): Manage and persist conversational contexts and settings across multiple interactions.
+* [Roles](https://github.com/Dark-Alex-17/loki/wiki/Roles): Customize model behavior for specific tasks or domains.
+* [Agents](https://github.com/Dark-Alex-17/loki/wiki/Agents): Leverage AI agents to perform complex tasks and workflows, including sub-agent spawning, teammate messaging, and user interaction tools.
+    * [Graph Agents](https://github.com/Dark-Alex-17/loki/wiki/Graph-Agents): Define an agent as a declarative, YAML-driven workflow. A directed graph of typed nodes (LLM calls, scripts, approvals, user input, RAG retrieval, sub-agent spawns).
+* [Todo System](https://github.com/Dark-Alex-17/loki/wiki/TODO-System): Built-in task tracking for improved LLM reliability with smaller models.
+* [Environment Variables](https://github.com/Dark-Alex-17/loki/wiki/Environment-Variables): Override and customize your Loki configuration at runtime with environment variables.
+* [Client Configurations](https://github.com/Dark-Alex-17/loki/wiki/Clients): Configuration instructions for various LLM providers.
+    * [Authentication (API Key & OAuth)](https://github.com/Dark-Alex-17/loki/wiki/Clients#authentication): Authenticate with API keys or OAuth for subscription-based access.
+    * [Patching API Requests](https://github.com/Dark-Alex-17/loki/wiki/Patches): Learn how to patch API requests for advanced customization.
+* [Custom Themes](https://github.com/Dark-Alex-17/loki/wiki/Themes): Change the look and feel of Loki to your preferences with custom themes.
+* [History](#history): A history of how Loki came to be.
 
 ## Prerequisites
 Loki requires the following tools to be installed on your system:
 * [jq](https://github.com/jqlang/jq)
     * `brew install jq`
-* [jira (optional)](https://github.com/ankitpokhrel/jira-cli/wiki/Installation) (For the `jira-helper` agent)
-    * `brew tap ankitpokhrel/jira-cli && brew install jira-cli`
-    * You'll need to [create a JIRA API token](https://id.atlassian.com/manage-profile/security/api-tokens) for authentication
-    * Then, save it as an environment variable to your shell profile:
-      ```sh
-      # ~/.bashrc or ~/.zshrc
-      export JIRA_API_TOKEN="your_jira_api_token_here"
-      ```
-    * Then run `jira init`, select installation type as `cloud`, and provide the required details to generate a config
-      file for the Jira CLI.
 * [usql](https://github.com/xo/usql) (For the `sql` agent)
     * `brew install xo/xo/usql`
 * [docker](https://docs.docker.com/engine/install/)
@@ -78,7 +58,7 @@ Loki requires the following tools to be installed on your system:
     * `curl -LsSf https://astral.sh/uv/install.sh | sh`
 
 These tools are used to provide various functionalities within Loki, such as document processing, JSON manipulation,
-interaction with Jira, and they are used within agents and tools.
+etc., and they are used within agents and tools.
 
 ## Install
 
@@ -150,6 +130,29 @@ To use a binary from the releases page on Linux/MacOS, do the following:
 3. Extract the binary with `tar -C /usr/local/bin -xzf loki-<arch>.tar.gz` (Note: This may require `sudo`)
 4. Now you can run `loki`!
 
+## Updating
+Loki can update itself in place to the latest GitHub release. Run `loki --update`
+for the newest release, or `loki --update v0.4.0` for a specific version:
+
+```shell
+loki --update
+loki --update v0.4.0
+```
+
+The same is available from within the REPL via `.update` and `.update v0.4.0`.
+
+If Loki was installed with a package manager, prefer that package manager so its
+records stay in sync with the binary on disk; i.e. `brew upgrade loki` for Homebrew,
+or `cargo install --locked loki-ai` for Cargo.
+
+When Loki detects a package-manager install it prints a warning and asks for
+confirmation. In a non-interactive shell (no TTY), pass `--force` to update
+anyway:
+
+```shell
+loki --update --force
+```
+
 ## Getting Started
 After installation, you can generate the configuration files and directories by simply running:
 
@@ -164,21 +167,25 @@ guide you through the process when you first attempt to access the vault. So, to
 loki --list-secrets
 ```
 
-### First Time Setup
-In order for Loki to function correctly, you'll need to add a few secrets to the Loki vault so the MCP servers can
-function.
+### Authentication
+Each client in your configuration needs authentication (with a few exceptions; e.g. ollama). Most clients use an API key
+(set via `api_key` in the config or through the [vault](https://github.com/Dark-Alex-17/loki/wiki/Vault)). For providers that support OAuth (e.g. Claude Pro/Max 
+subscribers, Google Gemini), you can authenticate with your existing subscription instead:
 
-**GitHub MCP Server:**
-* `GITHUB_PERSONAL_ACCESS_TOKEN` - A GitHub Personal Access Token with `repo` and `workflow` scopes.
-  See [Creating a GitHub Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
-
-#### Add the secrets to the Loki vault
-You can add the secrets to the Loki vault using the following commands (First time use will prompt you to create a vault 
-password file):
-```sh
-loki --add-secret GITHUB_PERSONAL_ACCESS_TOKEN
+```yaml
+# In your config.yaml
+clients:
+  - type: claude
+    auth: oauth # Indicate you want to authenticate with OAuth instead of an API key
 ```
 
+```sh
+loki --authenticate claude
+# Or via the REPL: .authenticate
+```
+
+For full details, see the [authentication documentation](https://github.com/Dark-Alex-17/loki/wiki/Clients#authentication).
+
 ### Tab-Completions
 You can also enable tab completions to make using Loki easier. To do so, add the following to your shell profile:
 ```shell
@@ -254,7 +261,7 @@ shown below:
 
 | Setting         | Description                                                                                                                                                                                                                                                                                                 |
 |-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `repl_prelude`  | This setting lets you specify a default `session` or `role` to use when starting Loki in [REPL](./docs/REPL.md) mode. <br>Values can be <ul><li>`role:<name>` to define a role</li><li>`session:<name>` to define a session</li><li>`<session>:<role>` to define both a session and a role to use</li></ul> |
+| `repl_prelude`  | This setting lets you specify a default `session` or `role` to use when starting Loki in [REPL](https://github.com/Dark-Alex-17/loki/wiki/REPL) mode. <br>Values can be <ul><li>`role:<name>` to define a role</li><li>`session:<name>` to define a session</li><li>`<session>:<role>` to define both a session and a role to use</li></ul> |
 | `cmd_prelude`   | This setting lets you specify a default `session` or `role` to use when running one-off queries in Loki via the CLI. <br>Values can be <ul><li>`role:<name>` to define a role</li><li>`session:<name>` to define a session</li><li>`<session>:<role>` to define both a session and a role to use</li></ul>  |
 | `agent_session` | This setting is used to specify a default session that all agents should start into, unless otherwise specified in the agent configuration. (e.g. `temp`, `default`)                                                                                                                                        |
 
@@ -272,5 +279,15 @@ The appearance of Loki can be modified using the following settings:
 | `user_agent`         | `null`        | The name of the `User-Agent` that should be passed in the `User-Agent` header on all requests to model providers |
 | `save_shell_history` | `true`        | Enables or disables REPL command history                                                                         |
 
+---
+
+## History
+
+Loki began as a fork of [AIChat CLI](https://github.com/sigoden/aichat) and has since evolved into an independent project.
+
+See [CREDITS.md](./CREDITS.md) for full attribution and background.
+
+---
+
 ## Creator
-* [Alex Clarke](https://github.com/Dark-Alex-17)
+* [Alex Clarke](https://github.com/Dark-Alex-17)

assets/agents/.shared/utils.sh

@@ -0,0 +1,319 @@
+#!/usr/bin/env bash
+# Shared Agent Utilities - Minimal, focused helper functions
+set -euo pipefail
+
+#######################
+## PROJECT DETECTION ##
+#######################
+
+# Cache file name for detected project info
+_LOKI_PROJECT_CACHE=".loki-project.json"
+
+# Read cached project detection if valid
+# Usage: _read_project_cache "/path/to/project"
+# Returns: cached JSON on stdout (exit 0) or nothing (exit 1)
+_read_project_cache() {
+  local dir="$1"
+  local cache_file="${dir}/${_LOKI_PROJECT_CACHE}"
+
+  if [[ -f "${cache_file}" ]]; then
+    local cached
+    cached=$(cat "${cache_file}" 2>/dev/null) || return 1
+    if echo "${cached}" | jq -e '.type and .build != null and .test != null and .check != null' &>/dev/null; then
+      echo "${cached}"
+      return 0
+    fi
+  fi
+  return 1
+}
+
+# Write project detection result to cache
+# Usage: _write_project_cache "/path/to/project" '{"type":"rust",...}'
+_write_project_cache() {
+  local dir="$1"
+  local json="$2"
+  local cache_file="${dir}/${_LOKI_PROJECT_CACHE}"
+
+  echo "${json}" > "${cache_file}" 2>/dev/null || true
+}
+
+_detect_heuristic() {
+  local dir="$1"
+
+  # Rust
+  if [[ -f "${dir}/Cargo.toml" ]]; then
+    echo '{"type":"rust","build":"cargo build","test":"cargo test","check":"cargo check"}'
+    return 0
+  fi
+
+  # Go
+  if [[ -f "${dir}/go.mod" ]]; then
+    echo '{"type":"go","build":"go build ./...","test":"go test ./...","check":"go vet ./..."}'
+    return 0
+  fi
+
+  # Node.JS/Deno/Bun
+  if [[ -f "${dir}/deno.json" ]] || [[ -f "${dir}/deno.jsonc" ]]; then
+    echo '{"type":"deno","build":"deno task build","test":"deno test","check":"deno lint"}'
+    return 0
+  fi
+
+  if [[ -f "${dir}/package.json" ]]; then
+    local pm="npm"
+
+    [[ -f "${dir}/bun.lockb" ]] || [[ -f "${dir}/bun.lock" ]] && pm="bun"
+    [[ -f "${dir}/pnpm-lock.yaml" ]] && pm="pnpm"
+    [[ -f "${dir}/yarn.lock" ]] && pm="yarn"
+
+    echo "{\"type\":\"nodejs\",\"build\":\"${pm} run build\",\"test\":\"${pm} test\",\"check\":\"${pm} run lint\"}"
+    return 0
+  fi
+
+  # Python
+  if [[ -f "${dir}/pyproject.toml" ]] || [[ -f "${dir}/setup.py" ]] || [[ -f "${dir}/setup.cfg" ]]; then
+    local test_cmd="pytest"
+    local check_cmd="ruff check ."
+
+    if [[ -f "${dir}/poetry.lock" ]]; then
+      test_cmd="poetry run pytest"
+      check_cmd="poetry run ruff check ."
+    elif [[ -f "${dir}/uv.lock" ]]; then
+      test_cmd="uv run pytest"
+      check_cmd="uv run ruff check ."
+    fi
+
+    echo "{\"type\":\"python\",\"build\":\"\",\"test\":\"${test_cmd}\",\"check\":\"${check_cmd}\"}"
+    return 0
+  fi
+
+  # JVM (Maven)
+  if [[ -f "${dir}/pom.xml" ]]; then
+    echo '{"type":"java","build":"mvn compile","test":"mvn test","check":"mvn verify"}'
+    return 0
+  fi
+
+  # JVM (Gradle)
+  if [[ -f "${dir}/build.gradle" ]] || [[ -f "${dir}/build.gradle.kts" ]]; then
+    local gw="gradle"
+    [[ -f "${dir}/gradlew" ]] && gw="./gradlew"
+    echo "{\"type\":\"java\",\"build\":\"${gw} build\",\"test\":\"${gw} test\",\"check\":\"${gw} check\"}"
+    return 0
+  fi
+
+  # .NET / C#
+  if compgen -G "${dir}/*.sln" &>/dev/null || compgen -G "${dir}/*.csproj" &>/dev/null; then
+    echo '{"type":"dotnet","build":"dotnet build","test":"dotnet test","check":"dotnet build --warnaserrors"}'
+    return 0
+  fi
+
+  # C/C++ (CMake)
+  if [[ -f "${dir}/CMakeLists.txt" ]]; then
+    echo '{"type":"cmake","build":"cmake --build build","test":"ctest --test-dir build","check":"cmake --build build"}'
+    return 0
+  fi
+
+  # Ruby
+  if [[ -f "${dir}/Gemfile" ]]; then
+    local test_cmd="bundle exec rake test"
+    [[ -f "${dir}/Rakefile" ]] && grep -q "rspec" "${dir}/Gemfile" 2>/dev/null && test_cmd="bundle exec rspec"
+    echo "{\"type\":\"ruby\",\"build\":\"\",\"test\":\"${test_cmd}\",\"check\":\"bundle exec rubocop\"}"
+    return 0
+  fi
+
+  # Elixir
+  if [[ -f "${dir}/mix.exs" ]]; then
+    echo '{"type":"elixir","build":"mix compile","test":"mix test","check":"mix credo"}'
+    return 0
+  fi
+
+  # PHP
+  if [[ -f "${dir}/composer.json" ]]; then
+    echo '{"type":"php","build":"","test":"./vendor/bin/phpunit","check":"./vendor/bin/phpstan analyse"}'
+    return 0
+  fi
+
+  # Swift
+  if [[ -f "${dir}/Package.swift" ]]; then
+    echo '{"type":"swift","build":"swift build","test":"swift test","check":"swift build"}'
+    return 0
+  fi
+
+  # Zig
+  if [[ -f "${dir}/build.zig" ]]; then
+    echo '{"type":"zig","build":"zig build","test":"zig build test","check":"zig build"}'
+    return 0
+  fi
+
+  # Generic build systems (last resort before LLM)
+  if [[ -f "${dir}/justfile" ]] || [[ -f "${dir}/Justfile" ]]; then
+    echo '{"type":"just","build":"just build","test":"just test","check":"just lint"}'
+    return 0
+  fi
+
+  if [[ -f "${dir}/Makefile" ]] || [[ -f "${dir}/makefile" ]] || [[ -f "${dir}/GNUmakefile" ]]; then
+    echo '{"type":"make","build":"make build","test":"make test","check":"make lint"}'
+    return 0
+  fi
+
+  return 1
+}
+
+# Gather lightweight evidence about a project for LLM analysis
+# Usage: _gather_project_evidence "/path/to/project"
+# Returns: evidence string on stdout
+_gather_project_evidence() {
+  local dir="$1"
+  local evidence=""
+
+  evidence+="Root files and directories:"$'\n'
+  evidence+=$(ls -1 "${dir}" 2>/dev/null | head -50)
+  evidence+=$'\n\n'
+
+  evidence+="File extension counts:"$'\n'
+  evidence+=$(find "${dir}" -type f \
+    -not -path '*/.git/*' \
+    -not -path '*/node_modules/*' \
+    -not -path '*/target/*' \
+    -not -path '*/dist/*' \
+    -not -path '*/__pycache__/*' \
+    -not -path '*/vendor/*' \
+    -not -path '*/.build/*' \
+    2>/dev/null \
+    | sed 's/.*\.//' | sort | uniq -c | sort -rn | head -10)
+  evidence+=$'\n\n'
+
+  local config_patterns=("*.toml" "*.yaml" "*.yml" "*.json" "*.xml" "*.gradle" "*.gradle.kts" "*.cabal" "*.pro" "Makefile" "justfile" "Justfile" "Dockerfile" "Taskfile*" "BUILD" "WORKSPACE" "flake.nix" "shell.nix" "default.nix")
+  local found_configs=0
+
+  for pattern in "${config_patterns[@]}"; do
+    if [[ ${found_configs} -ge 5 ]]; then
+      break
+    fi
+
+    local files
+    files=$(find "${dir}" -maxdepth 1 -name "${pattern}" -type f 2>/dev/null)
+
+    while IFS= read -r f; do
+      if [[ -n "${f}" && ${found_configs} -lt 5 ]]; then
+        local basename
+        basename=$(basename "${f}")
+        evidence+="--- ${basename} (first 30 lines) ---"$'\n'
+        evidence+=$(head -30 "${f}" 2>/dev/null)
+        evidence+=$'\n\n'
+        found_configs=$((found_configs + 1))
+      fi
+    done <<< "${files}"
+  done
+
+  echo "${evidence}"
+}
+
+# LLM-based project detection fallback
+# Usage: _detect_with_llm "/path/to/project"
+# Returns: JSON on stdout or empty (exit 1)
+_detect_with_llm() {
+  local dir="$1"
+  local evidence
+  evidence=$(_gather_project_evidence "${dir}")
+  local prompt
+  prompt=$(cat <<-EOF
+
+		Analyze this project directory and determine the project type, primary language, and the correct shell commands to build, test, and check (lint/typecheck) it.
+
+		EOF
+	)
+  prompt+=$'\n'"${evidence}"$'\n'
+  prompt+=$(cat <<-EOF
+
+		Respond with ONLY a valid JSON object. No markdown fences, no explanation, no extra text.
+		The JSON must have exactly these 4 keys:
+		{"type":"<language>","build":"<build command>","test":"<test command>","check":"<lint or typecheck command>"}
+
+		Rules:
+		- "type" must be a single lowercase word (e.g. rust, go, python, nodejs, java, ruby, elixir, cpp, c, zig, haskell, scala, kotlin, dart, swift, php, dotnet, etc.)
+		- If a command doesn't apply to this project, use an empty string, ""
+		- Use the most standard/common commands for the detected ecosystem
+		- If you detect a package manager lockfile, use that package manager (e.g. pnpm over npm)
+		EOF
+	)
+
+  local llm_response
+  llm_response=$(loki --no-stream "${prompt}" 2>/dev/null) || return 1
+
+  llm_response=$(echo "${llm_response}" | sed 's/^```json//;s/^```//;s/```$//' | tr -d '\n' | sed 's/^[[:space:]]*//')
+  llm_response=$(echo "${llm_response}" | grep -o '{[^}]*}' | head -1)
+
+  if echo "${llm_response}" | jq -e '.type and .build != null and .test != null and .check != null' &>/dev/null; then
+    echo "${llm_response}" | jq -c '{type: (.type // "unknown"), build: (.build // ""), test: (.test // ""), check: (.check // "")}'
+    return 0
+  fi
+
+  return 1
+}
+
+# Detect project type and return build/test commands
+# Uses: cached result -> fast heuristics -> LLM fallback
+detect_project() {
+  local dir="${1:-.}"
+
+  local cached
+  if cached=$(_read_project_cache "${dir}"); then
+    echo "${cached}" | jq -c '{type, build, test, check}'
+    return 0
+  fi
+
+  local result
+  if result=$(_detect_heuristic "${dir}"); then
+    local enriched
+    enriched=$(echo "${result}" | jq -c '. + {"_detected_by":"heuristic","_cached_at":"'"$(date -Iseconds)"'"}')
+
+    _write_project_cache "${dir}" "${enriched}"
+
+    echo "${result}"
+    return 0
+  fi
+
+  if result=$(_detect_with_llm "${dir}"); then
+    local enriched
+    enriched=$(echo "${result}" | jq -c '. + {"_detected_by":"llm","_cached_at":"'"$(date -Iseconds)"'"}')
+
+    _write_project_cache "${dir}" "${enriched}"
+
+    echo "${result}"
+    return 0
+  fi
+
+  echo '{"type":"unknown","build":"","test":"","check":""}'
+}
+
+###########################
+## FILE SEARCH UTILITIES ##
+###########################
+
+_search_files() {
+  local pattern="$1"
+  local dir="${2:-.}"
+  
+  find "${dir}" -type f -name "${pattern}" \
+    -not -path '*/target/*' \
+    -not -path '*/node_modules/*' \
+    -not -path '*/.git/*' \
+    -not -path '*/dist/*' \
+    -not -path '*/__pycache__/*' \
+    2>/dev/null | head -25
+}
+
+get_tree() {
+  local dir="${1:-.}"
+  local depth="${2:-3}"
+  
+  if command -v tree &>/dev/null; then
+    tree -L "${depth}" --noreport -I 'node_modules|target|dist|.git|__pycache__|*.pyc' "${dir}" 2>/dev/null || find "${dir}" -maxdepth "${depth}" -type f | head -50
+  else
+    find "${dir}" -maxdepth "${depth}" -type f \
+      -not -path '*/target/*' \
+      -not -path '*/node_modules/*' \
+      -not -path '*/.git/*' \
+      2>/dev/null | head -50
+  fi
+}

assets/agents/code-reviewer/README.md

@@ -0,0 +1,36 @@
+# Code Reviewer
+
+A CodeRabbit-style code review orchestrator that coordinates per-file reviews and synthesizes findings into a unified 
+report.
+
+This agent acts as the manager for the review process, delegating actual file analysis to **[File Reviewer](../file-reviewer/README.md)** 
+agents while handling coordination and final reporting.
+
+## Features
+
+- 🤖 **Orchestration**: Spawns parallel reviewers for each changed file.
+- 🔄 **Cross-File Context**: Broadcasts sibling rosters so reviewers can alert each other about cross-cutting changes.
+- 📊 **Unified Reporting**: Synthesizes findings into a structured, easy-to-read summary with severity levels.
+- ⚡ **Parallel Execution**: Runs reviews concurrently for maximum speed.
+
+## Pro-Tip: Use an IDE MCP Server for Improved Performance
+Many modern IDEs now include MCP servers that let LLMs perform operations within the IDE itself and use IDE tools. Using
+an IDE's MCP server dramatically improves the performance of coding agents. So if you have an IDE, try adding that MCP
+server to your config (see the [MCP Server docs](../../../docs/function-calling/MCP-SERVERS.md) to see how to configure
+them), and modify the agent definition to look like this:
+
+```yaml
+# ...
+
+mcp_servers:
+  - jetbrains # The name of your configured IDE MCP server
+
+global_tools:
+  - fs_read.sh
+  - fs_grep.sh
+  - fs_glob.sh
+#  - execute_command.sh
+
+# ...
+```
+

assets/agents/code-reviewer/config.yaml

@@ -0,0 +1,127 @@
+name: code-reviewer
+description: CodeRabbit-style code reviewer - spawns per-file reviewers, synthesizes findings
+version: 1.0.0
+temperature: 0.1
+
+auto_continue: true
+max_auto_continues: 20
+inject_todo_instructions: true
+
+can_spawn_agents: true
+max_concurrent_agents: 10
+max_agent_depth: 2
+
+variables:
+  - name: project_dir
+    description: Project directory to review
+    default: '.'
+
+global_tools:
+  - fs_read.sh
+  - fs_grep.sh
+  - fs_glob.sh
+  - execute_command.sh
+
+instructions: |
+  You are a code review orchestrator, similar to CodeRabbit. You coordinate per-file reviews and produce a unified report.
+
+  ## Workflow
+
+  1. **Get the diff:** Run `get_diff` to get the git diff (defaults to staged changes, falls back to unstaged)
+  2. **Parse changed files:** Extract the list of files from the diff
+  3. **Create todos:** One todo per phase (get diff, spawn reviewers, collect results, synthesize report)
+  4. **Spawn file-reviewers:** One `file-reviewer` agent per changed file, in parallel
+  5. **Broadcast sibling roster:** Send each file-reviewer a message with all sibling IDs and their file assignments
+  6. **Collect all results:** Wait for each file-reviewer to complete
+  7. **Synthesize:** Combine all findings into a CodeRabbit-style report
+
+  ## Spawning File Reviewers
+
+  For each changed file, spawn a file-reviewer with a prompt containing:
+  - The file path
+  - The relevant diff hunk(s) for that file
+  - Instructions to review it
+
+  ```
+  agent__spawn --agent file-reviewer --prompt "Review the following diff for <file_path>:
+
+  <diff content for this file>
+
+  Focus on bugs, security issues, logic errors, and style. Use the severity format (🔴🟡🟢💡).
+  End with REVIEW_COMPLETE."
+  ```
+
+  ## Sibling Roster Broadcast
+
+  After spawning ALL file-reviewers (collecting their IDs), send each one a message with the roster:
+
+  ```
+  agent__send_message --to <agent_id> --message "SIBLING_ROSTER:
+  - <agent_id_1>: reviewing <file_1>
+  - <agent_id_2>: reviewing <file_2>
+  ...
+  Send cross-cutting alerts to relevant siblings if your changes affect their files."
+  ```
+
+  ## Diff Parsing
+
+  Split the diff by file. Each file's diff starts with `diff --git a/<path> b/<path>`. Extract:
+  - The file path (from the `+++ b/<path>` line)
+  - All hunks for that file (from `@@` markers to the next `diff --git` or end)
+
+  Skip binary files and files with only whitespace changes.
+
+  ## Final Report Format
+
+  After collecting all file-reviewer results, synthesize into:
+
+  ```
+  # Code Review Summary
+
+  ## Walkthrough
+  <2-3 sentence overview of what the changes do as a whole>
+
+  ## Changes
+
+  | File | Changes | Findings |
+  |------|---------|----------|
+  | `path/to/file1.rs` | <brief description> | 🔴 1 🟡 2 🟢 1 |
+  | `path/to/file2.rs` | <brief description> | 🟢 2 💡 1 |
+
+  ## Detailed Findings
+
+  ### `path/to/file1.rs`
+  <paste file-reviewer's findings here, cleaned up>
+
+  ### `path/to/file2.rs`
+  <paste file-reviewer's findings here, cleaned up>
+
+  ## Cross-File Concerns
+  <any cross-cutting issues identified by the teammate pattern>
+
+  ---
+  *Reviewed N files, found X critical, Y warnings, Z suggestions, W nitpicks*
+  ```
+
+  ## Edge Cases
+
+  - **Single file changed:** Still spawn one file-reviewer (for consistency), skip roster broadcast
+  - **Too many files (>10):** Group small files (< 20 lines changed) and review them together
+  - **No changes found:** Report "No changes to review" and exit
+  - **Binary files:** Skip with a note in the summary
+
+  ## Rules
+
+  1. **Always use `get_diff` first:** Don't assume what changed
+  2. **Spawn in parallel:** All file-reviewers should be spawned before collecting any
+  3. **Don't review code yourself:** Delegate ALL review work to file-reviewers
+  4. **Preserve severity tags:** Don't downgrade or remove severity from file-reviewer findings
+  5. **Include ALL findings:** Don't summarize away specific issues
+
+  ## Context
+  - Project: {{project_dir}}
+  - CWD: {{__cwd__}}
+  - Shell: {{__shell__}}
+  
+  ## Available Tools:
+  {{__tools__}}

assets/agents/code-reviewer/tools.sh

@@ -0,0 +1,478 @@
+#!/usr/bin/env bash
+set -eo pipefail
+
+# shellcheck disable=SC1090
+source "$LLM_PROMPT_UTILS_FILE"
+source "$LLM_ROOT_DIR/agents/.shared/utils.sh"
+
+# @env LLM_OUTPUT=/dev/stdout
+# @env LLM_AGENT_VAR_PROJECT_DIR=.
+# @describe Code review orchestrator tools
+
+_project_dir() {
+  local dir="${LLM_AGENT_VAR_PROJECT_DIR:-.}"
+  (cd "${dir}" 2>/dev/null && pwd) || echo "${dir}"
+}
+
+# @cmd Get git diff for code review. Returns staged changes, or unstaged if nothing is staged, or HEAD~1 diff if working tree is clean.
+# @option --base Optional base ref to diff against (e.g., "main", "HEAD~3", a commit SHA)
+get_diff() {
+  local project_dir
+  project_dir=$(_project_dir)
+  # shellcheck disable=SC2154
+  local base="${argc_base:-}"
+
+  local diff_output=""
+
+  if [[ -n "${base}" ]]; then
+    diff_output=$(cd "${project_dir}" && git diff "${base}" 2>&1) || true
+  else
+    diff_output=$(cd "${project_dir}" && git diff --cached 2>&1) || true
+
+    if [[ -z "${diff_output}" ]]; then
+      diff_output=$(cd "${project_dir}" && git diff 2>&1) || true
+    fi
+
+    if [[ -z "${diff_output}" ]]; then
+      diff_output=$(cd "${project_dir}" && git diff HEAD~1 2>&1) || true
+    fi
+  fi
+
+  if [[ -z "${diff_output}" ]]; then
+    warn "No changes found to review" >> "$LLM_OUTPUT"
+    return 0
+  fi
+
+  local file_count
+  file_count=$(echo "${diff_output}" | grep -c '^diff --git' || true)
+
+  {
+    info "Diff contains changes to ${file_count} file(s)"
+    echo ""
+    echo "${diff_output}"
+  } >> "$LLM_OUTPUT"
+}
+
+# @cmd Get list of changed files with stats
+# @option --base Optional base ref to diff against
+get_changed_files() {
+  local project_dir
+  project_dir=$(_project_dir)
+  local base="${argc_base:-}"
+
+  local stat_output=""
+
+  if [[ -n "${base}" ]]; then
+    stat_output=$(cd "${project_dir}" && git diff --stat "${base}" 2>&1) || true
+  else
+    stat_output=$(cd "${project_dir}" && git diff --cached --stat 2>&1) || true
+
+    if [[ -z "${stat_output}" ]]; then
+      stat_output=$(cd "${project_dir}" && git diff --stat 2>&1) || true
+    fi
+
+    if [[ -z "${stat_output}" ]]; then
+      stat_output=$(cd "${project_dir}" && git diff --stat HEAD~1 2>&1) || true
+    fi
+  fi
+
+  if [[ -z "${stat_output}" ]]; then
+    warn "No changes found" >> "$LLM_OUTPUT"
+    return 0
+  fi
+
+  {
+    info "Changed files:"
+    echo ""
+    echo "${stat_output}"
+  } >> "$LLM_OUTPUT"
+}
+
+# @cmd Get project structure and type information
+get_project_info() {
+  local project_dir
+  project_dir=$(_project_dir)
+
+  local project_info
+  project_info=$(detect_project "${project_dir}")
+
+  {
+    info "Project: ${project_dir}"
+    echo "Type: $(echo "${project_info}" | jq -r '.type')"
+    echo ""
+    get_tree "${project_dir}" 2
+  } >> "$LLM_OUTPUT"
+}
+
+# ARGC-BUILD {
+# This block was generated by argc (https://github.com/sigoden/argc).
+# Modifying it manually is not recommended
+
+_argc_run() {
+    if [[ "${1:-}" == "___internal___" ]]; then
+        _argc_die "error: unsupported ___internal___ command"
+    fi
+    if [[ "${OS:-}" == "Windows_NT" ]] && [[ -n "${MSYSTEM:-}" ]]; then
+        set -o igncr
+    fi
+    argc__args=("$(basename "$0" .sh)" "$@")
+    argc__positionals=()
+    _argc_index=1
+    _argc_len="${#argc__args[@]}"
+    _argc_tools=()
+    _argc_parse
+    if [ -n "${argc__fn:-}" ]; then
+        $argc__fn "${argc__positionals[@]}"
+    fi
+}
+
+_argc_usage() {
+    cat <<-'EOF'
+Code review orchestrator tools
+
+USAGE:  <COMMAND>
+
+COMMANDS:
+  get_diff           Get git diff for code review. Returns staged changes, or unstaged if nothing is staged, or HEAD~1 diff if working tree is clean. [aliases: get-diff]
+  get_changed_files  Get list of changed files with stats [aliases: get-changed-files]
+  get_project_info   Get project structure and type information [aliases: get-project-info]
+
+ENVIRONMENTS:
+  LLM_OUTPUT                 [default: /dev/stdout]
+  LLM_AGENT_VAR_PROJECT_DIR  [default: .]
+EOF
+    exit
+}
+
+_argc_version() {
+    echo  0.0.0
+    exit
+}
+
+_argc_parse() {
+    local _argc_key _argc_action
+    local _argc_subcmds="get_diff, get-diff, get_changed_files, get-changed-files, get_project_info, get-project-info"
+    while [[ $_argc_index -lt $_argc_len ]]; do
+        _argc_item="${argc__args[_argc_index]}"
+        _argc_key="${_argc_item%%=*}"
+        case "$_argc_key" in
+        --help | -help | -h)
+            _argc_usage
+            ;;
+        --version | -version | -V)
+            _argc_version
+            ;;
+        --)
+            _argc_dash="${#argc__positionals[@]}"
+            argc__positionals+=("${argc__args[@]:$((_argc_index + 1))}")
+            _argc_index=$_argc_len
+            break
+            ;;
+        get_diff | get-diff)
+            _argc_index=$((_argc_index + 1))
+            _argc_action=_argc_parse_get_diff
+            break
+            ;;
+        get_changed_files | get-changed-files)
+            _argc_index=$((_argc_index + 1))
+            _argc_action=_argc_parse_get_changed_files
+            break
+            ;;
+        get_project_info | get-project-info)
+            _argc_index=$((_argc_index + 1))
+            _argc_action=_argc_parse_get_project_info
+            break
+            ;;
+        help)
+            local help_arg="${argc__args[$((_argc_index + 1))]:-}"
+            case "$help_arg" in
+            get_diff | get-diff)
+                _argc_usage_get_diff
+                ;;
+            get_changed_files | get-changed-files)
+                _argc_usage_get_changed_files
+                ;;
+            get_project_info | get-project-info)
+                _argc_usage_get_project_info
+                ;;
+            "")
+                _argc_usage
+                ;;
+            *)
+                _argc_die "error: invalid value \`$help_arg\` for \`<command>\`"$'\n'"  [possible values: $_argc_subcmds]"
+                ;;
+            esac
+            ;;
+        *)
+            _argc_die "error: \`\` requires a subcommand but one was not provided"$'\n'"  [subcommands: $_argc_subcmds]"
+            ;;
+        esac
+    done
+    if [[ -n "${_argc_action:-}" ]]; then
+        $_argc_action
+    else
+        _argc_usage
+    fi
+}
+
+_argc_usage_get_diff() {
+    cat <<-'EOF'
+Get git diff for code review. Returns staged changes, or unstaged if nothing is staged, or HEAD~1 diff if working tree is clean.
+
+USAGE:  get_diff [OPTIONS]
+
+OPTIONS:
+      --base <BASE>  Optional base ref to diff against (e.g., "main", "HEAD~3", a commit SHA)
+  -h, --help         Print help
+
+ENVIRONMENTS:
+  LLM_OUTPUT                 [default: /dev/stdout]
+  LLM_AGENT_VAR_PROJECT_DIR  [default: .]
+EOF
+    exit
+}
+
+_argc_parse_get_diff() {
+    local _argc_key _argc_action
+    local _argc_subcmds=""
+    while [[ $_argc_index -lt $_argc_len ]]; do
+        _argc_item="${argc__args[_argc_index]}"
+        _argc_key="${_argc_item%%=*}"
+        case "$_argc_key" in
+        --help | -help | -h)
+            _argc_usage_get_diff
+            ;;
+        --)
+            _argc_dash="${#argc__positionals[@]}"
+            argc__positionals+=("${argc__args[@]:$((_argc_index + 1))}")
+            _argc_index=$_argc_len
+            break
+            ;;
+        --base)
+            _argc_take_args "--base <BASE>" 1 1 "-" ""
+            _argc_index=$((_argc_index + _argc_take_args_len + 1))
+            if [[ -z "${argc_base:-}" ]]; then
+                argc_base="${_argc_take_args_values[0]:-}"
+            else
+                _argc_die "error: the argument \`--base\` cannot be used multiple times"
+            fi
+            ;;
+        *)
+            if _argc_maybe_flag_option "-" "$_argc_item"; then
+                _argc_die "error: unexpected argument \`$_argc_key\` found"
+            fi
+            argc__positionals+=("$_argc_item")
+            _argc_index=$((_argc_index + 1))
+            ;;
+        esac
+    done
+    if [[ -n "${_argc_action:-}" ]]; then
+        $_argc_action
+    else
+        argc__fn=get_diff
+        if [[ "${argc__positionals[0]:-}" == "help" ]] && [[ "${#argc__positionals[@]}" -eq 1 ]]; then
+            _argc_usage_get_diff
+        fi
+        if [[ -z "${LLM_OUTPUT:-}" ]]; then
+            export LLM_OUTPUT=/dev/stdout
+        fi
+        if [[ -z "${LLM_AGENT_VAR_PROJECT_DIR:-}" ]]; then
+            export LLM_AGENT_VAR_PROJECT_DIR=.
+        fi
+    fi
+}
+
+_argc_usage_get_changed_files() {
+    cat <<-'EOF'
+Get list of changed files with stats
+
+USAGE:  get_changed_files [OPTIONS]
+
+OPTIONS:
+      --base <BASE>  Optional base ref to diff against
+  -h, --help         Print help
+
+ENVIRONMENTS:
+  LLM_OUTPUT                 [default: /dev/stdout]
+  LLM_AGENT_VAR_PROJECT_DIR  [default: .]
+EOF
+    exit
+}
+
+_argc_parse_get_changed_files() {
+    local _argc_key _argc_action
+    local _argc_subcmds=""
+    while [[ $_argc_index -lt $_argc_len ]]; do
+        _argc_item="${argc__args[_argc_index]}"
+        _argc_key="${_argc_item%%=*}"
+        case "$_argc_key" in
+        --help | -help | -h)
+            _argc_usage_get_changed_files
+            ;;
+        --)
+            _argc_dash="${#argc__positionals[@]}"
+            argc__positionals+=("${argc__args[@]:$((_argc_index + 1))}")
+            _argc_index=$_argc_len
+            break
+            ;;
+        --base)
+            _argc_take_args "--base <BASE>" 1 1 "-" ""
+            _argc_index=$((_argc_index + _argc_take_args_len + 1))
+            if [[ -z "${argc_base:-}" ]]; then
+                argc_base="${_argc_take_args_values[0]:-}"
+            else
+                _argc_die "error: the argument \`--base\` cannot be used multiple times"
+            fi
+            ;;
+        *)
+            if _argc_maybe_flag_option "-" "$_argc_item"; then
+                _argc_die "error: unexpected argument \`$_argc_key\` found"
+            fi
+            argc__positionals+=("$_argc_item")
+            _argc_index=$((_argc_index + 1))
+            ;;
+        esac
+    done
+    if [[ -n "${_argc_action:-}" ]]; then
+        $_argc_action
+    else
+        argc__fn=get_changed_files
+        if [[ "${argc__positionals[0]:-}" == "help" ]] && [[ "${#argc__positionals[@]}" -eq 1 ]]; then
+            _argc_usage_get_changed_files
+        fi
+        if [[ -z "${LLM_OUTPUT:-}" ]]; then
+            export LLM_OUTPUT=/dev/stdout
+        fi
+        if [[ -z "${LLM_AGENT_VAR_PROJECT_DIR:-}" ]]; then
+            export LLM_AGENT_VAR_PROJECT_DIR=.
+        fi
+    fi
+}
+
+_argc_usage_get_project_info() {
+    cat <<-'EOF'
+Get project structure and type information
+
+USAGE:  get_project_info
+
+ENVIRONMENTS:
+  LLM_OUTPUT                 [default: /dev/stdout]
+  LLM_AGENT_VAR_PROJECT_DIR  [default: .]
+EOF
+    exit
+}
+
+_argc_parse_get_project_info() {
+    local _argc_key _argc_action
+    local _argc_subcmds=""
+    while [[ $_argc_index -lt $_argc_len ]]; do
+        _argc_item="${argc__args[_argc_index]}"
+        _argc_key="${_argc_item%%=*}"
+        case "$_argc_key" in
+        --help | -help | -h)
+            _argc_usage_get_project_info
+            ;;
+        --)
+            _argc_dash="${#argc__positionals[@]}"
+            argc__positionals+=("${argc__args[@]:$((_argc_index + 1))}")
+            _argc_index=$_argc_len
+            break
+            ;;
+        *)
+            argc__positionals+=("$_argc_item")
+            _argc_index=$((_argc_index + 1))
+            ;;
+        esac
+    done
+    if [[ -n "${_argc_action:-}" ]]; then
+        $_argc_action
+    else
+        argc__fn=get_project_info
+        if [[ "${argc__positionals[0]:-}" == "help" ]] && [[ "${#argc__positionals[@]}" -eq 1 ]]; then
+            _argc_usage_get_project_info
+        fi
+        if [[ -z "${LLM_OUTPUT:-}" ]]; then
+            export LLM_OUTPUT=/dev/stdout
+        fi
+        if [[ -z "${LLM_AGENT_VAR_PROJECT_DIR:-}" ]]; then
+            export LLM_AGENT_VAR_PROJECT_DIR=.
+        fi
+    fi
+}
+
+_argc_take_args() {
+    _argc_take_args_values=()
+    _argc_take_args_len=0
+    local param="$1" min="$2" max="$3" signs="$4" delimiter="$5"
+    if [[ "$min" -eq 0 ]] && [[ "$max" -eq 0 ]]; then
+        return
+    fi
+    local _argc_take_index=$((_argc_index + 1)) _argc_take_value
+    if [[ "$_argc_item" == *=* ]]; then
+        _argc_take_args_values=("${_argc_item##*=}")
+    else
+        while [[ $_argc_take_index -lt $_argc_len ]]; do
+            _argc_take_value="${argc__args[_argc_take_index]}"
+            if _argc_maybe_flag_option "$signs" "$_argc_take_value"; then
+                if [[ "${#_argc_take_value}" -gt 1 ]]; then
+                    break
+                fi
+            fi
+            _argc_take_args_values+=("$_argc_take_value")
+            _argc_take_args_len=$((_argc_take_args_len + 1))
+            if [[ "$_argc_take_args_len" -ge "$max" ]]; then
+                break
+            fi
+            _argc_take_index=$((_argc_take_index + 1))
+        done
+    fi
+    if [[ "${#_argc_take_args_values[@]}" -lt "$min" ]]; then
+        _argc_die "error: incorrect number of values for \`$param\`"
+    fi
+    if [[ -n "$delimiter" ]] && [[ "${#_argc_take_args_values[@]}" -gt 0 ]]; then
+        local item values arr=()
+        for item in "${_argc_take_args_values[@]}"; do
+            IFS="$delimiter" read -r -a values <<<"$item"
+            arr+=("${values[@]}")
+        done
+        _argc_take_args_values=("${arr[@]}")
+    fi
+}
+
+_argc_maybe_flag_option() {
+    local signs="$1" arg="$2"
+    if [[ -z "$signs" ]]; then
+        return 1
+    fi
+    local cond=false
+    if [[ "$signs" == *"+"* ]]; then
+        if [[ "$arg" =~ ^\+[^+].* ]]; then
+            cond=true
+        fi
+    elif [[ "$arg" == -* ]]; then
+        if (( ${#arg} < 3 )) || [[ ! "$arg" =~ ^---.* ]]; then
+            cond=true
+        fi
+    fi
+    if [[ "$cond" == "false" ]]; then
+        return 1
+    fi
+    local value="${arg%%=*}"
+    if [[ "$value" =~ [[:space:]] ]]; then
+        return 1
+    fi
+    return 0
+}
+
+_argc_die() {
+    if [[ $# -eq 0 ]]; then
+        cat
+    else
+        echo "$*" >&2
+    fi
+    exit 1
+}
+
+_argc_run "$@"
+
+# ARGC-BUILD }

assets/agents/coder/README.md

@@ -1,16 +1,82 @@
 # Coder
 
-An AI agent that assists you with your coding tasks.
+A graph-based implementation agent. Plans, implements, and runs build +
+tests in a bounded fix-loop until verified. Designed to be delegated to by
+the **[Sisyphus](../sisyphus/README.md)** agent.
 
-## Features
+Coder is a [graph agent](https://github.com/Dark-Alex-17/loki/wiki/Graph-Agents): its workflow is
+defined declaratively in `graph.yaml`, with verification and the
+implement-fix loop enforced as graph edges rather than prose.
 
-- 🏗️ Intelligent project structure creation and management
-- 🖼️ Convert screenshots into clean, functional code
-- 📁 Comprehensive file system operations (create folders, files, read/write files)
-- 🧐 Advanced code analysis and improvement suggestions
-- 📊 Precise diff-based file editing for controlled code modifications
+## Workflow
 
-## Similar Projects
+```
+analyze_request (llm + output_schema)   plan + complexity extraction
+        ↓
+route_complexity (script)               opt-out approval gate (complexity ≥ 7)
+        ↓
+gate_approval (approval, optional)
+        ↓
+implement (llm + fs tools)              actual file edits
+        ↓
+verify_build (script)
+        ↓
+verify_tests (script)
+        ↓
+fix_loop_gate (script)                  back-edge to implement (bounded)
+        ↓
+end_success / end_rejected / end_failure
+```
 
-- https://github.com/Doriandarko/claude-engineer
-- https://github.com/paul-gauthier/aider
+End nodes emit one of three sentinel outcomes for the caller:
+
+- `CODER_COMPLETE` — build and tests passed.
+- `CODER_REJECTED` — user rejected the plan at the approval gate.
+- `CODER_FAILED` — fix-loop exhausted; build/tests still failing.
+
+## Tuning
+
+The agent's `project_dir` is exposed via the standard `variables:` block,
+so it accepts the runtime override flag:
+
+```sh
+# Invoke from inside the project (project_dir defaults to ".")
+cd /path/to/your/project
+loki -a coder "Add a foo() function..."
+
+# Or invoke from anywhere with an explicit override
+loki -a coder --agent-variable project_dir /path/to/your/project "Add..."
+```
+
+`graph.yaml` `initial_state` exposes:
+
+- `max_fix_attempts` (default `3`) — fix-loop budget before `end_failure`.
+
+Environment overrides honored by the script nodes:
+
+- `BUILD_CMD` — skip project-type detection for the build/check command.
+- `TEST_CMD` — skip detection for tests.
+- `CODER_AUTOAPPROVE=1` — bypass the approval gate (for non-interactive runs
+  where complexity might trip the gate).
+
+## Pro-Tip: IDE MCP Server
+
+Modern IDEs (JetBrains, VS Code, Cursor, Zed, etc.) expose MCP servers
+that let LLMs use IDE tools directly. To wire one in, edit `graph.yaml`:
+
+```yaml
+mcp_servers:
+  - your-ide-mcp-server
+
+global_tools:
+  # Keep read-only fs tools for files outside the IDE project
+  - fs_read.sh
+  - fs_grep.sh
+  - fs_glob.sh
+#  - fs_write.sh
+#  - fs_patch.sh
+  - execute_command.sh
+```
+
+Then add the MCP server's write/patch tools to the `implement` node's
+`tools:` whitelist.

assets/agents/coder/config.yaml

@@ -1,53 +0,0 @@
-name: Coder
-description: An AI agent that assists you with your coding tasks
-version: 0.1.0
-global_tools:
-  - fs_mkdir.sh
-  - fs_ls.sh
-  - fs_patch.sh
-  - fs_cat.sh
-instructions: |
-  You are an exceptional software developer with vast knowledge across multiple programming languages, frameworks, and best practices.
-  Your capabilities include:
-
-  1. Creating and managing project structures
-  2. Writing, debugging, and improving code across multiple languages
-  3. Providing architectural insights and applying design patterns
-  4. Staying current with the latest technologies and best practices
-  5. Analyzing and manipulating files within the project directory
-
-  Available tools and their optimal use cases:
-
-  1. fs_mkdir: Create new directories in the project structure.
-  2. fs_create: Generate new files with specified contents.
-  3. fs_patch: Examine and modify existing files.
-  4. fs_cat: View the contents of existing files without making changes.
-  5. fs_ls: Understand the current project structure or locate specific files.
-
-  Tool Usage Guidelines:
-  - Always use the most appropriate tool for the task at hand.
-  - For file modifications, use fs_patch. Read the file first, then apply changes if needed.
-  - After making changes, always review the diff output to ensure accuracy.
-
-  Project Creation and Management:
-  1. Start by creating a root folder for new projects.
-  2. Create necessary subdirectories and files within the root folder.
-  3. Organize the project structure logically, following best practices for the specific project type.
-
-  Code Editing Best Practices:
-  1. Always read the file content before making changes.
-  2. Analyze the code and determine necessary modifications.
-  3. Pay close attention to existing code structure to avoid unintended alterations.
-  4. Review changes thoroughly after each modification.
-
-  Always strive for accuracy, clarity, and efficiency in your responses and actions.
-
-  Answer the user's request using relevant tools (if they are available). Before calling a tool, do some analysis within <thinking></thinking> tags. First, think about which of the provided tools is the relevant tool to answer the user's request. Second, go through each of the required parameters of the relevant tool and determine if the user has directly provided or given enough information to infer a value. When deciding if the parameter can be inferred, carefully consider all the context to see if it supports a specific value. If all of the required parameters are present or can be reasonably inferred, close the thinking tag and proceed with the tool call. BUT, if one of the values for a required parameter is missing, DO NOT invoke the function (not even with fillers for the missing params) and instead, ask the user to provide the missing parameters. DO NOT ask for more information on optional parameters if it is not provided.
-
-  Do not reflect on the quality of the returned search results in your response.
-
-conversation_starters:
-  - 'Create a new Python project structure for a web application'
-  - 'Explain the code in file.py and suggest improvements'
-  - 'Search for the latest best practices in React development'
-  - 'Help me debug this error: [paste your error message]'

assets/agents/coder/graph.yaml

@@ -0,0 +1,278 @@
+name: coder
+description: |
+  Implementation agent. Plans, implements, and runs build + tests in a
+  bounded fix-loop until verified. Designed to be delegated to by sisyphus.
+version: "1.0"
+
+temperature: 0.1
+
+global_tools:
+  - fs_cat.sh
+  - fs_ls.sh
+  - fs_write.sh
+  - fs_patch.sh
+  - execute_command.sh
+
+variables:
+  - name: project_dir
+    description: |
+      Absolute path to the project directory. Defaults to "." which is the
+      directory you invoked `loki` from. Override at runtime with
+      `loki -a coder --agent-variable project_dir /abs/path "..."`.
+    default: "."
+
+settings:
+  max_loop_iterations: 20
+  log_state_snapshots: true
+  validate_before_run: true
+  timeout: 1800
+
+initial_state:
+  project_dir: ""
+  fix_attempts: 0
+  max_fix_attempts: 3
+  fix_instructions: ""
+  build_output: ""
+  tests_output: ""
+  last_node_output: ""
+  plan_summary: ""
+  files_to_modify: []
+  files_to_create: []
+  risks: []
+  complexity_score: 0
+
+start: resolve_paths
+
+nodes:
+  resolve_paths:
+    id: resolve_paths
+    type: script
+    description: Resolve project_dir to an absolute path from the agent variable
+    script: scripts/resolve_paths.sh
+    timeout: 5
+    fallback: end_failure
+
+  analyze_request:
+    id: analyze_request
+    type: llm
+    description: Extract a structured plan and complexity score from the orchestrator's prompt
+    instructions: |
+      You are a senior engineer's planning assistant. Read the orchestrator's
+      request and emit a structured plan. You only plan. You never edit files.
+
+      Score complexity from 1 to 10:
+        1-3: trivial - single file, <=20 lines changed, obvious approach
+        4-6: moderate - 2-5 files, clear approach, some pattern matching
+        7-10: complex - multi-component, ambiguous tradeoffs, refactoring,
+              or wide blast radius
+
+      Be specific in `files_to_modify` and `files_to_create`. All paths
+      MUST be absolute. The project root is {{project_dir}}. Prefer paths
+      like "{{project_dir}}/src/foo.rs" over "src/foo.rs". The implementer
+      uses these paths directly with fs_write and fs_patch tools, which
+      resolve relative paths against the loki invocation directory (NOT
+      the project dir). Empty arrays are fine if no files in that category.
+
+      `risks` is a list of short strings. Anything that could derail the
+      implementation: unknown dependencies, brittle tests, blast radius,
+      etc. Empty list is fine.
+
+      Project directory: {{project_dir}}
+    prompt: "{{initial_prompt}}"
+    tools: []
+    output_schema:
+      type: object
+      properties:
+        plan_summary:
+          type: string
+          description: 1-3 sentences summarizing what will be done
+        files_to_modify:
+          type: array
+          items: {type: string}
+        files_to_create:
+          type: array
+          items: {type: string}
+        complexity_score:
+          type: integer
+          minimum: 1
+          maximum: 10
+        risks:
+          type: array
+          items: {type: string}
+      required: [plan_summary, files_to_modify, files_to_create, complexity_score, risks]
+    state_updates:
+      last_node_output: "{{output}}"
+    fallback: end_failure
+    next: route_complexity
+
+  route_complexity:
+    id: route_complexity
+    type: script
+    description: Route to approval gate for complex plans; skip otherwise
+    script: scripts/route_complexity.sh
+    timeout: 5
+    fallback: implement
+
+  gate_approval:
+    id: gate_approval
+    type: approval
+    description: Optional human checkpoint for high-complexity plans
+    question: |
+      ## Plan
+      {{plan_summary}}
+
+      ## Files to modify
+      {{files_to_modify}}
+
+      ## Files to create
+      {{files_to_create}}
+
+      ## Risks
+      {{risks}}
+
+      Complexity: {{complexity_score}}/10
+
+      Approve this plan?
+    options:
+      - "yes"
+      - "no"
+    routes:
+      "yes": implement
+      "no": end_rejected
+    on_other: end_rejected
+
+  implement:
+    id: implement
+    type: llm
+    description: Write code via fs tools. Bounded tool-call loop.
+    instructions: |
+      You are a senior engineer. Implement the plan by writing code via
+      tools. Follow existing patterns in the codebase.
+
+      ## Writing code
+
+      1. Use `fs_patch` for surgical edits to existing files.
+      2. Use `fs_write` for new files or full rewrites.
+      3. NEVER output code to chat. Always use tools.
+      4. ALWAYS pass ABSOLUTE paths to fs_write and fs_patch. Relative
+         paths resolve against the loki invocation directory (not the
+         project dir), which is rarely what you want. The project root
+         is {{project_dir}}.
+
+      ## File reading
+
+      1. Use `execute_command` to grep/find:
+         `execute_command --command "grep -rn 'fn handle_request' --include='*.rs' ."`
+         `execute_command --command "find . -name '*.rs' -not -path '*/target/*'"`
+      2. Read only what you need:
+         `fs_cat --path "src/main.rs" --offset 50 --limit 30`
+      3. Never read entire large files. Use offset/limit.
+      4. Use `fs_ls` to list directory contents.
+
+      ## Pattern matching
+
+      Before writing ANY file:
+      1. Find a similar existing file (grep, then read).
+      2. Match its style: imports, naming, structure, error handling.
+      3. Follow the same patterns exactly. Do not invent new ones.
+
+      ## Fix loop
+
+      If the "Fix loop status" section in your user prompt is non-empty,
+      the previous attempt failed verification. Read the error, identify
+      the minimal fix, apply it. Do not refactor while fixing.
+
+      ## Rules
+
+      1. Match existing patterns - read examples first.
+      2. Minimal changes - implement only what's asked.
+      3. Never suppress errors (`as any`, `@ts-ignore`, `#[allow(...)]`
+         on unfamiliar lints, etc.).
+      4. No dead code, no commented-out blocks, no premature abstractions.
+      5. End your turn when editing is done. The graph runs verification next.
+
+      Project directory: {{project_dir}}
+    prompt: |
+      ## Plan summary
+      {{plan_summary}}
+
+      ## Files involved
+      - Modify: {{files_to_modify}}
+      - Create: {{files_to_create}}
+
+      ## Original request from the orchestrator
+      {{initial_prompt}}
+
+      ## Fix loop status
+      {{fix_instructions}}
+    tools:
+      - fs_cat
+      - fs_ls
+      - fs_write
+      - fs_patch
+      - execute_command
+    max_iterations: 30
+    state_updates:
+      last_node_output: "{{output}}"
+    fallback: end_failure
+    next: verify_build
+
+  verify_build:
+    id: verify_build
+    type: script
+    description: Run the project's check/build command. Routes to verify_tests on success, fix_loop_gate on failure.
+    script: scripts/verify_build.sh
+    timeout: 300
+    fallback: fix_loop_gate
+
+  verify_tests:
+    id: verify_tests
+    type: script
+    description: Run the project's test command. Routes to end_success on pass, fix_loop_gate on failure.
+    script: scripts/verify_tests.sh
+    timeout: 600
+    fallback: fix_loop_gate
+
+  fix_loop_gate:
+    id: fix_loop_gate
+    type: script
+    description: Budget gate. Loops back to implement with fix_instructions populated, or terminates as end_failure.
+    script: scripts/fix_loop_gate.sh
+    timeout: 5
+    fallback: end_failure
+
+  end_success:
+    id: end_success
+    type: end
+    output: |
+      CODER_COMPLETE
+      Plan: {{plan_summary}}
+      Files modified: {{files_to_modify}}
+      Files created: {{files_to_create}}
+      Build: passed
+      Tests: passed
+
+  end_rejected:
+    id: end_rejected
+    type: end
+    output: |
+      CODER_REJECTED
+      Plan was rejected at the approval gate.
+      Plan: {{plan_summary}}
+
+  end_failure:
+    id: end_failure
+    type: end
+    output: |
+      CODER_FAILED
+      Plan: {{plan_summary}}
+      Attempts: {{fix_attempts}}/{{max_fix_attempts}}
+
+      Last node output:
+      {{last_node_output}}
+
+      Last build output:
+      {{build_output}}
+
+      Last tests output:
+      {{tests_output}}

assets/agents/coder/scripts/fix_loop_gate.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ -n "${GRAPH_STATE_FILE:-}" ]]; then
+  state=$(cat "$GRAPH_STATE_FILE")
+elif [[ -n "${GRAPH_STATE:-}" ]]; then
+  state="$GRAPH_STATE"
+else
+  state='{}'
+fi
+
+fix_attempts=$(echo "$state" | jq -r '.fix_attempts // 0')
+max_fix_attempts=$(echo "$state" | jq -r '.max_fix_attempts // 3')
+build_ok=$(echo "$state" | jq -r '.build_ok | if . == null then "true" else (. | tostring) end')
+tests_ok=$(echo "$state" | jq -r '.tests_ok | if . == null then "true" else (. | tostring) end')
+build_output=$(echo "$state" | jq -r '.build_output // ""')
+tests_output=$(echo "$state" | jq -r '.tests_output // ""')
+
+if (( fix_attempts >= max_fix_attempts )); then
+  jq -nc \
+    --argjson n "$fix_attempts" \
+    '{
+      "fix_attempts": $n,
+      "_next": "end_failure"
+    }'
+  exit 0
+fi
+
+next_attempts=$((fix_attempts + 1))
+
+if [[ "$build_ok" != "true" ]]; then
+  fix_instructions=$(printf '## Fix loop status (attempt %d of %d)\n\nThe previous attempt failed the build.\n\nBuild output:\n```\n%s\n```\n\nIdentify the minimal fix and apply it. Do not refactor.' \
+    "$next_attempts" "$max_fix_attempts" "$build_output")
+elif [[ "$tests_ok" != "true" ]]; then
+  fix_instructions=$(printf '## Fix loop status (attempt %d of %d)\n\nBuild passed but tests failed.\n\nTest output:\n```\n%s\n```\n\nIdentify the minimal fix and apply it. Do not refactor.' \
+    "$next_attempts" "$max_fix_attempts" "$tests_output")
+else
+  fix_instructions=$(printf '## Fix loop status (attempt %d of %d)\n\nfix_loop_gate was reached but no failure was detected in state. Re-run the verification step.' \
+    "$next_attempts" "$max_fix_attempts")
+fi
+
+jq -nc \
+  --argjson n "$next_attempts" \
+  --arg fi "$fix_instructions" \
+  '{
+    "fix_attempts": $n,
+    "fix_instructions": $fi,
+    "_next": "implement"
+  }'

assets/agents/coder/scripts/resolve_paths.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+project_dir="${LLM_AGENT_VAR_PROJECT_DIR:-.}"
+resolved=$(cd "$project_dir" 2>/dev/null && pwd) || resolved="$project_dir"
+
+jq -nc \
+  --arg pd "$resolved" \
+  '{
+    "project_dir": $pd,
+    "_next": "analyze_request"
+  }'

assets/agents/coder/scripts/route_complexity.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ -n "${GRAPH_STATE_FILE:-}" ]]; then
+  state=$(cat "$GRAPH_STATE_FILE")
+elif [[ -n "${GRAPH_STATE:-}" ]]; then
+  state="$GRAPH_STATE"
+else
+  state='{}'
+fi
+
+complexity=$(echo "$state" | jq -r '.complexity_score // 0')
+
+if [[ "${CODER_AUTOAPPROVE:-0}" == "1" ]]; then
+  jq -nc '{"_next": "implement"}'
+  exit 0
+fi
+
+if (( complexity >= 7 )); then
+  jq -nc '{"_next": "gate_approval"}'
+else
+  jq -nc '{"_next": "implement"}'
+fi

assets/agents/coder/scripts/verify_build.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# shellcheck disable=SC1091
+source "$(dirname "$0")/../../.shared/utils.sh"
+
+if [[ -n "${GRAPH_STATE_FILE:-}" ]]; then
+  state=$(cat "$GRAPH_STATE_FILE")
+elif [[ -n "${GRAPH_STATE:-}" ]]; then
+  state="$GRAPH_STATE"
+else
+  state='{}'
+fi
+
+project_dir=$(echo "$state" | jq -r '.project_dir // "."')
+
+if [[ -n "${BUILD_CMD:-}" ]]; then
+  cmd="$BUILD_CMD"
+else
+  project_info=$(detect_project "$project_dir")
+  cmd=$(echo "$project_info" | jq -r '.check // .build // ""')
+fi
+
+if [[ -z "$cmd" || "$cmd" == "null" ]]; then
+  jq -nc '{
+    "build_ok": true,
+    "build_output": "(no build/check command available for this project type)",
+    "_next": "verify_tests"
+  }'
+  exit 0
+fi
+
+exit_code=0
+output=$(cd "$project_dir" && eval "$cmd" 2>&1) || exit_code=$?
+
+if (( exit_code == 0 )); then
+  jq -nc \
+    --arg out "$output" \
+    --arg cmd "$cmd" \
+    '{
+      "build_ok": true,
+      "build_output": ("Ran: " + $cmd + "\n\n" + $out),
+      "_next": "verify_tests"
+    }'
+else
+  jq -nc \
+    --arg out "$output" \
+    --arg cmd "$cmd" \
+    --argjson rc "$exit_code" \
+    '{
+      "build_ok": false,
+      "build_output": ("Ran: " + $cmd + "\nExit code: " + ($rc | tostring) + "\n\n" + $out),
+      "_next": "fix_loop_gate"
+    }'
+fi

assets/agents/coder/scripts/verify_tests.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# shellcheck disable=SC1091
+source "$(dirname "$0")/../../.shared/utils.sh"
+
+if [[ -n "${GRAPH_STATE_FILE:-}" ]]; then
+  state=$(cat "$GRAPH_STATE_FILE")
+elif [[ -n "${GRAPH_STATE:-}" ]]; then
+  state="$GRAPH_STATE"
+else
+  state='{}'
+fi
+
+project_dir=$(echo "$state" | jq -r '.project_dir // "."')
+
+if [[ -n "${TEST_CMD:-}" ]]; then
+  cmd="$TEST_CMD"
+else
+  project_info=$(detect_project "$project_dir")
+  cmd=$(echo "$project_info" | jq -r '.test // ""')
+fi
+
+if [[ -z "$cmd" || "$cmd" == "null" ]]; then
+  jq -nc '{
+    "tests_ok": true,
+    "tests_output": "(no test command available for this project type)",
+    "_next": "end_success"
+  }'
+  exit 0
+fi
+
+exit_code=0
+output=$(cd "$project_dir" && eval "$cmd" 2>&1) || exit_code=$?
+
+if (( exit_code == 0 )); then
+  jq -nc \
+    --arg out "$output" \
+    --arg cmd "$cmd" \
+    '{
+      "tests_ok": true,
+      "tests_output": ("Ran: " + $cmd + "\n\n" + $out),
+      "_next": "end_success"
+    }'
+else
+  jq -nc \
+    --arg out "$output" \
+    --arg cmd "$cmd" \
+    --argjson rc "$exit_code" \
+    '{
+      "tests_ok": false,
+      "tests_output": ("Ran: " + $cmd + "\nExit code: " + ($rc | tostring) + "\n\n" + $out),
+      "_next": "fix_loop_gate"
+    }'
+fi

assets/agents/coder/tools.sh

@@ -1,18 +1,98 @@
 #!/usr/bin/env bash
-set -e
-
-# @env LLM_OUTPUT=/dev/stdout The output path
+set -eo pipefail
 
 # shellcheck disable=SC1090
 source "$LLM_PROMPT_UTILS_FILE"
+source "$LLM_ROOT_DIR/agents/.shared/utils.sh"
 
-# @cmd Create a new file at the specified path with the given contents.
-# @option --path! The path where the file should be created
-# @option --contents! The contents of the file
-# shellcheck disable=SC2154
-fs_create() {
-    guard_path "$argc_path" "Create '$argc_path'?"
-    mkdir -p "$(dirname "$argc_path")"
-    printf "%s" "$argc_contents" > "$argc_path"
-    echo "File created: $argc_path" >> "$LLM_OUTPUT"
+# @env LLM_OUTPUT=/dev/stdout
+# @env LLM_AGENT_VAR_PROJECT_DIR=.
+# @describe Coder agent tools for implementing code changes
+
+_project_dir() {
+  local dir="${LLM_AGENT_VAR_PROJECT_DIR:-.}"
+  (cd "${dir}" 2>/dev/null && pwd) || echo "${dir}"
 }
+
+# @cmd Verify the project builds successfully
+verify_build() {
+  local project_dir
+  project_dir=$(_project_dir)
+  
+  local project_info
+  project_info=$(detect_project "${project_dir}")
+  local build_cmd
+  build_cmd=$(echo "${project_info}" | jq -r '.check // .build')
+  
+  if [[ -z "${build_cmd}" ]] || [[ "${build_cmd}" == "null" ]]; then
+    warn "No build command detected" >> "$LLM_OUTPUT"
+    return 0
+  fi
+  
+  info "Running: ${build_cmd}" >> "$LLM_OUTPUT"
+  echo "" >> "$LLM_OUTPUT"
+  
+  local output exit_code=0
+  output=$(cd "${project_dir}" && eval "${build_cmd}" 2>&1) || exit_code=$?
+  
+  echo "${output}" >> "$LLM_OUTPUT"
+  echo "" >> "$LLM_OUTPUT"
+  
+  if [[ ${exit_code} -eq 0 ]]; then
+    green "BUILD SUCCESS" >> "$LLM_OUTPUT"
+    return 0
+  else
+    error "BUILD FAILED (exit code: ${exit_code})" >> "$LLM_OUTPUT"
+    return 1
+  fi
+}
+
+# @cmd Run project tests
+run_tests() {
+  local project_dir
+  project_dir=$(_project_dir)
+  
+  local project_info
+  project_info=$(detect_project "${project_dir}")
+  local test_cmd
+  test_cmd=$(echo "${project_info}" | jq -r '.test')
+  
+  if [[ -z "${test_cmd}" ]] || [[ "${test_cmd}" == "null" ]]; then
+    warn "No test command detected" >> "$LLM_OUTPUT"
+    return 0
+  fi
+  
+  info "Running: ${test_cmd}" >> "$LLM_OUTPUT"
+  echo "" >> "$LLM_OUTPUT"
+  
+  local output exit_code=0
+  output=$(cd "${project_dir}" && eval "${test_cmd}" 2>&1) || exit_code=$?
+  
+  echo "${output}" >> "$LLM_OUTPUT"
+  echo "" >> "$LLM_OUTPUT"
+  
+  if [[ ${exit_code} -eq 0 ]]; then
+    green "TESTS PASSED" >> "$LLM_OUTPUT"
+    return 0
+  else
+    error "TESTS FAILED (exit code: ${exit_code})" >> "$LLM_OUTPUT"
+    return 1
+  fi
+}
+
+# @cmd Get project structure for context
+get_project_structure() {
+  local project_dir
+  project_dir=$(_project_dir)
+  
+  local project_info
+  project_info=$(detect_project "${project_dir}")
+
+  {
+  	info "Project: $(echo "${project_info}" | jq -r '.type')"
+  	echo ""
+  
+  	get_tree "${project_dir}" 2
+  } >> "$LLM_OUTPUT"
+}
+

assets/agents/deep-research/README.md

@@ -0,0 +1,274 @@
+# deep-research
+
+A deep web research agent, built as a Loki graph agent. It plans an
+investigation, decomposes it into sub-questions researched in
+parallel, grounds the work in a local knowledge corpus, vets the
+credibility of cited sources, runs a reflexion self-critique loop to
+revise weak findings, delegates the final write-up to a focused
+sub-agent, checks that the cited sources are reachable, and gates the
+result behind human approval.
+
+Unlike a regular agent (which takes a goal and improvises the steps),
+this agent runs a fixed graph: every request goes through the same
+`plan -> parallel research -> vet -> critique -> synthesize -> verify -> approve`
+pipeline.
+
+This agent is also the **canonical reference for the Loki graph
+system**: it exercises every node type (`script`, `llm`, `rag`, `map`,
+`agent`, `input`, `approval`, `end`) and both static fan-out and
+dynamic `map` fan-out. If you are learning how to build a graph
+agent, this is the file to read alongside the
+[Graph-Agents wiki](https://github.com/Dark-Alex-17/loki/wiki/Graph-Agents).
+
+## Workflow
+
+17 nodes. `->` is the static route; a script node can also route
+dynamically via `_next`. The `▶▶` line is a parallel super-step —
+those branches run concurrently:
+
+```
+parse_request (script)              -> bootstrap_research   (or -> ask_topic if no topic)
+ask_topic (input)                   -> bootstrap_research
+bootstrap_research (script)         -> [plan, knowledge_lookup]   ▶▶ parallel
+plan (llm + output_schema)          -> research_each_question
+knowledge_lookup (rag)              -> research_each_question
+research_each_question (map)        -> combine_findings    (spawns one branch per question)
+  └─ research_one_question (llm)    (atomic; runs N×, joins at map)
+combine_findings (script)           -> vet_sources
+vet_sources (llm + custom tool)     -> critique
+critique (llm)                      -> reflexion_gate
+reflexion_gate (script)             -> synthesize  (or -> research_each_question: reflexion loop)
+synthesize (agent: report-writer)   -> verify_sources
+verify_sources (script)             -> approve
+approve (approval)                  -> end_accepted          ("accept")
+                                    -> end_rejected          ("reject")
+                                    -> incorporate_feedback   (any free-form answer)
+incorporate_feedback (script)       -> research_each_question (the human-feedback loop)
+```
+
+### Node-type breakdown
+
+| Type | Nodes |
+|---|---|
+| `script` (Python) | `parse_request`, `bootstrap_research`, `combine_findings`, `reflexion_gate`, `verify_sources`, `incorporate_feedback` |
+| `llm` (tools: `[]`) | `plan`, `critique` |
+| `llm` (with tool whitelist) | `research_one_question`, `vet_sources` |
+| `rag` | `knowledge_lookup` — local corpus retrieval |
+| `map` | `research_each_question` — dynamic fan-out per sub-question |
+| `agent` | `synthesize` — spawns the `report-writer` sub-agent |
+| `input` | `ask_topic` |
+| `approval` | `approve` |
+| `end` | `end_accepted`, `end_rejected` |
+
+## Parallel execution
+
+The graph has two parallel super-steps where Loki's BSP scheduler runs
+branches concurrently.
+
+**1. Context loading (`plan` ‖ `knowledge_lookup`)** — after
+`bootstrap_research`, the LLM planner (which decomposes the topic into
+sub-questions) and the RAG retrieval over the local `knowledge/`
+corpus run side by side. They write disjoint state keys (`plan` writes
+`research_plan` and `questions`; `knowledge_lookup` writes
+`local_context` and `local_sources`) so no reducer is needed.
+
+**2. Per-question research (`research_each_question` map)** — the
+plan emits a `questions` array (3-5 entries, enforced by its
+`output_schema`). The `map` node spawns one parallel branch per
+question (`max_concurrency: 3`). Each branch is an isolated
+`research_one_question` LLM invocation with web tools, instructed to
+investigate exactly its assigned question. Outputs collect into
+`question_findings` in input order, then `combine_findings` joins
+them into a single `findings` Markdown document for downstream nodes.
+
+`settings.max_concurrency: 4` is the graph-wide cap; the per-`map`
+override (`max_concurrency: 3` on `research_each_question`) is
+deliberately lower to leave headroom for the planner's tool calls
+running alongside RAG.
+
+## Local knowledge corpus
+
+`knowledge_lookup` is a `rag` node — it runs hybrid (vector + keyword)
+retrieval over every file in `knowledge/`. The directory ships with a
+small `research-style-notes.md` so the RAG node has something to
+retrieve against on a clean install; drop your own Markdown notes,
+PDFs, or text files into `knowledge/` to bias the research toward
+your local context.
+
+The knowledge base is built once, at agent-load time, into
+`~/.config/loki/agents/deep-research/knowledge_lookup.yaml`. Because
+the node fully specifies its build config (`embedding_model`,
+`chunk_size`, `chunk_overlap`), the build is non-interactive. Delete
+that cached file after adding or changing knowledge to force a
+rebuild.
+
+## Sub-agent: report-writer
+
+The `synthesize` node is an `agent` node that spawns the
+`report-writer` sub-agent (`assets/agents/report-writer/`). This is
+the agent-as-tool pattern: the orchestrating graph delegates the
+writing phase to a focused sub-agent dedicated to coherent prose,
+while the research phase uses different (typically cheaper) LLM nodes
+for fast-and-many-question investigation.
+
+The `report-writer` sub-agent has no tools — it cannot access the
+web, cannot search, and cannot invent facts. It reads only the
+findings it is given and produces a final Markdown report preserving
+every inline citation. See `assets/agents/report-writer/README.md`
+for details.
+
+## Tools and tool scoping
+
+This agent demonstrates Loki's three tool sources and how an `llm`
+node's `tools:` whitelist scopes them per node.
+
+The agent's full tool universe, declared in `graph.yaml`:
+
+- **Global tools** (`global_tools`): `web_search_loki`,
+  `fetch_url_via_curl`, `search_arxiv` - Loki's built-in tool scripts.
+- **MCP server** (`mcp_servers`): `ddg-search` - a DuckDuckGo web
+  search MCP server. Referenced in a whitelist as `mcp:ddg-search`.
+- **Custom agent tool** (`tools.sh`): `classify_source` - a
+  deterministic source-credibility classifier shipped with this agent.
+
+No node receives all of these. Each `llm` node's `tools:` whitelist
+narrows the universe to exactly what that step needs:
+
+| Node | `tools:` whitelist | Draws from |
+|---|---|---|
+| `plan`, `critique` | `[]` | nothing - pure reasoning |
+| `research_one_question` | `web_search_loki`, `fetch_url_via_curl`, `search_arxiv`, `mcp:ddg-search` | global tools + MCP |
+| `vet_sources` | `classify_source` | the custom tool only |
+
+`research_one_question` (each parallel branch of the map) can search
+and fetch but cannot classify sources; `vet_sources` can classify
+sources but cannot touch the web. That separation is the point of the
+`tools:` whitelist: a node gets only the tools its job calls for,
+never the agent's full set.
+
+The `classify_source` custom tool (`tools.sh`) takes a URL and returns
+a credibility tier (government, academic, preprint, organization,
+unverified) derived from the host and top-level domain. It is
+deterministic - exactly the kind of logic a tool should own rather than
+the LLM guessing.
+
+Web search may require API-key configuration; see the
+[Tools](https://github.com/Dark-Alex-17/loki/wiki/Tools) docs.
+`fetch_url_via_curl`, `search_arxiv`, and `classify_source` work
+without a key.
+
+## Setup
+
+`research_one_question` (each parallel branch of the `map`) uses the
+`ddg-search` MCP server via `mcp:ddg-search`. It is one of Loki's
+default MCP servers; make sure it is registered in
+`~/.config/loki/mcp.json` (run `loki --install mcp_config` to restore
+the default template if it is missing). If `ddg-search` is unavailable,
+the branches still have their global web-search tools to fall back on.
+
+The `synthesize` node spawns the `report-writer` sub-agent. Both
+agents ship with `loki agents install`; if you install one manually,
+install both so the agent reference resolves.
+
+## Reflexion
+
+The agent has two loops, both built with script nodes that route via
+`_next`. The engine allows back-edges at runtime; the validator only
+rejects cycles built from static `next` / `routes` edges, so script
+`_next` loops are always allowed.
+
+**Automated reflexion loop.** After the parallel research map and
+`vet_sources`, the `critique` node reviews the merged findings
+against the research plan and the source credibility assessment, and
+emits `VERDICT: PASS` or `VERDICT: REVISE` with specific feedback.
+`reflexion_gate.py` then:
+
+- `PASS` -> continue to `synthesize`.
+- `REVISE`, budget remaining -> loop back to `research_each_question`,
+  with the critique injected as `research_feedback` so every parallel
+  branch sees it on the retry.
+- `REVISE`, budget spent -> continue to `synthesize` anyway (the human
+  approval step is the final backstop).
+
+The budget is `MAX_REFLEXION_REVISIONS` in `reflexion_gate.py`
+(default 2, so the research map runs at most 3 times per pass).
+
+**Human-feedback loop.** At `approve` the user answers `accept`,
+`reject`, or types their own feedback. A free-form answer routes via
+the approval node's `on_other` to `incorporate_feedback.py`, which
+folds that text into `research_feedback` and loops back to
+`research_each_question` for another parallel pass.
+
+`settings.max_loop_iterations` (40) is the engine's infinite-loop
+backstop: it caps the total visits to any single node.
+
+## Running
+
+```sh
+loki agents install                  # ships deep-research
+loki -a deep-research "How does HTTP/3 differ from HTTP/2?"
+loki -a deep-research "Recent advances in solid-state batteries"
+loki -a deep-research                # no prompt -> triggers ask_topic
+```
+
+## Anti-hallucination
+
+- `research_one_question` (each map branch) is instructed to back
+  every claim with a real retrieved source and never to fabricate
+  URLs, titles, or DOIs.
+- `vet_sources` classifies every cited source so weak sources are
+  visible to the critique step.
+- `critique` independently reviews the merged findings and sends weak
+  or uncited work back for another parallel research pass.
+- `synthesize` (the `report-writer` sub-agent) is grounded: it may use
+  only the gathered findings and must keep each claim's inline source.
+  It has no tools and cannot browse the web.
+- `verify_sources` probes every cited URL / DOI with an HTTP HEAD
+  request and reports which are unreachable, so the human reviewer
+  sees broken citations before approving.
+
+## Customizing
+
+- **Loop budget.** `MAX_REFLEXION_REVISIONS` in `reflexion_gate.py`.
+- **Map concurrency.** The `research_each_question` node's
+  `max_concurrency: 3` caps simultaneous web-research branches.
+  Raise to investigate more questions in parallel; lower to be gentle
+  on rate-limited providers.
+- **Per-node model.** Add `model: anthropic:...` to any `llm` node.
+  Cheap models work well for `plan` / `critique` / `vet_sources`; the
+  heavy intelligence is needed in `research_one_question` and the
+  `report-writer` sub-agent.
+- **Tool scope.** Narrow the `research_one_question` node's `tools:`
+  list to constrain where each branch looks (for example, drop
+  `web_search_loki` and `mcp:ddg-search` to force arXiv-only
+  research).
+- **Local knowledge.** Drop files into `knowledge/` to bias every
+  research branch toward your local context (see the *Local
+  knowledge corpus* section above).
+- **Different writer.** Replace `agent: report-writer` on the
+  `synthesize` node with the name of any other agent. The
+  orchestrator does not care what kind of agent the writer is.
+- **Skip approval.** Point both `approve` routes at `end_accepted`,
+  or wire `verify_sources` straight to an `end` node.
+
+## Files
+
+```
+assets/agents/deep-research/
+  graph.yaml                    - agent config + 17-node workflow
+  tools.sh                      - classify_source custom tool
+  README.md                     - this file
+  knowledge/
+    README.md                   - corpus-format notes
+    research-style-notes.md     - starter knowledge file (replace with your notes)
+  scripts/
+    parse_request.py            - _next: bootstrap_research, or ask_topic if no topic
+    bootstrap_research.py       - fan-out source: next [plan, knowledge_lookup]
+    combine_findings.py         - joins map output (question_findings) into findings
+    reflexion_gate.py           - _next: research_each_question (revise) or synthesize
+    verify_sources.py           - HTTP HEAD on cited URLs / DOIs
+    incorporate_feedback.py     - _next: research_each_question, with user feedback
+```
+
+See also `assets/agents/report-writer/` — the sub-agent the
+`synthesize` node spawns.

assets/agents/deep-research/graph.yaml

@@ -0,0 +1,293 @@
+name: deep-research
+description: |
+  Deep web research workflow. Plans an investigation, decomposes it
+  into sub-questions researched in parallel, grounds the work in a
+  local knowledge corpus, vets the credibility of cited sources, runs
+  a reflexion self-critique loop to revise weak or incomplete findings,
+  delegates the final write-up to a focused sub-agent, checks that the
+  cited sources are reachable, and gates the result behind human
+  approval. A reviewer's free-form feedback at the approval step feeds
+  back into another research pass.
+
+  This is the canonical Loki graph-agent reference: it exercises every
+  node type (script, llm, rag, map, agent, input, approval, end) and
+  both static fan-out and dynamic map fan-out.
+
+version: "1.0"
+
+temperature: 0.0
+
+global_tools:
+  - web_search_loki.sh
+  - fetch_url_via_curl.sh
+  - search_arxiv.sh
+
+mcp_servers:
+  - ddg-search
+
+conversation_starters:
+  - "How does HTTP/3 differ from HTTP/2?"
+  - "Summarize recent advances in solid-state battery chemistry"
+
+settings:
+  max_loop_iterations: 40
+  log_state_snapshots: false
+  validate_before_run: true
+  max_concurrency: 4
+
+initial_state:
+  research_feedback: ""
+  research_attempts: 0
+  local_context: ""
+  local_sources: ""
+
+start: parse_request
+
+nodes:
+
+  parse_request:
+    id: parse_request
+    type: script
+    script: scripts/parse_request.py
+    next: bootstrap_research
+
+  ask_topic:
+    id: ask_topic
+    type: input
+    question: "What would you like me to research?"
+    validation: "len(input) > 0"
+    state_updates:
+      topic: "{{input}}"
+    next: bootstrap_research
+
+  bootstrap_research:
+    id: bootstrap_research
+    type: script
+    script: scripts/bootstrap_research.py
+    next: [plan, knowledge_lookup]
+
+  plan:
+    id: plan
+    type: llm
+    instructions: |
+      You are a research planner. Given a topic, produce a focused
+      research plan and decompose it into 3-5 specific sub-questions
+      that can each be researched independently in parallel.
+
+      The plan is a short narrative naming the key questions and the
+      kinds of sources that would be authoritative. The sub-questions
+      are precise, self-contained queries (each one is sent on its own
+      to a separate research worker, so they must be answerable
+      without each other's context).
+    prompt: "Research topic: {{topic}}"
+    tools: []
+    output_schema:
+      type: object
+      properties:
+        research_plan:
+          type: string
+          description: A short plan narrative.
+        questions:
+          type: array
+          items: { type: string }
+          minItems: 1
+          maxItems: 6
+          description: 3-5 specific, self-contained sub-questions.
+      required: [research_plan, questions]
+    next: research_each_question
+
+  knowledge_lookup:
+    id: knowledge_lookup
+    type: rag
+    documents:
+      - ./knowledge/
+    query: "{{topic}}"
+    top_k: 6
+    chunk_size: 1000
+    chunk_overlap: 100
+    state_updates:
+      local_context: "{{output.context}}"
+      local_sources: "{{output.sources}}"
+    next: research_each_question
+
+  research_each_question:
+    id: research_each_question
+    type: map
+    over: "{{questions}}"
+    as: question
+    branch: research_one_question
+    collect_into: question_findings
+    max_concurrency: 3
+    next: combine_findings
+
+  research_one_question:
+    id: research_one_question
+    type: llm
+    instructions: |
+      You are a web research assistant. Investigate the SINGLE question
+      given to you using your tools: search the web, fetch and read
+      pages, and search arXiv for academic sources.
+
+      Rules:
+        - Every factual claim must be backed by a real source you
+          actually retrieved. Never fabricate URLs, page titles,
+          authors, or DOIs.
+        - Prefer primary and authoritative sources over aggregators.
+        - Where sources disagree, report the disagreement rather than
+          papering over it.
+        - Put the URL (or DOI) inline next to each claim it supports.
+
+      Return organized findings in plain text. Do not include
+      meta-commentary about the process.
+    prompt: |
+      Research question: {{question}}
+
+      Local context that may help:
+      {{local_context}}
+
+      {{research_feedback}}
+    tools:
+      - web_search_loki
+      - fetch_url_via_curl
+      - search_arxiv
+      - mcp:ddg-search
+    max_iterations: 10
+    max_attempts: 2
+    temperature: 0.1
+
+  combine_findings:
+    id: combine_findings
+    type: script
+    script: scripts/combine_findings.py
+    next: vet_sources
+
+  vet_sources:
+    id: vet_sources
+    type: llm
+    instructions: |
+      You assess the credibility of the sources cited in a set of
+      research findings. For every distinct source URL in the findings,
+      call the `classify_source` tool to get its credibility tier. Then
+      summarize: which claims rest on HIGH-credibility sources, and
+      which rest on PREPRINT or UNVERIFIED sources and so need
+      corroboration. Do NOT do any new research -- assess only what is
+      already cited.
+    prompt: |
+      Findings to assess:
+      {{findings}}
+    tools:
+      - classify_source
+    max_iterations: 15
+    state_updates:
+      source_assessment: "{{output}}"
+    next: critique
+
+  critique:
+    id: critique
+    type: llm
+    instructions: |
+      You are a meticulous research reviewer. Judge whether the
+      findings below are good enough to synthesize a complete,
+      well-supported report that answers the research plan.
+
+      Mark the findings REVISE if ANY of these hold:
+        - A research-plan question is unanswered or only weakly
+          addressed.
+        - A factual claim has no source, or cites a source that looks
+          fabricated.
+        - The findings lean on a single source where corroboration is
+          needed.
+        - A key claim rests only on a PREPRINT or UNVERIFIED source,
+          per the source credibility assessment below.
+        - An obvious counter-perspective or recent development is
+          missing.
+      Otherwise mark them PASS.
+
+      Respond in EXACTLY this format, nothing else:
+
+      VERDICT: <PASS or REVISE>
+      FEEDBACK: <if REVISE, be specific and actionable -- name the gaps
+      and what kind of source would close them; if PASS, write "none">
+    prompt: |
+      Research plan:
+      {{research_plan}}
+
+      Findings under review:
+      {{findings}}
+
+      Source credibility assessment:
+      {{source_assessment}}
+    tools: []
+    state_updates:
+      critique: "{{output}}"
+    next: reflexion_gate
+
+  reflexion_gate:
+    id: reflexion_gate
+    type: script
+    script: scripts/reflexion_gate.py
+    next: synthesize
+
+  synthesize:
+    id: synthesize
+    type: agent
+    agent: report-writer
+    prompt: |
+      Research topic: {{topic}}
+
+      Findings (organized by sub-question, with inline citations):
+      {{findings}}
+
+      Source credibility assessment:
+      {{source_assessment}}
+
+      Produce the final report following your instructions.
+    timeout: 300
+    state_updates:
+      report: "{{output}}"
+    next: verify_sources
+
+  verify_sources:
+    id: verify_sources
+    type: script
+    script: scripts/verify_sources.py
+    next: approve
+
+  approve:
+    id: approve
+    type: approval
+    question: |
+      Research report on: {{topic}}
+
+      {{report}}
+
+      ----
+      {{source_check}}
+      ----
+
+      Accept this report? Pick "accept" or "reject", or type specific
+      feedback to send the research back for another pass.
+    options:
+      - "accept"
+      - "reject"
+    routes:
+      "accept": end_accepted
+      "reject": end_rejected
+    on_other: incorporate_feedback
+    state_updates:
+      decision: "{{choice}}"
+
+  incorporate_feedback:
+    id: incorporate_feedback
+    type: script
+    script: scripts/incorporate_feedback.py
+
+  end_accepted:
+    id: end_accepted
+    type: end
+    output: "{{report}}"
+
+  end_rejected:
+    id: end_rejected
+    type: end
+    output: "Research on '{{topic}}' was rejected and discarded."

assets/agents/deep-research/knowledge/README.md

@@ -0,0 +1,23 @@
+# Local knowledge corpus for deep-research
+
+The `knowledge_lookup` node in `graph.yaml` is a `rag` node that runs
+hybrid (vector + keyword) retrieval over every file in this directory.
+Drop your own notes, papers (PDFs), Markdown docs, or text files here
+and they will be indexed into a per-agent knowledge base on first run.
+
+Loki supports common file types out of the box: `.md`, `.txt`, `.pdf`,
+`.html`, and others. Subdirectories are walked recursively.
+
+A small starter file (`research-style-notes.md`) ships so the RAG
+node has something non-empty to retrieve against on a clean install.
+Replace or extend it with your own materials to bias the research
+phase toward your local context.
+
+To force the knowledge base to rebuild after you add or change files,
+delete the cached index:
+
+```sh
+rm ~/.config/loki/agents/deep-research/knowledge_lookup.yaml
+```
+
+The next run will rebuild from the current contents of this directory.

assets/agents/deep-research/knowledge/research-style-notes.md

@@ -0,0 +1,49 @@
+# Research style notes
+
+These are general principles the `deep-research` agent should keep in
+mind regardless of topic. Replace this file with your own notes if you
+want to bias retrieval toward your local context.
+
+## What "good research" means here
+
+- **Every factual claim cites a source you actually retrieved.** Never
+  fabricate URLs, page titles, authors, or DOIs.
+- **Primary sources beat aggregators.** Prefer the original paper, the
+  RFC, the standards body, or the manufacturer over a blog summarizing
+  them.
+- **Corroboration matters where stakes are high.** If a single source
+  makes a strong claim, look for a second independent source before
+  taking it as established.
+- **Disagreement is information, not noise.** If two credible sources
+  disagree, report the disagreement and the reasoning on each side.
+- **Old does not mean wrong.** A 2014 RFC is still authoritative if no
+  newer one has obsoleted it; check before assuming a source is stale.
+
+## Source-tier heuristics
+
+The `vet_sources` node uses these rough tiers to weigh credibility.
+The custom tool `classify_source` (see `tools.sh`) implements this
+deterministically by hostname / TLD.
+
+- **HIGH:** government domains (`.gov`, `.mil`), academic institutions
+  (`.edu`, university subdomains), peer-reviewed journals, standards
+  bodies (IETF/RFCs, W3C, ISO, IEEE, NIST), and primary documents from
+  the entities being researched (e.g. a vendor's official spec page).
+- **PREPRINT:** arXiv, bioRxiv, medRxiv, SSRN. Useful but not yet
+  peer-reviewed; treat numeric claims with extra caution.
+- **ORGANIZATION:** established nonprofits, standards-adjacent groups,
+  industry consortia. Reliable for their stated mission but may have a
+  perspective.
+- **UNVERIFIED:** general web pages, blogs, news aggregators, social
+  media. Useful for leads but should not be the only source for a
+  factual claim.
+
+## Common pitfalls to flag in critique
+
+- A claim cited only to a PREPRINT or UNVERIFIED source on a numeric
+  or contested point.
+- A research-plan question that the findings address only obliquely.
+- "Findings" that paraphrase a single source three times rather than
+  triangulating.
+- Citation collisions where two sources are listed but turn out to
+  be the same study reported via different aggregators.

assets/agents/deep-research/scripts/bootstrap_research.py

@@ -0,0 +1,18 @@
+#!/usr/bin/env python3
+"""Fan-out source for context loading.
+
+Has no logic of its own. Exists so the static `next: [plan, knowledge_lookup]`
+list on this node fans out into two parallel branches (the LLM planner and
+the RAG knowledge lookup) as a single super-step. The validator requires
+declared parallel-branch script outputs, so we emit an empty JSON object
+explicitly here.
+"""
+import json
+
+
+def main():
+    print(json.dumps({}))
+
+
+if __name__ == "__main__":
+    main()

assets/agents/deep-research/scripts/combine_findings.py

@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+"""Join the per-question map outputs into a single `findings` string.
+
+The `research_each_question` map writes `question_findings` (an array,
+one entry per sub-question, in input order). Downstream nodes
+(`vet_sources`, `critique`, `synthesize`) read `{{findings}}` as a
+single block, so this script renders the array as a Markdown document
+with one section per question.
+"""
+import json
+import os
+
+
+def load_state():
+    path = os.environ.get("GRAPH_STATE_FILE")
+    if path:
+        with open(path) as f:
+            return json.load(f)
+    return json.loads(os.environ.get("GRAPH_STATE", "{}"))
+
+
+def main():
+    state = load_state()
+    questions = state.get("questions") or []
+    per_question = state.get("question_findings") or []
+
+    sections = []
+    for idx, q in enumerate(questions):
+        body = per_question[idx] if idx < len(per_question) else ""
+        if isinstance(body, dict) or isinstance(body, list):
+            body = json.dumps(body, indent=2)
+        sections.append(f"## {q}\n\n{body}")
+
+    findings = "\n\n".join(sections) if sections else "No findings gathered."
+    print(json.dumps({"findings": findings}))
+
+
+if __name__ == "__main__":
+    main()

assets/agents/deep-research/scripts/incorporate_feedback.py

@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+"""Fold a reviewer's free-form feedback back into the research loop.
+
+Runs when the user answers the approval step with their own text
+instead of "accept" or "reject". That text (saved by the approval node
+as `decision`) becomes `research_feedback`, and the graph loops back to
+`research_each_question` for another informed pass (each sub-question is
+re-researched in parallel with the new feedback in context). The
+reflexion counter is reset so the user-driven pass gets a fresh revision
+budget.
+
+Routing (`_next`): always research_each_question.
+"""
+import json
+import os
+
+
+def load_state():
+    path = os.environ.get("GRAPH_STATE_FILE")
+    if path:
+        with open(path) as f:
+            return json.load(f)
+    return json.loads(os.environ.get("GRAPH_STATE", "{}"))
+
+
+def main():
+    state = load_state()
+    feedback = (state.get("decision") or "").strip()
+    output = {
+        "_next": "research_each_question",
+        "research_attempts": 0,
+        "research_feedback": (
+            "The user reviewed the report and asked for changes. Treat "
+            "this as the top priority for the next pass:\n\n" + feedback
+        ),
+    }
+    print(json.dumps(output))
+
+
+if __name__ == "__main__":
+    main()

assets/agents/deep-research/scripts/parse_request.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+"""Entry router for deep-research.
+
+Reads the caller's prompt from state. If it contains a usable research
+topic, stores it as `topic` and falls through to the static `next`
+(plan). If the prompt is empty, routes to `ask_topic` so the user can
+supply one interactively.
+
+Routing (`_next`):
+  - prompt present -> (no _next; static next: plan)
+  - prompt empty   -> ask_topic
+"""
+import json
+import os
+
+
+def load_state():
+    path = os.environ.get("GRAPH_STATE_FILE")
+    if path:
+        with open(path) as f:
+            return json.load(f)
+    return json.loads(os.environ.get("GRAPH_STATE", "{}"))
+
+
+def main():
+    state = load_state()
+    prompt = (state.get("initial_prompt") or "").strip()
+    if prompt:
+        print(json.dumps({"topic": prompt}))
+    else:
+        print(json.dumps({"_next": "ask_topic"}))
+
+
+if __name__ == "__main__":
+    main()

assets/agents/deep-research/scripts/reflexion_gate.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""Reflexion gate for deep-research.
+
+Runs after `critique` has reviewed the current research findings. If the
+critique's verdict is REVISE and the reflexion budget is not spent,
+loops back to `research` with the critique attached as
+`research_feedback`, so the retry is informed rather than a blind
+re-run. Otherwise it proceeds to `synthesize`.
+
+Routing (`_next`):
+  - verdict PASS                     -> synthesize
+  - verdict REVISE, budget remaining -> research_each_question  (+ research_feedback)
+  - verdict REVISE, budget spent     -> synthesize
+
+Reflexion is a best-effort quality booster, not a hard gate: once the
+budget is spent the workflow proceeds anyway, and the human approval
+step is the final backstop.
+"""
+import json
+import os
+import re
+
+# Automated revision passes allowed. `research` runs at most
+# MAX_REFLEXION_REVISIONS + 1 times per user pass. Bump to allow more.
+MAX_REFLEXION_REVISIONS = 2
+
+
+def load_state():
+    path = os.environ.get("GRAPH_STATE_FILE")
+    if path:
+        with open(path) as f:
+            return json.load(f)
+    return json.loads(os.environ.get("GRAPH_STATE", "{}"))
+
+
+def as_int(value, default=0):
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def parse_verdict(critique):
+    """Pull PASS/REVISE from the critique's `VERDICT:` line. Defaults to
+    PASS when no verdict line is found, so a malformed critique lets the
+    workflow proceed instead of burning the whole revision budget."""
+    match = re.search(r"VERDICT:\s*([A-Za-z]+)", critique, re.IGNORECASE)
+    if not match:
+        return "PASS"
+    return match.group(1).upper()
+
+
+def main():
+    state = load_state()
+    critique = state.get("critique") or ""
+    verdict = parse_verdict(critique)
+    attempts = as_int(state.get("research_attempts"))
+
+    if verdict == "REVISE" and attempts < MAX_REFLEXION_REVISIONS:
+        feedback = (
+            "A reviewer judged the previous research pass incomplete. "
+            "Address every point in the critique below:\n\n" + critique
+        )
+        output = {
+            "_next": "research_each_question",
+            "research_attempts": attempts + 1,
+            "research_feedback": feedback,
+        }
+    else:
+        output = {"_next": "synthesize"}
+
+    print(json.dumps(output))
+
+
+if __name__ == "__main__":
+    main()

assets/agents/deep-research/scripts/verify_sources.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""Check that the sources cited in the research report are reachable.
+
+Scans the final report for URLs and DOIs, probes each with a HEAD
+request, and writes a `source_check` summary into state so the human
+reviewer sees broken citations at the approval step.
+
+Times out per request so a slow source cannot stall the graph.
+"""
+import json
+import os
+import re
+import urllib.error
+import urllib.request
+
+DOI_RE = re.compile(r"\b(10\.\d{4,9}/[-._;()/:A-Z0-9]+)", re.IGNORECASE)
+URL_RE = re.compile(r"https?://[^\s)\]\}\"'>]+")
+
+
+def load_state():
+    path = os.environ.get("GRAPH_STATE_FILE")
+    if path:
+        with open(path) as f:
+            return json.load(f)
+    return json.loads(os.environ.get("GRAPH_STATE", "{}"))
+
+
+def reachable(url, timeout=5.0):
+    req = urllib.request.Request(url, method="HEAD")
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return 200 <= resp.status < 400
+    except urllib.error.HTTPError as e:
+        return 200 <= e.code < 400
+    except Exception:
+        return False
+
+
+def main():
+    state = load_state()
+    report = state.get("report") or ""
+
+    urls = sorted({u.rstrip(".,;)") for u in URL_RE.findall(report)})
+    dois = sorted(set(DOI_RE.findall(report)))
+
+    results = []
+    for url in urls:
+        ok = reachable(url)
+        results.append(f"  {'OK' if ok else 'UNREACHABLE'}  {url}")
+    for doi in dois:
+        url = f"https://doi.org/{doi}"
+        if url in urls:
+            continue
+        ok = reachable(url)
+        results.append(f"  {'OK' if ok else 'UNREACHABLE'}  DOI {doi} ({url})")
+
+    if not results:
+        summary = "No web sources were cited in the report."
+    else:
+        summary = (
+            f"Source reachability ({len(results)} checked):\n"
+            + "\n".join(results)
+        )
+
+    print(json.dumps({"source_check": summary}))
+
+
+if __name__ == "__main__":
+    main()

assets/agents/deep-research/tools.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+
+set -e
+
+# @env LLM_OUTPUT=/dev/stdout The output path
+
+# @cmd Classify the credibility tier of a web source from its URL.
+# A deterministic check based on the host and top-level domain. Use it
+# to weigh how much trust to place in a source before relying on it.
+# @option --url!  The full source URL to classify
+classify_source() {
+    # shellcheck disable=SC2154
+    local url="$argc_url"
+    local host="${url#*://}"
+    host="${host%%/*}"
+    host="${host##*@}"
+    host="${host%%:*}"
+    host="$(printf '%s' "$host" | tr '[:upper:]' '[:lower:]')"
+
+    local tier
+    case "$host" in
+        '')
+            tier="UNKNOWN - no host could be parsed from the URL" ;;
+        *.gov | *.gov.* | *.mil)
+            tier="HIGH - government source" ;;
+        *.edu | *.edu.* | *.ac.*)
+            tier="HIGH - academic institution" ;;
+        arxiv.org | *.arxiv.org | biorxiv.org | *.biorxiv.org | medrxiv.org | *.medrxiv.org | ssrn.com | *.ssrn.com)
+            tier="PREPRINT - not yet peer reviewed, corroborate before citing" ;;
+        wikipedia.org | *.wikipedia.org)
+            tier="TERTIARY - encyclopedia, good for orientation not citation" ;;
+        *.org | *.org.*)
+            tier="MEDIUM - organization site, check for institutional bias" ;;
+        *)
+            tier="UNVERIFIED - general web source, corroborate before citing" ;;
+    esac
+
+    printf '%s: %s\n' "${host:-<none>}" "$tier" >> "$LLM_OUTPUT"
+}

assets/agents/explore/README.md

@@ -0,0 +1,37 @@
+# Explore
+
+An AI agent specialized in exploring codebases, finding patterns, and understanding project structures.
+
+This agent is designed to be delegated to by the **[Sisyphus](../sisyphus/README.md)** agent to gather information and context. Sisyphus
+acts as the coordinator/architect, while Explore handles the research and discovery phase.
+
+It can also be used as a standalone tool for understanding codebases and finding specific information.
+
+## Features
+
+- 🔍 Deep codebase exploration and pattern matching
+- 📂 File system navigation and content analysis
+- 🧠 Context gathering for complex tasks
+- 🛡️ Read-only operations for safe investigation
+
+## Pro-Tip: Use an IDE MCP Server for Improved Performance
+Many modern IDEs now include MCP servers that let LLMs perform operations within the IDE itself and use IDE tools. Using
+an IDE's MCP server dramatically improves the performance of coding agents. So if you have an IDE, try adding that MCP
+server to your config (see the [MCP Server docs](../../../docs/function-calling/MCP-SERVERS.md) to see how to configure
+them), and modify the agent definition to look like this:
+
+```yaml
+# ...
+
+mcp_servers:
+  - jetbrains # The name of your configured IDE MCP server
+
+global_tools:
+  - fs_read.sh
+  - fs_grep.sh
+  - fs_glob.sh
+  - fs_ls.sh
+  - web_search_loki.sh
+
+# ...
+```

assets/agents/explore/config.yaml

@@ -0,0 +1,78 @@
+name: explore
+description: Fast codebase exploration agent - finds patterns, structures, and relevant files
+version: 1.0.0
+temperature: 0.1
+
+variables:
+  - name: project_dir
+    description: Project directory to explore
+    default: '.'
+
+mcp_servers:
+  - ddg-search
+global_tools:
+  - fs_read.sh
+  - fs_grep.sh
+  - fs_glob.sh
+  - fs_ls.sh
+
+instructions: |
+  You are a codebase explorer. Your job: Search, find, report. Nothing else.
+  
+  ## Your Mission
+  
+  Given a search task, you:
+  1. Search for relevant files and patterns
+  2. Read key files to understand structure
+  3. Report findings concisely
+  4. Signal completion with EXPLORE_COMPLETE
+  
+  ## File Reading Strategy (IMPORTANT - minimize token usage)
+
+  1. **Find first, read second** - Never read a file without knowing why
+  2. **Use grep to locate** - `fs_grep --pattern "struct User" --include "*.rs"` finds exactly where things are
+  3. **Use glob to discover** - `fs_glob --pattern "*.rs" --path src/` finds files by name
+  4. **Read targeted sections** - `fs_read --path "src/main.rs" --offset 50 --limit 30` reads only lines 50-79
+  5. **Never read entire large files** - If a file is 500+ lines, read the relevant section only
+
+  ## Available Actions
+
+  - `fs_grep --pattern "struct User" --include "*.rs"` - Find content across files
+  - `fs_glob --pattern "*.rs" --path src/` - Find files by name pattern
+  - `fs_read --path "src/main.rs"` - Read a file (with line numbers)
+  - `fs_read --path "src/main.rs" --offset 100 --limit 50` - Read lines 100-149 only
+  - `get_structure` - See project layout
+  - `search_content --pattern "struct User"` - Agent-level content search
+  
+  ## Output Format
+  
+  Always end your response with a findings summary:
+  
+  ```
+  FINDINGS:
+  - [Key finding 1]
+  - [Key finding 2]
+  - Relevant files: [list]
+  
+  EXPLORE_COMPLETE
+  ```
+  
+  ## Rules
+  
+  1. **Be fast** - Don't read every file, read representative ones
+  2. **Be focused** - Answer the specific question asked
+  3. **Be concise** - Report findings, not your process
+  4. **Never modify files** - You are read-only
+  5. **Limit reads** - Max 5 file reads per exploration
+  
+  ## Context
+  - Project: {{project_dir}}
+  - CWD: {{__cwd__}}
+  
+  ## Available Tools:
+  {{__tools__}}
+
+conversation_starters:
+  - 'Find how authentication is implemented'
+  - 'What patterns are used for API endpoints'
+  - 'Show me the project structure'

assets/agents/explore/tools.sh

@@ -0,0 +1,175 @@
+#!/usr/bin/env bash
+set -eo pipefail
+
+# shellcheck disable=SC1090
+source "$LLM_PROMPT_UTILS_FILE"
+source "$LLM_ROOT_DIR/agents/.shared/utils.sh"
+
+# @env LLM_OUTPUT=/dev/stdout
+# @env LLM_AGENT_VAR_PROJECT_DIR=.
+# @describe Explore agent tools for codebase search and analysis
+
+_project_dir() {
+  local dir="${LLM_AGENT_VAR_PROJECT_DIR:-.}"
+  (cd "${dir}" 2>/dev/null && pwd) || echo "${dir}"
+}
+
+# Normalize a path to be relative to project root.
+# Strips the project_dir prefix if the LLM passes an absolute path.
+_normalize_path() {
+  local input_path="$1"
+  local project_dir
+  project_dir=$(_project_dir)
+
+  if [[ "${input_path}" == /* ]]; then
+    input_path="${input_path#"${project_dir}"/}"
+  fi
+
+  input_path="${input_path#./}"
+  echo "${input_path}"
+}
+
+# @cmd Get project structure and layout
+get_structure() {
+  local project_dir
+  project_dir=$(_project_dir)
+  
+  info "Project structure:" >> "$LLM_OUTPUT"
+  echo "" >> "$LLM_OUTPUT"
+  
+  local project_info
+  project_info=$(detect_project "${project_dir}")
+
+  {
+  	echo "Type: $(echo "${project_info}" | jq -r '.type')"
+  	echo ""
+
+  	get_tree "${project_dir}" 3
+  } >> "$LLM_OUTPUT"
+}
+
+# @cmd Search for files by name pattern
+# @option --pattern! File name pattern (e.g., "*.rs", "config*", "*test*")
+search_files() {
+	# shellcheck disable=SC2154
+  local pattern="${argc_pattern}"
+  local project_dir
+  project_dir=$(_project_dir)
+  
+  info "Files matching: ${pattern}" >> "$LLM_OUTPUT"
+  echo "" >> "$LLM_OUTPUT"
+  
+  local results
+  results=$(_search_files "${pattern}" "${project_dir}")
+  
+  if [[ -n "${results}" ]]; then
+    echo "${results}" >> "$LLM_OUTPUT"
+  else
+    warn "No files found" >> "$LLM_OUTPUT"
+  fi
+}
+
+# @cmd Search for content in files
+# @option --pattern! Text or regex pattern to search for
+# @option --file-type Filter by file extension (e.g., "rs", "py", "ts")
+search_content() {
+  local pattern="${argc_pattern}"
+  local file_type="${argc_file_type:-}"
+  local project_dir
+  project_dir=$(_project_dir)
+  
+  info "Searching: ${pattern}" >> "$LLM_OUTPUT"
+  echo "" >> "$LLM_OUTPUT"
+  
+  local include_arg=""
+  if [[ -n "${file_type}" ]]; then
+    include_arg="--include=*.${file_type}"
+  fi
+  
+  local results
+  # shellcheck disable=SC2086
+  results=$(grep -rn ${include_arg} "${pattern}" "${project_dir}" 2>/dev/null | \
+    grep -v '/target/' | \
+    grep -v '/node_modules/' | \
+    grep -v '/.git/' | \
+    grep -v '/dist/' | \
+    sed "s|^${project_dir}/||" | \
+    head -30) || true
+  
+  if [[ -n "${results}" ]]; then
+    echo "${results}" >> "$LLM_OUTPUT"
+  else
+    warn "No matches found" >> "$LLM_OUTPUT"
+  fi
+}
+
+# @cmd Read a file's contents
+# @option --path! Path to the file (relative to project root)
+# @option --lines Maximum lines to read (default: 200)
+read_file() {
+  local file_path
+	# shellcheck disable=SC2154
+  file_path=$(_normalize_path "${argc_path}")
+  local max_lines="${argc_lines:-200}"
+  local project_dir
+  project_dir=$(_project_dir)
+  
+  local full_path="${project_dir}/${file_path}"
+  
+  if [[ ! -f "${full_path}" ]]; then
+    error "File not found: ${file_path}" >> "$LLM_OUTPUT"
+    return 1
+  fi
+
+  {
+  	info "File: ${file_path}"
+  	echo ""
+  } >> "$LLM_OUTPUT"
+  
+  head -n "${max_lines}" "${full_path}" >> "$LLM_OUTPUT"
+  
+  local total_lines
+  total_lines=$(wc -l < "${full_path}")
+  if [[ "${total_lines}" -gt "${max_lines}" ]]; then
+    echo "" >> "$LLM_OUTPUT"
+    warn "... truncated (${total_lines} total lines)" >> "$LLM_OUTPUT"
+  fi
+}
+
+# @cmd Find similar files to a given file (for pattern matching)
+# @option --path! Path to the reference file
+find_similar() {
+  local file_path
+  file_path=$(_normalize_path "${argc_path}")
+  local project_dir
+  project_dir=$(_project_dir)
+  
+  local ext="${file_path##*.}"
+  local dir
+  dir=$(dirname "${file_path}")
+  
+  info "Files similar to: ${file_path}" >> "$LLM_OUTPUT"
+  echo "" >> "$LLM_OUTPUT"
+  
+  local results
+  results=$(find "${project_dir}/${dir}" -maxdepth 1 -type f -name "*.${ext}" \
+    ! -name "$(basename "${file_path}")" \
+    ! -name "*test*" \
+    ! -name "*spec*" \
+    2>/dev/null | sed "s|^${project_dir}/||" | head -5)
+  
+  if [[ -n "${results}" ]]; then
+    echo "${results}" >> "$LLM_OUTPUT"
+  else
+    results=$(find "${project_dir}" -type f -name "*.${ext}" \
+      ! -name "$(basename "${file_path}")" \
+      ! -name "*test*" \
+      -not -path '*/target/*' \
+      2>/dev/null | sed "s|^${project_dir}/||" | head -5)
+    if [[ -n "${results}" ]]; then
+      echo "${results}" >> "$LLM_OUTPUT"
+    else
+      warn "No similar files found" >> "$LLM_OUTPUT"
+    fi
+  fi
+}

assets/agents/file-reviewer/README.md

@@ -0,0 +1,35 @@
+# File Reviewer
+
+A specialized worker agent that reviews a single file's diff for bugs, style issues, and cross-cutting concerns.
+
+This agent is designed to be spawned by the **[Code Reviewer](../code-reviewer/README.md)** agent. It focuses deeply on 
+one file while communicating with sibling agents to catch issues that span multiple files.
+
+## Features
+
+- 🔍 **Deep Analysis**: Focuses on bugs, logic errors, security issues, and style problems in a single file.
+- 🗣️ **Teammate Communication**: Sends and receives alerts to/from sibling reviewers about interface or dependency 
+  changes.
+- 🎯 **Targeted Reading**: Reads only relevant context around changed lines to stay efficient.
+- 🏷️ **Structured Findings**: Categorizes issues by severity (🔴 Critical, 🟡 Warning, 🟢 Suggestion, 💡 Nitpick).
+
+## Pro-Tip: Use an IDE MCP Server for Improved Performance
+Many modern IDEs now include MCP servers that let LLMs perform operations within the IDE itself and use IDE tools. Using
+an IDE's MCP server dramatically improves the performance of coding agents. So if you have an IDE, try adding that MCP
+server to your config (see the [MCP Server docs](../../../docs/function-calling/MCP-SERVERS.md) to see how to configure
+them), and modify the agent definition to look like this:
+
+```yaml
+# ...
+
+mcp_servers:
+  - jetbrains # The name of your configured IDE MCP server
+
+global_tools:
+  - fs_read.sh
+  - fs_grep.sh
+  - fs_glob.sh
+
+# ...
+```
+

assets/agents/file-reviewer/config.yaml

@@ -0,0 +1,113 @@
+name: file-reviewer
+description: Reviews a single file's diff for bugs, style issues, and cross-cutting concerns
+version: 1.0.0
+temperature: 0.1
+
+variables:
+  - name: project_dir
+    description: Project directory for context
+    default: '.'
+
+global_tools:
+  - fs_read.sh
+  - fs_grep.sh
+  - fs_glob.sh
+
+instructions: |
+  You are a precise code reviewer. You review ONE file's diff and produce structured findings.
+
+  ## Your Mission
+
+  You receive a git diff for a single file. Your job:
+  1. Analyze the diff for bugs, logic errors, security issues, and style problems
+  2. Read surrounding code for context (use `fs_read` with targeted offsets)
+  3. Check your inbox for cross-cutting alerts from sibling reviewers
+  4. Send alerts to siblings if you spot cross-file issues
+  5. Return structured findings
+
+  ## Input
+
+  You receive:
+  - The file path being reviewed
+  - The git diff for that file
+  - A sibling roster (other file-reviewers and which files they're reviewing)
+
+  ## Cross-Cutting Alerts (Teammate Pattern)
+
+  After analyzing your file, check if changes might affect sibling files:
+  - **Interface changes**: If a function signature changed, alert siblings reviewing callers
+  - **Type changes**: If a type/struct changed, alert siblings reviewing files that use it
+  - **Import changes**: If exports changed, alert siblings reviewing importers
+  - **Config changes**: Alert all siblings if config format changed
+
+  To alert a sibling:
+  ```
+  agent__send_message --to <sibling_agent_id> --message "ALERT: <description of cross-file concern>"
+  ```
+
+  Check your inbox periodically for alerts from siblings:
+  ```
+  agent__check_inbox
+  ```
+
+  If you receive an alert, incorporate it into your findings under a "Cross-File Concerns" section.
+
+  ## File Reading Strategy
+
+  1. **Read changed lines' context:** Use `fs_read --path "file" --offset <start> --limit 50` to see surrounding code
+  2. **Grep for usage:** `fs_grep --pattern "function_name" --include "*.rs"` to find callers
+  3. **Never read entire large files:** Target the changed regions only
+  4. **Max 5 file reads:** Be efficient
+
+  ## Output Format
+
+  Structure your response EXACTLY as:
+
+  ```
+  ## File: <file_path>
+
+  ### Summary
+  <1-2 sentence summary of the changes>
+
+  ### Findings
+
+  #### <finding_title>
+  - **Severity**: 🔴 CRITICAL | 🟡 WARNING | 🟢 SUGGESTION | 💡 NITPICK
+  - **Lines**: <start_line>-<end_line>
+  - **Description**: <clear explanation of the issue>
+  - **Suggestion**: <how to fix it>
+
+  #### <next_finding_title>
+  ...
+
+  ### Cross-File Concerns
+  <any issues received from siblings or that you alerted siblings about>
+  <"None" if no cross-file concerns>
+
+  REVIEW_COMPLETE
+  ```
+
+  ## Severity Guide
+
+  | Severity | When to use |
+  |----------|------------|
+  | 🔴 CRITICAL | Bugs, security vulnerabilities, data loss risks, crashes |
+  | 🟡 WARNING | Logic errors, performance issues, missing error handling, race conditions |
+  | 🟢 SUGGESTION | Better patterns, improved readability, missing docs for public APIs |
+  | 💡 NITPICK | Style preferences, minor naming issues, formatting |
+
+  ## Rules
+
+  1. **Be specific:** Reference exact line numbers and code
+  2. **Be actionable:** Every finding must have a suggestion
+  3. **Don't nitpick formatting:** If a formatter/linter exists (check for .rustfmt.toml, .prettierrc, etc.)
+  4. **Focus on the diff:** Don't review unchanged code unless it's directly affected
+  5. **Never modify files:** You are read-only
+  6. **Always end with REVIEW_COMPLETE**
+
+  ## Context
+  - Project: {{project_dir}}
+  - CWD: {{__cwd__}}
+  
+  ## Available Tools:
+  {{__tools__}}

assets/agents/file-reviewer/tools.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+set -eo pipefail
+
+# shellcheck disable=SC1090
+source "$LLM_PROMPT_UTILS_FILE"
+source "$LLM_ROOT_DIR/agents/.shared/utils.sh"
+
+# @env LLM_OUTPUT=/dev/stdout
+# @env LLM_AGENT_VAR_PROJECT_DIR=.
+# @describe File reviewer tools for single-file code review
+
+_project_dir() {
+  local dir="${LLM_AGENT_VAR_PROJECT_DIR:-.}"
+  (cd "${dir}" 2>/dev/null && pwd) || echo "${dir}"
+}
+
+# @cmd Get project structure to understand codebase layout
+get_structure() {
+  local project_dir
+  project_dir=$(_project_dir)
+
+  info "Project structure:" >> "$LLM_OUTPUT"
+  echo "" >> "$LLM_OUTPUT"
+
+  local project_info
+  project_info=$(detect_project "${project_dir}")
+
+  {
+    echo "Type: $(echo "${project_info}" | jq -r '.type')"
+    echo ""
+    get_tree "${project_dir}" 2
+  } >> "$LLM_OUTPUT"
+}

assets/agents/jira-helper/README.md

@@ -1,32 +0,0 @@
-# Jira AI Agent
-
-## Overview
-
-The Jira AI Agent is designed to assist with managing tasks within Jira projects, providing capabilities such as creating, searching, updating, assigning, linking, and commenting on issues. Its primary purpose is to help software engineers seamlessly integrate Jira into their workflows through an AI-driven interface.
-
-## Configuration
-
-### Variables
-
-This agent accepts the following variables:
-
-- **config**: Specifies the configuration file for the Jira CLI. This configuration should be located at `~/.config/.jira/<config_name>.yml`. Example: `work`.
-- **project**: The Jira project key where operations are executed. Example: `PAN`.
-
-### Customization
-
-#### For a User's Specific Jira Instance
-
-1. **Config File Setup**:
-   - Users must ensure there is a configuration file for their Jira instance located at `~/.config/.jira/`. The filename should match the `config` variable value provided to the agent (e.g., for `config` set to `work`, ensure a `work.yml` exists).
-
-2. **State, Issue Type, and Priority Customization**:
-   - Modify the functions `_issue_type_choice` and `_issue_state_choice` in `tools.sh` to reflect the specific issue types and states used in your Jira instance.
-   - The `priority` for new issues can be modified directly through the `create_issue()` function in `tools.sh` with options set to the values available in your Jira instance (e.g., Medium, Highest, etc.).
-
-## How the Agent Works
-
-The agent works by utilizing provided variables to interact with Jira CLI commands through `tools.sh`. The `config` variable links directly to a `.yml` configuration file that contains connections settings for a Jira instance, enabling the agent to perform operations such as issue creation or status updates.
-
-- **Configuration Linkage**: The `config` parameters specified during the execution must have a corresponding `.yml` configuration file at `~/.config/.jira/`, which contains the required Jira server details like login credentials and server URL.
-- **Jira Command Execution**: The agent uses predefined functions within `tools.sh` to execute Jira operations. These functions rely on the configuration and project variable inputs to construct and execute the appropriate Jira CLI commands.

assets/agents/jira-helper/config.yaml

@@ -1,25 +0,0 @@
-name: Jira Agent
-description: An AI agent that can assist with Jira tasks such as creating issues, searching for issues, and updating issues.
-version: 0.1.0
-agent_session: temp
-instructions: |
-  You are a AI agent designed to assist with managing Jira tasks and helping software engineers
-  utilize and integrate Jira into their workflows. You can create, search, update, assign, link, and comment on issues in Jira.
-
-  When you create issues, the general format of the issues is broken into two sections: Description, and User Acceptance Criteria. The Description section gives context and details about the issue, and the User Acceptance Criteria section provides bullet points that function like a checklist of all the things that must be completed in order for the issue to be considered done.
-  
-  Create issues under the {{project}} Jira project.
-
-
-  Available tools:
-  {{__tools__}}
-variables:
-  - name: config
-    description: The configuration to use for the Jira CLI; e.g. work
-  - name: project
-    description: The Jira project to operate on; e.g. PAN
-conversation_starters:
-  - What are the latest issues in my Jira project?
-  - Can you create a new Jira issue for me?
-  - What are my open Jira issues?
-  - Can you search for issues with the label "bug" in my Jira project?

assets/agents/jira-helper/tools.sh

@@ -1,259 +0,0 @@
-#!/usr/bin/env bash
-# shellcheck disable=SC2154
-# shellcheck disable=SC2046
-set -e
-
-# @meta require-tools jira
-# @env LLM_OUTPUT=/dev/stdout The output path
-# @env LLM_AGENT_VAR_CONFIG! The configuration to use for the Jira CLI; e.g. work
-# @env LLM_AGENT_VAR_PROJECT! The Jira project to operate on; e.g. PAN
-
-# @cmd Fetch my Jira username
-get_jira_username() {
-  declare config_file="$HOME/.config/.jira/${LLM_AGENT_VAR_CONFIG}.yml"
-
-  jira me -c "$config_file" >> "$LLM_OUTPUT"
-}
-
-# @cmd Query for jira issues using a Jira Query Language (JQL) query
-# @option --jql-query! The Jira Query Language query to execute
-# @option --project! $LLM_AGENT_VAR_PROJECT <PROJECT> Jira project to operate on; e.g. PAN
-query_jira_issues() {
-  declare config_file="$HOME"/.config/.jira/"${LLM_AGENT_VAR_CONFIG}".yml
-
-  jira issue ls \
-    --project "$argc_project" \
-    -q "$argc_jql_query" \
-    --plain \
-    -c "$config_file" >> "$LLM_OUTPUT"
-}
-
-# @cmd Assign a Jira issue to the specified user
-# @option --issue-key! The Jira issue key, e.g. ISSUE-1
-# @option --assignee! The email or display name of the user to assign the issue to
-# @option --project! $LLM_AGENT_VAR_PROJECT <PROJECT> Jira project to operate on; e.g. PAN
-assign_jira_issue() {
-  declare config_file="$HOME"/.config/.jira/"${LLM_AGENT_VAR_CONFIG}".yml
-
-  jira issue assign \
-    --project "$argc_project" \
-    "$argc_issue_key" "$argc_assignee" \
-    -c "$config_file" >> "$LLM_OUTPUT"
-}
-
-# @cmd View a Jira issue
-# @option --issue-key! The Jira issue key, e.g. ISSUE-1
-# @option --project! $LLM_AGENT_VAR_PROJECT <PROJECT> Jira project to operate on; e.g. PAN
-view_issue() {
-  declare config_file="$HOME"/.config/.jira/"${LLM_AGENT_VAR_CONFIG}".yml
-
-  jira issue view \
-    "$argc_issue_key" \
-    --project "$argc_project" \
-    --comments 20 \
-    --plain \
-    -c "$config_file" >> "$LLM_OUTPUT"
-}
-
-# @cmd Transition a Jira issue to a different state
-# @option --issue-key! The Jira issue key, e.g. ISSUE-1
-# @option --state![`_issue_state_choice`] The Jira state of the issue
-# @option --comment Add a comment to the issue
-# @option --resolution Set resolution
-# @option --project! $LLM_AGENT_VAR_PROJECT <PROJECT> Jira project to operate on; e.g. PAN
-transition_issue() {
-  declare config_file="$HOME"/.config/.jira/"${LLM_AGENT_VAR_CONFIG}".yml
-  declare -a flags=()
-
-  if [[ -n $argc_comment ]]; then
-    flags+=("--comment '${argc_comment}'")
-  fi
-
-  if [[ -n $argc_resolution ]]; then
-    flags+=("--resolution ${argc_resolution}")
-  fi
-
-  jira issue move \
-    --project "$argc_project" \
-    "$argc_issue_key" "$argc_state" "$(echo "${flags[*]}" | xargs)" \
-    -c "$config_file" >> "$LLM_OUTPUT"
-}
-
-# @cmd Create a new Jira issue
-# @option --type![`_issue_type_choice`]
-# @option --summary! Issue summary or title
-# @option --description! Issue description
-# @option --parent-issue-key Parent issue key can be used to attach epic to an issue. And, this field is mandatory when creating a sub-task
-# @option --assignee Issue assignee (username, email or display name)
-# @option --fix-version* String array of Release info (fixVersions); for example: `--fix-version 'some fix version 1' --fix-version 'version 2'`
-# @option --affects-version* String array of Release info (affectsVersions); for example: `--affects-version 'the first affected version' --affects-version 'v1.2.3'`
-# @option --label* String array of issue labels; for example: `--label backend --label custom`
-# @option --component* String array of issue components; for example: `--component backend --component core`
-# @option --original-estimate The original estimate of the issue
-# @option --priority[=Medium|Highest|High|Low|Lowest] The priority of the issue
-# @option --project! $LLM_AGENT_VAR_PROJECT <PROJECT> Jira project to operate on; e.g. PAN
-create_issue() {
-  declare config_file="$HOME"/.config/.jira/"${LLM_AGENT_VAR_CONFIG}".yml
-  declare -a flags=()
-
-  if [[ -n $argc_assignee ]]; then
-    flags+=("--assignee $argc_assignee")
-  fi
-
-  if [[ -n $argc_original_estimate ]]; then
-    flags+=("--original-estimate $argc_original_estimate")
-  fi
-
-  if [[ -n $argc_priority ]]; then
-    flags+=("--priority $argc_priority")
-  fi
-
-  if [[ -n $argc_fix_version ]]; then
-    for version in "${argc_fix_version[@]}"; do
-      flags+=("--fix-version '$version'")
-    done
-  fi
-
-  if [[ -n $argc_affects_version ]]; then
-    for version in "${argc_affects_version[@]}"; do
-      flags+=("--affects-version '$version'")
-    done
-  fi
-
-  if [[ -n $argc_components ]]; then
-    for component in "${argc_components[@]}"; do
-      flags+=("--affects-version '$component'")
-    done
-  fi
-
-  jira issue create \
-    --project "$argc_project" \
-    --type "$argc_type" \
-    --summary "$argc_summary" \
-    --body "$argc_description" \
-    --parent "$argc_parent_issue_key" \
-    -c "$config_file" \
-    --no-input $(echo "${flags[*]}" | xargs) >> "$LLM_OUTPUT"
-}
-
-# @cmd Link two issues together
-# @option --inward-issue-key! Issue key of the source issue, eg: ISSUE-1
-# @option --outward-issue-key! Issue key of the target issue, eg: ISSUE-2
-# @option --issue-link-type! Relationship between two issues, eg: Duplicates, Blocks etc.
-# @option --project! $LLM_AGENT_VAR_PROJECT <PROJECT> Jira project to operate on; e.g. PAN
-link_issues() {
-  declare config_file="$HOME"/.config/.jira/"${LLM_AGENT_VAR_CONFIG}".yml
-
-  jira issue link \
-    --project "$argc_project" \
-    "${argc_inward_issue_key}" "${argc_outward_issue_key}" "${argc_issue_link_type}" \
-    -c "$config_file" >> "$LLM_OUTPUT"
-}
-
-# @cmd Unlink or disconnect two issues from each other, if already connected.
-# @option --inward-issue-key! Issue key of the source issue, eg: ISSUE-1
-# @option --outward-issue-key! Issue key of the target issue, eg: ISSUE-2.
-# @option --project! $LLM_AGENT_VAR_PROJECT <PROJECT> Jira project to operate on; e.g. PAN
-unlink_issues() {
-  declare config_file="$HOME"/.config/.jira/"${LLM_AGENT_VAR_CONFIG}".yml
-
-  jira issue unlink \
-    --project "$argc_project" \
-    "${argc_inward_issue_key}" "${argc_outward_issue_key}" \
-    -c "$config_file" >> "$LLM_OUTPUT"
-}
-
-# @cmd Add a comment to an issue
-# @option --issue-key! Issue key of the source issue, eg: ISSUE-1
-# @option --comment-body! Body of the comment you want to add
-# @option --project! $LLM_AGENT_VAR_PROJECT <PROJECT> Jira project to operate on; e.g. PAN
-add_comment_to_issue() {
-  declare config_file="$HOME"/.config/.jira/"${LLM_AGENT_VAR_CONFIG}".yml
-
-  jira issue comment add \
-    --project "$argc_project" \
-    "${argc_issue_key}" "${argc_comment_body}" \
-    --no-input \
-    -c "$config_file" >> "$LLM_OUTPUT"
-}
-
-# @cmd Edit an existing Jira issue
-# @option --issue-key! The Jira issue key, e.g. ISSUE-1
-# @option --parent Link to a parent key
-# @option --summary Edit summary or title
-# @option --description Edit description
-# @option --priority Edit priority
-# @option --assignee Edit assignee (email or display name)
-# @option --label Append labels
-# @option --project! $LLM_AGENT_VAR_PROJECT <PROJECT> Jira project to operate on; e.g. PAN
-edit_issue() {
-  declare config_file="$HOME"/.config/.jira/"${LLM_AGENT_VAR_CONFIG}".yml
-  declare -a flags=()
-
-  if [[ -n $argc_parent ]]; then
-    flags+=("--parent $argc_parent")
-  fi
-
-  if [[ -n $argc_summary ]]; then
-    flags+=("--summary $argc_summary")
-  fi
-
-  if [[ -n $argc_description ]]; then
-    flags+=("--body $argc_description")
-  fi
-
-  if [[ -n $argc_priority ]]; then
-    flags+=("--priority $argc_priority")
-  fi
-
-  if [[ -n $argc_assignee ]]; then
-    flags+=("--assignee $argc_assignee")
-  fi
-
-  if [[ -n $argc_label ]]; then
-    flags+=("--label $argc_label")
-  fi
-
-  jira issue edit \
-    --project "$argc_project" \
-    "$argc_issue_key" $(echo "${flags[*]}" | xargs) \
-    --no-input \
-    -c "$config_file" >> "$LLM_OUTPUT"
-}
-
-_issue_type_choice() {
-  if [[ $LLM_AGENT_VAR_CONFIG == "work" ]]; then
-    echo "Story"
-    echo "Task"
-    echo "Bug"
-    echo "Technical Debt"
-    echo "Sub-task"
-  elif [[ $LLM_AGENT_VAR_CONFIG == "sideproject" ]]; then
-    echo "Task"
-    echo "Story"
-    echo "Bug"
-    echo "Epic"
-  fi
-}
-
-_issue_state_choice() {
-  if [[ $LLM_AGENT_VAR_CONFIG == "work" ]]; then
-    echo "Ready for Dev"
-    echo "CODE REVIEW"
-    echo "IN PROGRESS"
-    echo "Backlog"
-    echo "Done"
-    echo "TESTING"
-  elif [[ $LLM_AGENT_VAR_CONFIG == "sideproject" ]]; then
-    echo "IN CLARIFICATION"
-    echo "NEED TO CLARIFY"
-    echo "READY TO WORK"
-    echo "RELEASE BACKLOG"
-    echo "REOPEN"
-    echo "CODE REVIEW"
-    echo "IN PROGRESS"
-    echo "IN TESTING"
-    echo "TO TEST"
-    echo "DONE"
-  fi
-}

assets/agents/oracle/README.md

@@ -0,0 +1,39 @@
+# Oracle
+
+An AI agent specialized in high-level architecture, complex debugging, and design decisions.
+
+This agent is designed to be delegated to by the **[Sisyphus](../sisyphus/README.md)** agent when deep reasoning, architectural advice,
+or complex problem-solving is required. Sisyphus acts as the coordinator, while Oracle provides the expert analysis and
+recommendations.
+
+It can also be used as a standalone tool for design reviews and solving difficult technical challenges.
+
+## Features
+
+- 🏛️ System architecture and design patterns
+- 🐛 Complex debugging and root cause analysis
+- ⚖️ Tradeoff analysis and technology selection
+- 📝 Code review and best practices advice
+- 🧠 Deep reasoning for ambiguous problems
+
+## Pro-Tip: Use an IDE MCP Server for Improved Performance
+Many modern IDEs now include MCP servers that let LLMs perform operations within the IDE itself and use IDE tools. Using
+an IDE's MCP server dramatically improves the performance of coding agents. So if you have an IDE, try adding that MCP
+server to your config (see the [MCP Server docs](../../../docs/function-calling/MCP-SERVERS.md) to see how to configure
+them), and modify the agent definition to look like this:
+
+```yaml
+# ...
+
+mcp_servers:
+  - jetbrains # The name of your configured IDE MCP server
+
+global_tools:
+  - fs_read.sh
+  - fs_grep.sh
+  - fs_glob.sh
+  - fs_ls.sh
+  - web_search_loki.sh
+
+# ...
+```

assets/agents/oracle/config.yaml

@@ -0,0 +1,85 @@
+name: oracle
+description: High-IQ advisor for architecture, debugging, and complex decisions
+version: 1.0.0
+temperature: 0.2
+
+variables:
+  - name: project_dir
+    description: Project directory for context
+    default: '.'
+
+mcp_servers:
+  - ddg-search
+global_tools:
+  - fs_read.sh
+  - fs_grep.sh
+  - fs_glob.sh
+  - fs_ls.sh
+
+instructions: |
+  You are Oracle - a senior architect and debugger consulted for complex decisions.
+  
+  ## Your Role
+  
+  You are READ-ONLY. You analyze, advise, and recommend. You do NOT implement.
+  
+  ## When You're Consulted
+  
+  1. **Architecture Decisions**: Multi-system tradeoffs, design patterns, technology choices
+  2. **Complex Debugging**: After 2+ failed fix attempts, deep analysis needed
+  3. **Code Review**: Evaluating proposed designs or implementations
+  4. **Risk Assessment**: Security, performance, or reliability concerns
+  
+  ## File Reading Strategy (IMPORTANT - minimize token usage)
+
+  1. **Use grep to find relevant code** - `fs_grep --pattern "auth" --include "*.rs"` finds where things are
+  2. **Read only what you need** - `fs_read --path "src/main.rs" --offset 50 --limit 30` reads lines 50-79
+  3. **Never read entire large files** - If 500+ lines, grep first, then read the relevant section
+  4. **Use glob to discover files** - `fs_glob --pattern "*.rs" --path src/`
+
+  ## Your Process
+
+  1. **Understand**: Use grep/glob to find relevant code, then read targeted sections
+  2. **Analyze**: Consider multiple angles and tradeoffs
+  3. **Recommend**: Provide clear, actionable advice
+  4. **Justify**: Explain your reasoning
+  
+  ## Output Format
+  
+  Structure your response as:
+  
+  ```
+  ## Analysis
+  [Your understanding of the situation]
+  
+  ## Recommendation
+  [Clear, specific advice]
+  
+  ## Reasoning
+  [Why this is the right approach]
+  
+  ## Risks/Considerations
+  [What to watch out for]
+  
+  ORACLE_COMPLETE
+  ```
+  
+  ## Rules
+  
+  1. **Never modify files** - You advise, others implement
+  2. **Be thorough** - Read all relevant context before advising
+  3. **Be specific** - General advice isn't helpful
+  4. **Consider tradeoffs** - There are rarely perfect solutions
+  5. **Stay focused** - Answer the specific question asked
+  
+  ## Context
+  - Project: {{project_dir}}
+  - CWD: {{__cwd__}}
+  
+  ## Available Tools:
+  {{__tools__}}
+
+conversation_starters:
+  - 'Review this architecture design'
+  - 'Help debug this complex issue'
+  - 'Evaluate these implementation options'

assets/agents/oracle/tools.sh

@@ -0,0 +1,150 @@
+#!/usr/bin/env bash
+set -eo pipefail
+
+# shellcheck disable=SC1090
+source "$LLM_PROMPT_UTILS_FILE"
+source "$LLM_ROOT_DIR/agents/.shared/utils.sh"
+
+# @env LLM_OUTPUT=/dev/stdout
+# @env LLM_AGENT_VAR_PROJECT_DIR=.
+# @describe Oracle agent tools for analysis and consultation (read-only)
+
+_project_dir() {
+  local dir="${LLM_AGENT_VAR_PROJECT_DIR:-.}"
+  (cd "${dir}" 2>/dev/null && pwd) || echo "${dir}"
+}
+
+# Normalize a path to be relative to project root.
+# Strips the project_dir prefix if the LLM passes an absolute path.
+_normalize_path() {
+  local input_path="$1"
+  local project_dir
+  project_dir=$(_project_dir)
+
+  if [[ "${input_path}" == /* ]]; then
+    input_path="${input_path#"${project_dir}"/}"
+  fi
+
+  input_path="${input_path#./}"
+  echo "${input_path}"
+}
+
+# @cmd Read a file for analysis
+# @option --path! Path to the file (relative to project root)
+read_file() {
+  local project_dir
+  project_dir=$(_project_dir)
+  local file_path
+  # shellcheck disable=SC2154
+  file_path=$(_normalize_path "${argc_path}")
+  local full_path="${project_dir}/${file_path}"
+  
+  if [[ ! -f "${full_path}" ]]; then
+    error "File not found: ${file_path}" >> "$LLM_OUTPUT"
+    return 1
+  fi
+
+  {
+  	info "Reading: ${file_path}"
+  	echo ""
+  	cat "${full_path}"
+  } >> "$LLM_OUTPUT"
+}
+
+# @cmd Get project structure and type
+get_project_info() {
+  local project_dir
+  project_dir=$(_project_dir)
+  
+  local project_info
+  project_info=$(detect_project "${project_dir}")
+
+  {
+		info "Project Analysis" >> "$LLM_OUTPUT"
+		cat <<-EOF
+
+			Type: $(echo "${project_info}" | jq -r '.type')
+			Build: $(echo "${project_info}" | jq -r '.build')
+			Test: $(echo "${project_info}" | jq -r '.test')
+
+		EOF
+
+		info "Structure:" >> "$LLM_OUTPUT"
+		get_tree "${project_dir}" 3
+  } >> "$LLM_OUTPUT"
+}
+
+# @cmd Search for patterns in the codebase
+# @option --pattern! Pattern to search for
+# @option --file-type Filter by extension (e.g., "rs", "py")
+search_code() {
+  local file_type="${argc_file_type:-}"
+  local project_dir
+  project_dir=$(_project_dir)
+
+  # shellcheck disable=SC2154
+  info "Searching: ${argc_pattern}" >> "$LLM_OUTPUT"
+  echo "" >> "$LLM_OUTPUT"
+  
+  local include_arg=""
+  if [[ -n "${file_type}" ]]; then
+    include_arg="--include=*.${file_type}"
+  fi
+  
+  local results
+  # shellcheck disable=SC2086
+  results=$(grep -rn ${include_arg} "${argc_pattern}" "${project_dir}" 2>/dev/null | \
+    grep -v '/target/' | \
+    grep -v '/node_modules/' | \
+    grep -v '/.git/' | \
+    sed "s|^${project_dir}/||" | \
+    head -30) || true
+  
+  if [[ -n "${results}" ]]; then
+    echo "${results}" >> "$LLM_OUTPUT"
+  else
+    warn "No matches found" >> "$LLM_OUTPUT"
+  fi
+}
+
+# @cmd Run a read-only command for analysis (e.g., git log, cargo tree)
+# @option --command! Command to run
+analyze_with_command() {
+  local project_dir
+  project_dir=$(_project_dir)
+  
+  local dangerous_patterns="rm |>|>>|mv |cp |chmod |chown |sudo|curl.*\\||wget.*\\|"
+  # shellcheck disable=SC2154
+  if echo "${argc_command}" | grep -qE "${dangerous_patterns}"; then
+    error "Command appears to modify files or be dangerous. Oracle is read-only." >> "$LLM_OUTPUT"
+    return 1
+  fi
+  
+  info "Running: ${argc_command}" >> "$LLM_OUTPUT"
+  echo "" >> "$LLM_OUTPUT"
+  
+  local output
+  output=$(cd "${project_dir}" && eval "${argc_command}" 2>&1) || true
+  echo "${output}" >> "$LLM_OUTPUT"
+}
+
+# @cmd List directory contents
+# @option --path Path to list (default: project root)
+list_directory() {
+  local dir_path
+  dir_path=$(_normalize_path "${argc_path:-.}")
+  local project_dir
+  project_dir=$(_project_dir)
+  local full_path="${project_dir}/${dir_path}"
+  
+  if [[ ! -d "${full_path}" ]]; then
+    error "Directory not found: ${dir_path}" >> "$LLM_OUTPUT"
+    return 1
+  fi
+
+  {
+		info "Contents of: ${dir_path}"
+		echo ""
+		ls -la "${full_path}"
+  } >> "$LLM_OUTPUT"
+}

assets/agents/report-writer/README.md

@@ -0,0 +1,46 @@
+# report-writer
+
+A tiny, focused sub-agent that turns a set of research findings into a
+single coherent final report. Reads only what it is given — does not
+do independent research, does not access the web, does not invent
+facts. It exists as a focused tool for orchestrating agents to
+delegate the writing phase to.
+
+## Why a separate agent?
+
+This is an example of the **agent-as-tool** pattern in graph agents.
+The `deep-research` graph agent's `synthesize` node is an `agent` node
+that spawns this one (see `assets/agents/deep-research/graph.yaml`).
+Separating the role has two practical benefits:
+
+- The orchestrating agent can use a cheap model (or a high-temperature
+  exploratory one) for the research phase, while letting the writing
+  phase use a different (typically lower-temperature, possibly larger)
+  model dedicated to coherent prose.
+- The writing prompt is owned by this agent's `config.yaml` rather
+  than buried inside another agent's graph. You can polish it
+  independently without touching the research flow.
+
+## Standalone use
+
+You can also use this agent directly if you have a set of findings you
+want polished:
+
+```sh
+loki -a report-writer "Topic: X. Findings: <paste findings here>"
+```
+
+It will produce a single Markdown report following the rules in its
+system prompt: executive summary at the top, grouped sections by
+related sub-questions, every inline citation preserved verbatim, and a
+final "Open questions / disagreements" section.
+
+## What it will NOT do
+
+- Search the web, fetch URLs, query an MCP server, or use any tool.
+  It has no tools configured.
+- Invent facts beyond what is in the findings you give it.
+- Strip or rewrite citations.
+
+These constraints are the point of the agent existing: a writer that
+the orchestrator can trust to stay in its lane.

assets/agents/report-writer/config.yaml

@@ -0,0 +1,34 @@
+name: report-writer
+description: Polishes research findings into a clear, citation-preserving final report
+version: 1.0.0
+temperature: 0.2
+
+instructions: |
+  You are a technical writer. You will be given:
+    - a research topic
+    - a set of findings, organized per sub-question, with inline
+      citations next to each claim
+    - a source-credibility assessment of the cited sources
+
+  Your job is to produce a single, well-organized final report:
+
+  Rules:
+    - Use ONLY the findings provided. Do not introduce facts from
+      your own memory. Do not speculate beyond what the findings
+      support.
+    - Preserve every inline citation. If a sentence in the findings
+      had a URL or DOI, the equivalent sentence in your report must
+      keep the same citation.
+    - Lead with a 2-3 sentence executive summary at the top.
+    - Organize the body so that related sub-questions are grouped,
+      not strictly one section per question. The findings are raw
+      material; the report should read as a single coherent answer
+      to the original topic.
+    - End with a short "Open questions / disagreements" section
+      naming anything the findings flagged as unresolved or
+      contested.
+
+  Output plain Markdown. No metadata, no JSON wrapper.
+
+conversation_starters:
+  - "Polish these findings into a cited report"

assets/agents/sisyphus/README.md

@@ -0,0 +1,40 @@
+# Sisyphus
+
+The main coordinator agent for the Loki coding ecosystem, providing a powerful CLI interface for code generation and
+project management similar to OpenCode, ClaudeCode, Codex, or Gemini CLI.
+
+_Inspired by the Sisyphus and Oracle agents of OpenCode._
+
+Sisyphus acts as the primary entry point, capable of handling complex tasks by coordinating specialized sub-agents:
+- **[Coder](../coder/README.md)**: For implementation and file modifications.
+- **[Explore](../explore/README.md)**: For codebase understanding and research.
+- **[Oracle](../oracle/README.md)**: For architecture and complex reasoning.
+
+## Features
+
+- 🤖 **Coordinator**: Manages multi-step workflows and delegates to specialized agents.
+- 💻 **CLI Coding**: Provides a natural language interface for writing and editing code.
+- 🔄 **Task Management**: Tracks progress and context across complex operations.
+- 🛠️ **Tool Integration**: Seamlessly uses system tools for building, testing, and file manipulation.
+
+## Pro-Tip: Use an IDE MCP Server for Improved Performance
+Many modern IDEs (JetBrains, VS Code, Cursor, Zed, etc.) expose MCP servers that let LLMs use IDE tools directly. Using
+one dramatically improves the performance of coding agents. If you have one, add it to your loki config (see the
+[MCP Server docs](../../../docs/function-calling/MCP-SERVERS.md)) and reference it in this agent's `mcp_servers:` list:
+
+```yaml
+# ...
+
+mcp_servers:
+  - your-ide-mcp-server
+
+global_tools:
+  - fs_read.sh
+  - fs_grep.sh
+  - fs_glob.sh
+  - fs_ls.sh
+  - web_search_loki.sh
+  - execute_command.sh
+
+# ...
+```

assets/agents/sisyphus/config.yaml

@@ -0,0 +1,258 @@
+name: sisyphus
+description: OpenCode-style orchestrator - classifies intent, delegates to specialists, tracks progress with todos
+version: 2.0.0
+temperature: 0.1
+
+agent_session: temp
+auto_continue: true
+max_auto_continues: 25
+inject_todo_instructions: true
+
+can_spawn_agents: true
+max_concurrent_agents: 4
+max_agent_depth: 3
+inject_spawn_instructions: true
+summarization_threshold: 8000
+
+variables:
+  - name: project_dir
+    description: Project directory to work in
+    default: '.'
+  - name: auto_confirm
+    description: Auto-confirm command execution
+    default: '1'
+
+mcp_servers:
+  - ddg-search
+global_tools:
+  - fs_read.sh
+  - fs_grep.sh
+  - fs_glob.sh
+  - fs_ls.sh
+  - execute_command.sh
+
+instructions: |
+  You are Sisyphus - an orchestrator that drives coding tasks to completion.
+
+  Your job: Classify -> Delegate -> Verify -> Complete
+
+  ## Intent Classification (BEFORE every action)
+
+  | Type | Signal | Action |
+  |------|--------|--------|
+  | Trivial | Single file, known location, typo fix | Do it yourself with tools |
+  | Exploration | "Find X", "Where is Y", "List all Z" | Spawn `explore` agent |
+  | Implementation | "Add feature", "Fix bug", "Write code" | Spawn `coder` agent |
+  | Architecture/Design | See oracle triggers below | Spawn `oracle` agent |
+  | Ambiguous | Unclear scope, multiple interpretations | ASK the user via `user__ask` or `user__input` |
+
+  ### Oracle Triggers (MUST spawn oracle when you see these)
+
+  Spawn `oracle` ANY time the user asks about:
+  - **"How should I..."** / **"What's the best way to..."** -- design/approach questions
+  - **"Why does X keep..."** / **"What's wrong with..."** -- complex debugging (not simple errors)
+  - **"Should I use X or Y?"** -- technology or pattern choices
+  - **"How should this be structured?"** -- architecture and organization
+  - **"Review this"** / **"What do you think of..."** -- code/design review
+  - **Tradeoff questions** -- performance vs readability, complexity vs flexibility
+  - **Multi-component questions** -- anything spanning 3+ files or modules
+  - **Vague/open-ended questions** -- "improve this", "make this better", "clean this up"
+
+  **CRITICAL**: Do NOT answer architecture/design questions yourself. You are a coordinator.
+  Even if you think you know the answer, oracle provides deeper, more thorough analysis.
+  The only exception is truly trivial questions about a single file you've already read.
+
+  ### Agent Specializations
+
+  | Agent | Use For | Characteristics |
+  |-------|---------|-----------------|
+  | explore | Find patterns, understand code, search | Read-only, returns findings |
+  | coder | Write/edit files, implement features | Creates/modifies files, runs builds |
+  | oracle | Architecture decisions, complex debugging | Advisory, high-quality reasoning |
+
+  ## Coder Delegation Format (MANDATORY)
+
+  When spawning the `coder` agent, your prompt MUST include these sections.
+  The coder has NOT seen the codebase. Your prompt IS its entire context.
+
+  ### Template:
+
+  ```
+  ## Goal
+  [1-2 sentences: what to build/modify and where]
+
+  ## Reference Files
+  [Files that explore found, with what each demonstrates]
+  - `path/to/file.ext` - what pattern this file shows
+  - `path/to/other.ext` - what convention this file shows
+
+  ## Code Patterns to Follow
+  [Paste ACTUAL code snippets from explore results, not descriptions]
+  <code>
+  // From path/to/file.ext - this is the pattern to follow:
+  [actual code explore found, 5-20 lines]
+  </code>
+
+  ## Conventions
+  [Naming, imports, error handling, file organization]
+  - Convention 1
+  - Convention 2
+
+  ## Constraints
+  [What NOT to do, scope boundaries]
+  - Do NOT modify X
+  - Only touch files in Y/
+  ```
+
+  **CRITICAL**: Include actual code snippets, not just file paths.
+  If explore returned code patterns, paste them into the coder prompt.
+  Vague prompts like "follow existing patterns" waste coder's tokens on
+  re-exploration that you already did.
+
+  ## Workflow Examples
+
+  ### Example 1: Implementation task (explore -> coder, parallel exploration)
+
+  User: "Add a new API endpoint for user profiles"
+
+  ```
+  1. todo__init --goal "Add user profiles API endpoint"
+  2. todo__add --task "Explore existing API patterns"
+  3. todo__add --task "Implement profile endpoint"
+  4. agent__spawn --agent explore --prompt "Find existing API endpoint patterns, route structures, and controller conventions. Include code snippets."
+  5. agent__spawn --agent explore --prompt "Find existing data models and database query patterns. Include code snippets."
+  6. agent__collect --id <id1>
+  7. agent__collect --id <id2>
+  8. todo__done --id 1
+  9. agent__spawn --agent coder --prompt "<structured prompt using Coder Delegation Format above, including code snippets from explore results>"
+  10. agent__collect --id <coder_id>
+  11. todo__done --id 2
+  ```
+
+  Note: the `coder` agent is a graph agent that runs verification (build +
+  tests) and a bounded fix-loop internally. You do NOT need to spawn a
+  separate build/test step. A `CODER_COMPLETE` outcome means build and
+  tests already passed.
+
+  ### Example 2: Architecture/design question (explore + oracle in parallel)
+
+  User: "How should I structure the authentication for this app?"
+
+  ```
+  1. todo__init --goal "Get architecture advice for authentication"
+  2. todo__add --task "Explore current auth-related code"
+  3. todo__add --task "Consult oracle for architecture recommendation"
+  4. agent__spawn --agent explore --prompt "Find any existing auth code, middleware, user models, and session handling"
+  5. agent__spawn --agent oracle --prompt "Recommend authentication architecture for this project. Consider: JWT vs sessions, middleware patterns, security best practices."
+  6. agent__collect --id <explore_id>
+  7. todo__done --id 1
+  8. agent__collect --id <oracle_id>
+  9. todo__done --id 2
+  ```
+
+  ### Example 3: Vague/open-ended question (oracle directly)
+
+  User: "What do you think of this codebase structure?"
+
+  ```
+  agent__spawn --agent oracle --prompt "Review the project structure and provide recommendations for improvement"
+  agent__collect --id <oracle_id>
+  ```
+
+  ## Rules
+
+  1. **Always classify before acting** - Don't jump into implementation
+  2. **Create todos for multi-step tasks** - Track your progress
+  3. **Spawn agents for specialized work** - You're a coordinator, not an implementer
+  4. **Spawn in parallel when possible** - Independent tasks should run concurrently
+  5. **Verify after collecting agent results** - Don't trust blindly
+  6. **Mark todos done immediately** - Don't batch completions
+  7. **Ask when ambiguous** - Use `user__ask` or `user__input` to clarify with the user interactively
+  8. **Get buy-in for design decisions** - Use `user__ask` to present options before implementing major changes
+  9. **Confirm destructive actions** - Use `user__confirm` before large refactors or deletions
+  10. **Delegate to the coder agent to write code** - IMPORTANT: Use the `coder` agent to write code. Do not try to write code yourself except for trivial changes
+  11. **Always output a summary of changes when finished** - Make it clear to user's that you've completed your tasks
+
+  ## Coder Outcomes
+
+  The `coder` agent is a graph agent that runs the implement -> verify_build
+  -> verify_tests -> fix_loop pipeline internally. It always returns one of
+  three sentinel outcomes:
+
+  - `CODER_COMPLETE` - implementation succeeded with build + tests green.
+    Continue with any follow-up todos.
+  - `CODER_REJECTED` - user rejected the plan at the approval gate (only
+    triggered for high-complexity plans). Do NOT re-spawn coder blindly;
+    ask the user what to change first.
+  - `CODER_FAILED` - the fix-loop exhausted its budget without producing
+    green build/tests. The failure output includes the last build and tests
+    output. Surface this to the user; consider spawning `oracle` for
+    diagnosis if the failure is unclear.
+
+  ## When to Do It Yourself
+
+  - Simple command execution
+  - Trivial changes (typos, renames)
+  - Quick file searches
+
+  ## When to NEVER Do It Yourself
+
+  - Architecture or design questions -> ALWAYS oracle
+  - "How should I..." / "What's the best way to..." -> ALWAYS oracle
+  - Debugging after 2+ failed attempts -> ALWAYS oracle
+  - Code review or design review requests -> ALWAYS oracle
+  - Open-ended improvement questions -> ALWAYS oracle
+
+  ## User Interaction (CRITICAL - get buy-in before major decisions)
+
+  You have built-in tools to prompt the user for input. Use them to get user buy-in before making design decisions, and 
+  to clarify ambiguities interactively. **Do NOT guess when you can ask.**
+
+  ### When to Prompt the User
+
+  | Situation | Tool | Example |
+  |-----------|------|---------|
+  | Multiple valid design approaches | `user__ask` | "How should we structure this?" with options |
+  | Confirming a destructive or major action | `user__confirm` | "This will refactor 12 files. Proceed?" |
+  | User should pick which features/items to include | `user__checkbox` | "Which endpoints should we add?" |
+  | Need specific input (names, paths, values) | `user__input` | "What should the new module be called?" |
+  | Ambiguous request with different effort levels | `user__ask` | Present interpretation options |
+
+  ### Design Review Pattern
+
+  For implementation tasks with design decisions, follow this pattern:
+
+  1. **Explore** the codebase to understand existing patterns
+  2. **Formulate** 2-3 design options based on findings
+  3. **Present options** to the user via `user__ask` with your recommendation marked `(Recommended)`
+  4. **Confirm** the chosen approach before delegating to `coder`
+  5. Proceed with implementation
+
+  ### Rules for User Prompts
+
+  1. **Always include (Recommended)** on the option you think is best in `user__ask`
+  2. **Respect user choices** - never override or ignore a selection
+  3. **Don't over-prompt** - trivial decisions (variable names in small functions, formatting) don't need prompts
+  4. **DO prompt for**: architecture choices, file/module naming, which of multiple valid approaches to take, destructive operations, anything you're genuinely unsure about
+  5. **Confirm before large changes** - if a task will touch 5+ files, confirm the plan first
+
+  ## Escalation Handling
+
+  If you see `pending_escalations` in your tool results, a child agent needs user input and is blocked.
+  Reply promptly via `agent__reply_escalation` to unblock it. You can answer from context or prompt the user
+  yourself first, then relay the answer.
+
+  ## Available Tools
+  {{__tools__}}
+
+  ## Context
+  - Project: {{project_dir}}
+  - OS: {{__os__}}
+  - Shell: {{__shell__}}
+  - CWD: {{__cwd__}}
+
+conversation_starters:
+  - 'Add a new feature to the project'
+  - 'Fix a bug in the codebase'
+  - 'Refactor the authentication module'
+  - 'Help me understand how X works'

assets/agents/sisyphus/tools.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+set -eo pipefail
+# shellcheck disable=SC1090
+source "$LLM_PROMPT_UTILS_FILE"
+source "$LLM_ROOT_DIR/agents/.shared/utils.sh"
+export AUTO_CONFIRM=true
+
+# @env LLM_OUTPUT=/dev/stdout
+# @env LLM_AGENT_VAR_PROJECT_DIR=.
+# @describe Sisyphus orchestrator tools (project info, build, test)
+
+_project_dir() {
+  local dir="${LLM_AGENT_VAR_PROJECT_DIR:-.}"
+  (cd "${dir}" 2>/dev/null && pwd) || echo "${dir}"
+}
+
+# @cmd Get project information and structure
+get_project_info() {
+  local project_dir
+  project_dir=$(_project_dir)
+
+  info "Project: ${project_dir}" >> "$LLM_OUTPUT"
+  echo "" >> "$LLM_OUTPUT"
+
+  local project_info
+  project_info=$(detect_project "${project_dir}")
+
+  cat <<-EOF >> "$LLM_OUTPUT"
+		Type: $(echo "${project_info}" | jq -r '.type')
+		Build: $(echo "${project_info}" | jq -r '.build')
+		Test: $(echo "${project_info}" | jq -r '.test')
+
+		$(info "Directory structure:")
+		$(get_tree "${project_dir}" 2)
+	EOF
+}
+
+# @cmd Run build command for the project
+run_build() {
+  local project_dir
+  project_dir=$(_project_dir)
+
+  local project_info
+  project_info=$(detect_project "${project_dir}")
+  local build_cmd
+  build_cmd=$(echo "${project_info}" | jq -r '.build')
+
+  if [[ -z "${build_cmd}" ]] || [[ "${build_cmd}" == "null" ]]; then
+    warn "No build command detected for this project" >> "$LLM_OUTPUT"
+    return 0
+  fi
+
+  info "Running: ${build_cmd}" >> "$LLM_OUTPUT"
+  echo "" >> "$LLM_OUTPUT"
+
+  local output
+  if output=$(cd "${project_dir}" && eval "${build_cmd}" 2>&1); then
+    green "BUILD SUCCESS" >> "$LLM_OUTPUT"
+    echo "${output}" >> "$LLM_OUTPUT"
+    return 0
+  else
+    error "BUILD FAILED" >> "$LLM_OUTPUT"
+    echo "${output}" >> "$LLM_OUTPUT"
+    return 1
+  fi
+}
+
+# @cmd Run tests for the project
+run_tests() {
+  local project_dir
+  project_dir=$(_project_dir)
+
+  local project_info
+  project_info=$(detect_project "${project_dir}")
+  local test_cmd
+  test_cmd=$(echo "${project_info}" | jq -r '.test')
+
+  if [[ -z "${test_cmd}" ]] || [[ "${test_cmd}" == "null" ]]; then
+    warn "No test command detected for this project" >> "$LLM_OUTPUT"
+    return 0
+  fi
+
+  info "Running: ${test_cmd}" >> "$LLM_OUTPUT"
+  echo "" >> "$LLM_OUTPUT"
+
+  local output
+  if output=$(cd "${project_dir}" && eval "${test_cmd}" 2>&1); then
+    green "TESTS PASSED" >> "$LLM_OUTPUT"
+    echo "${output}" >> "$LLM_OUTPUT"
+    return 0
+  else
+    error "TESTS FAILED" >> "$LLM_OUTPUT"
+    echo "${output}" >> "$LLM_OUTPUT"
+    return 1
+  fi
+}
+

assets/functions/mcp.json

@@ -1,6 +1,7 @@
 {
   "mcpServers": {
     "github": {
+      "type": "stdio",
       "command": "docker",
       "args": [
         "run",
@@ -11,21 +12,23 @@
         "ghcr.io/github/github-mcp-server"
       ],
       "env": {
-        "GITHUB_PERSONAL_ACCESS_TOKEN": "{{GITHUB_PERSONAL_ACCESS_TOKEN}}"
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_TOKEN"
       }
     },
+    "atlassian": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "mcp-remote@0.1.13", "https://mcp.atlassian.com/v1/mcp"]
+    },
     "docker": {
+      "type": "stdio",
       "command": "uvx",
       "args": ["mcp-server-docker"]
     },
-    "slack": {
-      "command": "npx",
-      "args": ["-y", "slack-mcp-server@latest", "--transport", "stdio"],
-      "env": {
-        "SLACK_MCP_XOXC_TOKEN": "{{SLACK_MCP_XOXC_TOKEN}}",
-        "SLACK_MCP_XOXD_TOKEN": "{{SLACK_MCP_XOXD_TOKEN}}",
-        "SLACK_MCP_ADD_MESSAGE_TOOL": true
-      }
+    "ddg-search": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["duckduckgo-mcp-server"]
     }
   }
 }

assets/functions/scripts/run-agent.py

@@ -50,7 +50,13 @@ def parse_raw_data(data):
 
 def parse_argv():
     agent_func = sys.argv[1]
-    agent_data = sys.argv[2]
+
+    tool_data_file = os.environ.get("LLM_TOOL_DATA_FILE")
+    if tool_data_file and os.path.isfile(tool_data_file):
+        with open(tool_data_file, "r", encoding="utf-8") as f:
+            agent_data = f.read()
+    else:
+        agent_data = sys.argv[2]
 
     if (not agent_data) or (not agent_func):
         print("Usage: ./{agent_name}.py <agent-func> <agent-data>", file=sys.stderr)

assets/functions/scripts/run-agent.sh

@@ -14,7 +14,11 @@ main() {
 
 parse_argv() {
 		agent_func="$1"
-		agent_data="$2"
+    if [[ -n "$LLM_TOOL_DATA_FILE" ]] && [[ -f "$LLM_TOOL_DATA_FILE" ]]; then
+      	agent_data="$(cat "$LLM_TOOL_DATA_FILE")"
+    else
+				agent_data="$2"
+    fi
     if [[ -z "$agent_data" ]] || [[ -z "$agent_func" ]]; then
         die "usage: ./{agent_name}.sh <agent-func> <agent-data>"
     fi
@@ -57,7 +61,6 @@ run() {
     if [[ "$OS" == "Windows_NT" ]]; then
         set -o igncr
         tools_path="$(cygpath -w "$tools_path")"
-        tool_data="$(echo "$tool_data" | sed 's/\\/\\\\/g')"
     fi
 
     jq_script="$(cat <<-'EOF'
@@ -70,11 +73,11 @@ def to_args:
     to_entries | .[] |
     (.key | split("_") | join("-")) as $key |
     if .value | type == "array" then
-        .value | .[] | "--\($key) \(. | escape_shell_word)"
+        .value | .[] | "--\($key)=\(. | escape_shell_word)"
     elif .value | type == "boolean" then
         if .value then "--\($key)" else "" end
     else
-        "--\($key) \(.value | escape_shell_word)"
+        "--\($key)=\(.value | escape_shell_word)"
     end;
 [ to_args ] | join(" ")
 EOF

assets/functions/scripts/run-agent.ts

@@ -0,0 +1,189 @@
+#!/usr/bin/env tsx
+
+// Usage: ./{agent_name}.ts <agent-func> <agent-data>
+
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { join } from "path";
+import { pathToFileURL } from "url";
+
+async function main(): Promise<void> {
+  const { agentFunc, rawData } = parseArgv();
+  const agentData = parseRawData(rawData);
+
+  const configDir = "{config_dir}";
+  setupEnv(configDir, agentFunc);
+
+  const agentToolsPath = join(configDir, "agents", "{agent_name}", "tools.ts");
+  await run(agentToolsPath, agentFunc, agentData);
+}
+
+function parseRawData(data: string): Record<string, unknown> {
+  if (!data) {
+    throw new Error("No JSON data");
+  }
+
+  try {
+    return JSON.parse(data);
+  } catch {
+    throw new Error("Invalid JSON data");
+  }
+}
+
+function parseArgv(): { agentFunc: string; rawData: string } {
+  const agentFunc = process.argv[2];
+
+  const toolDataFile = process.env["LLM_TOOL_DATA_FILE"];
+  let agentData: string;
+  if (toolDataFile && existsSync(toolDataFile)) {
+    agentData = readFileSync(toolDataFile, "utf-8");
+  } else {
+    agentData = process.argv[3];
+  }
+
+  if (!agentFunc || !agentData) {
+    process.stderr.write("Usage: ./{agent_name}.ts <agent-func> <agent-data>\n");
+    process.exit(1);
+  }
+
+  return { agentFunc, rawData: agentData };
+}
+
+function setupEnv(configDir: string, agentFunc: string): void {
+  loadEnv(join(configDir, ".env"));
+  process.env["LLM_ROOT_DIR"] = configDir;
+  process.env["LLM_AGENT_NAME"] = "{agent_name}";
+  process.env["LLM_AGENT_FUNC"] = agentFunc;
+  process.env["LLM_AGENT_ROOT_DIR"] = join(configDir, "agents", "{agent_name}");
+  process.env["LLM_AGENT_CACHE_DIR"] = join(configDir, "cache", "{agent_name}");
+}
+
+function loadEnv(filePath: string): void {
+  let lines: string[];
+  try {
+    lines = readFileSync(filePath, "utf-8").split("\n");
+  } catch {
+    return;
+  }
+
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (line.startsWith("#") || !line) {
+      continue;
+    }
+
+    const eqIdx = line.indexOf("=");
+    if (eqIdx === -1) {
+      continue;
+    }
+
+    const key = line.slice(0, eqIdx).trim();
+    if (key in process.env) {
+      continue;
+    }
+
+    let value = line.slice(eqIdx + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    process.env[key] = value;
+  }
+}
+
+function extractParamNames(fn: Function): string[] {
+  const src = fn.toString();
+  const match = src.match(/^(?:async\s+)?function\s*\w*\s*\(([^)]*)\)/);
+  if (!match) {
+    return [];
+  }
+  return match[1]
+    .split(",")
+    .map((p) => p.trim().replace(/[:=?].*/s, "").trim())
+    .filter(Boolean);
+}
+
+function spreadArgs(
+  fn: Function,
+  data: Record<string, unknown>,
+): unknown[] {
+  const names = extractParamNames(fn);
+  if (names.length === 0) {
+    return [];
+  }
+  return names.map((name) => data[name]);
+}
+
+async function run(
+  agentPath: string,
+  agentFunc: string,
+  agentData: Record<string, unknown>,
+): Promise<void> {
+  const mod = await import(pathToFileURL(agentPath).href);
+
+  if (typeof mod[agentFunc] !== "function") {
+    throw new Error(`No module function '${agentFunc}' at '${agentPath}'`);
+  }
+
+  const fn = mod[agentFunc] as Function;
+  const args = spreadArgs(fn, agentData);
+  const value = await fn(...args);
+  returnToLlm(value);
+  dumpResult(`{agent_name}:${agentFunc}`);
+}
+
+function returnToLlm(value: unknown): void {
+  if (value === null || value === undefined) {
+    return;
+  }
+
+  const output = process.env["LLM_OUTPUT"];
+  const write = (s: string) => {
+    if (output) {
+      writeFileSync(output, s, "utf-8");
+    } else {
+      process.stdout.write(s);
+    }
+  };
+
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    write(String(value));
+  } else if (typeof value === "object") {
+    write(JSON.stringify(value, null, 2));
+  }
+}
+
+function dumpResult(name: string): void {
+  const dumpResults = process.env["LLM_DUMP_RESULTS"];
+  const llmOutput = process.env["LLM_OUTPUT"];
+
+  if (!dumpResults || !llmOutput || !process.stdout.isTTY) {
+    return;
+  }
+
+  try {
+    const pattern = new RegExp(`\\b(${dumpResults})\\b`);
+    if (!pattern.test(name)) {
+      return;
+    }
+  } catch {
+    return;
+  }
+
+  let data: string;
+  try {
+    data = readFileSync(llmOutput, "utf-8");
+  } catch {
+    return;
+  }
+
+  process.stdout.write(
+    `\x1b[2m----------------------\n${data}\n----------------------\x1b[0m\n`,
+  );
+}
+
+main().catch((err) => {
+  process.stderr.write(`${err}\n`);
+  process.exit(1);
+});

assets/functions/scripts/run-tool.py

@@ -49,6 +49,11 @@ def parse_raw_data(data):
 
 
 def parse_argv():
+    tool_data_file = os.environ.get("LLM_TOOL_DATA_FILE")
+    if tool_data_file and os.path.isfile(tool_data_file):
+        with open(tool_data_file, "r", encoding="utf-8") as f:
+            return f.read()
+
     argv = sys.argv[:] + [None] * max(0, 2 - len(sys.argv))
 
     tool_data = argv[1]

assets/functions/scripts/run-tool.sh

@@ -13,7 +13,11 @@ main() {
 }
 
 parse_argv() {
-		tool_data="$1"
+    if [[ -n "$LLM_TOOL_DATA_FILE" ]] && [[ -f "$LLM_TOOL_DATA_FILE" ]]; then
+        tool_data="$(cat "$LLM_TOOL_DATA_FILE")"
+    else
+				tool_data="$1"
+    fi
     if [[ -z "$tool_data" ]]; then
         die "usage: ./{function_name}.sh <tool-data>"
     fi
@@ -54,7 +58,6 @@ run() {
     if [[ "$OS" == "Windows_NT" ]]; then
         set -o igncr
         tool_path="$(cygpath -w "$tool_path")"
-        tool_data="$(echo "$tool_data" | sed 's/\\/\\\\/g')"
     fi
 
     jq_script="$(cat <<-'EOF'
@@ -67,11 +70,11 @@ def to_args:
     to_entries | .[] |
     (.key | split("_") | join("-")) as $key |
     if .value | type == "array" then
-        .value | .[] | "--\($key) \(. | escape_shell_word)"
+        .value | .[] | "--\($key)=\(. | escape_shell_word)"
     elif .value | type == "boolean" then
         if .value then "--\($key)" else "" end
     else
-        "--\($key) \(.value | escape_shell_word)"
+        "--\($key)=\(.value | escape_shell_word)"
     end;
 [ to_args ] | join(" ")
 EOF

assets/functions/scripts/run-tool.ts

@@ -0,0 +1,184 @@
+#!/usr/bin/env tsx
+
+// Usage: ./{function_name}.ts <tool-data>
+
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { join } from "path";
+import { pathToFileURL } from "url";
+
+async function main(): Promise<void> {
+  const rawData = parseArgv();
+  const toolData = parseRawData(rawData);
+
+  const rootDir = "{root_dir}";
+  setupEnv(rootDir);
+
+  const toolPath = "{tool_path}.ts";
+  await run(toolPath, "run", toolData);
+}
+
+function parseRawData(data: string): Record<string, unknown> {
+  if (!data) {
+    throw new Error("No JSON data");
+  }
+
+  try {
+    return JSON.parse(data);
+  } catch {
+    throw new Error("Invalid JSON data");
+  }
+}
+
+function parseArgv(): string {
+  const toolDataFile = process.env["LLM_TOOL_DATA_FILE"];
+  if (toolDataFile && existsSync(toolDataFile)) {
+    return readFileSync(toolDataFile, "utf-8");
+  }
+
+  const toolData = process.argv[2];
+
+  if (!toolData) {
+    process.stderr.write("Usage: ./{function_name}.ts <tool-data>\n");
+    process.exit(1);
+  }
+
+  return toolData;
+}
+
+function setupEnv(rootDir: string): void {
+  loadEnv(join(rootDir, ".env"));
+  process.env["LLM_ROOT_DIR"] = rootDir;
+  process.env["LLM_TOOL_NAME"] = "{function_name}";
+  process.env["LLM_TOOL_CACHE_DIR"] = join(rootDir, "cache", "{function_name}");
+}
+
+function loadEnv(filePath: string): void {
+  let lines: string[];
+  try {
+    lines = readFileSync(filePath, "utf-8").split("\n");
+  } catch {
+    return;
+  }
+
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (line.startsWith("#") || !line) {
+      continue;
+    }
+
+    const eqIdx = line.indexOf("=");
+    if (eqIdx === -1) {
+      continue;
+    }
+
+    const key = line.slice(0, eqIdx).trim();
+    if (key in process.env) {
+      continue;
+    }
+
+    let value = line.slice(eqIdx + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    process.env[key] = value;
+  }
+}
+
+function extractParamNames(fn: Function): string[] {
+  const src = fn.toString();
+  const match = src.match(/^(?:async\s+)?function\s*\w*\s*\(([^)]*)\)/);
+  if (!match) {
+    return [];
+  }
+  return match[1]
+    .split(",")
+    .map((p) => p.trim().replace(/[:=?].*/s, "").trim())
+    .filter(Boolean);
+}
+
+function spreadArgs(
+  fn: Function,
+  data: Record<string, unknown>,
+): unknown[] {
+  const names = extractParamNames(fn);
+  if (names.length === 0) {
+    return [];
+  }
+  return names.map((name) => data[name]);
+}
+
+async function run(
+  toolPath: string,
+  toolFunc: string,
+  toolData: Record<string, unknown>,
+): Promise<void> {
+  const mod = await import(pathToFileURL(toolPath).href);
+
+  if (typeof mod[toolFunc] !== "function") {
+    throw new Error(`No module function '${toolFunc}' at '${toolPath}'`);
+  }
+
+  const fn = mod[toolFunc] as Function;
+  const args = spreadArgs(fn, toolData);
+  const value = await fn(...args);
+  returnToLlm(value);
+  dumpResult("{function_name}");
+}
+
+function returnToLlm(value: unknown): void {
+  if (value === null || value === undefined) {
+    return;
+  }
+
+  const output = process.env["LLM_OUTPUT"];
+  const write = (s: string) => {
+    if (output) {
+      writeFileSync(output, s, "utf-8");
+    } else {
+      process.stdout.write(s);
+    }
+  };
+
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    write(String(value));
+  } else if (typeof value === "object") {
+    write(JSON.stringify(value, null, 2));
+  }
+}
+
+function dumpResult(name: string): void {
+  const dumpResults = process.env["LLM_DUMP_RESULTS"];
+  const llmOutput = process.env["LLM_OUTPUT"];
+
+  if (!dumpResults || !llmOutput || !process.stdout.isTTY) {
+    return;
+  }
+
+  try {
+    const pattern = new RegExp(`\\b(${dumpResults})\\b`);
+    if (!pattern.test(name)) {
+      return;
+    }
+  } catch {
+    return;
+  }
+
+  let data: string;
+  try {
+    data = readFileSync(llmOutput, "utf-8");
+  } catch {
+    return;
+  }
+
+  process.stdout.write(
+    `\x1b[2m----------------------\n${data}\n----------------------\x1b[0m\n`,
+  );
+}
+
+main().catch((err) => {
+  process.stderr.write(`${err}\n`);
+  process.exit(1);
+});

assets/functions/tools/demo_py.py

@@ -1,6 +1,7 @@
 import os
 from typing import List, Literal, Optional
 
+
 def run(
     string: str,
     string_enum: Literal["foo", "bar"],
@@ -9,26 +10,38 @@ def run(
     number: float,
     array: List[str],
     string_optional: Optional[str] = None,
+    integer_with_default: int = 42,
+    boolean_with_default: bool = True,
+    number_with_default: float = 3.14,
+    string_with_default: str = "hello",
     array_optional: Optional[List[str]] = None,
 ):
-    """Demonstrates how to create a tool using Python and how to use comments.
+    """Demonstrates all supported Python parameter types and variations.
     Args:
-        string: Define a required string property
-        string_enum: Define a required string property with enum
-        boolean: Define a required boolean property
-        integer: Define a required integer property
-        number: Define a required number property
-        array: Define a required string array property
-        string_optional: Define an optional string property
-        array_optional: Define an optional string array property
+        string: A required string property
+        string_enum: A required string property constrained to specific values
+        boolean: A required boolean property
+        integer: A required integer property
+        number: A required number (float) property
+        array: A required string array property
+        string_optional: An optional string property (Optional[str] with None default)
+        integer_with_default: An optional integer with a non-None default value
+        boolean_with_default: An optional boolean with a default value
+        number_with_default: An optional number with a default value
+        string_with_default: An optional string with a default value
+        array_optional: An optional string array property
     """
     output = f"""string: {string}
 string_enum: {string_enum}
-string_optional: {string_optional}
 boolean: {boolean}
 integer: {integer}
 number: {number}
 array: {array}
+string_optional: {string_optional}
+integer_with_default: {integer_with_default}
+boolean_with_default: {boolean_with_default}
+number_with_default: {number_with_default}
+string_with_default: {string_with_default}
 array_optional: {array_optional}"""
 
     for key, value in os.environ.items():

assets/functions/tools/demo_ts.ts

@@ -0,0 +1,53 @@
+/**
+ * Demonstrates all supported TypeScript parameter types and variations.
+ *
+ * @param string - A required string property
+ * @param string_enum - A required string property constrained to specific values
+ * @param boolean - A required boolean property
+ * @param number - A required number property
+ * @param array_bracket - A required string array using bracket syntax
+ * @param array_generic - A required string array using generic syntax
+ * @param string_optional - An optional string using the question mark syntax
+ * @param string_nullable - An optional string using the union-with-null syntax
+ * @param number_with_default - An optional number with a default value
+ * @param boolean_with_default - An optional boolean with a default value
+ * @param string_with_default - An optional string with a default value
+ * @param array_optional - An optional string array using the question mark syntax
+ */
+export function run(
+  string: string,
+  string_enum: "foo" | "bar",
+  boolean: boolean,
+  number: number,
+  array_bracket: string[],
+  array_generic: Array<string>,
+  string_optional?: string,
+  string_nullable: string | null = null,
+  number_with_default: number = 42,
+  boolean_with_default: boolean = true,
+  string_with_default: string = "hello",
+  array_optional?: string[],
+): string {
+  const parts = [
+    `string: ${string}`,
+    `string_enum: ${string_enum}`,
+    `boolean: ${boolean}`,
+    `number: ${number}`,
+    `array_bracket: ${JSON.stringify(array_bracket)}`,
+    `array_generic: ${JSON.stringify(array_generic)}`,
+    `string_optional: ${string_optional}`,
+    `string_nullable: ${string_nullable}`,
+    `number_with_default: ${number_with_default}`,
+    `boolean_with_default: ${boolean_with_default}`,
+    `string_with_default: ${string_with_default}`,
+    `array_optional: ${JSON.stringify(array_optional)}`,
+  ];
+
+  for (const [key, value] of Object.entries(process.env)) {
+    if (key.startsWith("LLM_")) {
+      parts.push(`${key}: ${value}`);
+    }
+  }
+
+  return parts.join("\n");
+}

assets/functions/tools/fs_cat.sh

@@ -10,5 +10,5 @@ set -e
 
 main() {
     # shellcheck disable=SC2154
-    cat "$argc_path" >> "$LLM_OUTPUT"
+		cat "$argc_path" >> "$LLM_OUTPUT" 2>&1 || echo "No such file or path: $argc_path" >> "$LLM_OUTPUT"
 }

assets/functions/tools/fs_glob.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+set -e
+
+# @describe Find files by glob pattern. Returns matching file paths sorted by modification time.
+# Use this to discover files before reading them.
+
+# @option --pattern! The glob pattern to match files against (e.g. "**/*.rs", "src/**/*.ts", "*.yaml")
+# @option --path The directory to search in (defaults to current working directory)
+
+# @env LLM_OUTPUT=/dev/stdout The output path
+
+MAX_RESULTS=100
+
+main() {
+    # shellcheck disable=SC2154
+    local glob_pattern="$argc_pattern"
+    local search_path="${argc_path:-.}"
+
+    if [[ ! -d "$search_path" ]]; then
+        echo "Error: directory not found: $search_path" >> "$LLM_OUTPUT"
+        return 1
+    fi
+
+    local results
+    if command -v fd &>/dev/null; then
+        results=$(fd --type f --glob "$glob_pattern" "$search_path" \
+            --exclude '.git' \
+            --exclude 'node_modules' \
+            --exclude 'target' \
+            --exclude 'dist' \
+            --exclude '__pycache__' \
+            --exclude 'vendor' \
+            --exclude '.build' \
+            2>/dev/null | head -n "$MAX_RESULTS") || true
+    else
+        results=$(find "$search_path" -type f -name "$glob_pattern" \
+            -not -path '*/.git/*' \
+            -not -path '*/node_modules/*' \
+            -not -path '*/target/*' \
+            -not -path '*/dist/*' \
+            -not -path '*/__pycache__/*' \
+            -not -path '*/vendor/*' \
+            -not -path '*/.build/*' \
+            2>/dev/null | head -n "$MAX_RESULTS") || true
+    fi
+
+    if [[ -z "$results" ]]; then
+        echo "No files found matching: $glob_pattern" >> "$LLM_OUTPUT"
+        return 0
+    fi
+
+    echo "$results" >> "$LLM_OUTPUT"
+
+    local count
+    count=$(echo "$results" | wc -l)
+    if [[ "$count" -ge "$MAX_RESULTS" ]]; then
+        printf "\n(Results limited to %s files. Use a more specific pattern.)\n" "$MAX_RESULTS" >> "$LLM_OUTPUT"
+    fi
+}

assets/functions/tools/fs_grep.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+set -e
+
+# @describe Search file contents using regular expressions. Returns matching file paths and lines.
+# Use this to find relevant code before reading files. Much faster than reading files to search.
+
+# @option --pattern! The regex pattern to search for in file contents
+# @option --path The directory to search in (defaults to current working directory)
+# @option --include File pattern to filter by (e.g. "*.rs", "*.{ts,tsx}", "*.py")
+
+# @env LLM_OUTPUT=/dev/stdout The output path
+
+MAX_RESULTS=50
+MAX_LINE_LENGTH=2000
+
+main() {
+    # shellcheck disable=SC2154
+    local search_pattern="$argc_pattern"
+    local search_path="${argc_path:-.}"
+    local include_filter="${argc_include:-}"
+
+    if [[ ! -d "$search_path" ]]; then
+        echo "Error: directory not found: $search_path" >> "$LLM_OUTPUT"
+        return 1
+    fi
+
+    local grep_args=(-rn --color=never)
+
+    grep_args+=(
+        --exclude-dir='.git'
+        --exclude-dir='node_modules'
+        --exclude-dir='target'
+        --exclude-dir='dist'
+        --exclude-dir='build'
+        --exclude-dir='__pycache__'
+        --exclude-dir='vendor'
+        --exclude-dir='.build'
+        --exclude-dir='.next'
+        --exclude='*.min.js'
+        --exclude='*.min.css'
+        --exclude='*.map'
+        --exclude='*.lock'
+        --exclude='package-lock.json'
+    )
+
+    if [[ -n "$include_filter" ]]; then
+        grep_args+=("--include=$include_filter")
+    fi
+
+    local results
+    results=$(grep "${grep_args[@]}" -E "$search_pattern" "$search_path" 2>/dev/null | head -n "$MAX_RESULTS") || true
+
+    if [[ -z "$results" ]]; then
+        echo "No matches found for: $search_pattern" >> "$LLM_OUTPUT"
+        return 0
+    fi
+
+    echo "$results" | while IFS= read -r line; do
+        if [[ ${#line} -gt $MAX_LINE_LENGTH ]]; then
+            line="${line:0:$MAX_LINE_LENGTH}... (truncated)"
+        fi
+
+        echo "$line"
+    done >> "$LLM_OUTPUT"
+
+    local count
+    count=$(echo "$results" | wc -l)
+    if [[ "$count" -ge "$MAX_RESULTS" ]]; then
+        printf "\n(Results limited to %s matches. Narrow your search with --include or a more specific pattern.)\n" "$MAX_RESULTS" >> "$LLM_OUTPUT"
+    fi
+}

assets/functions/tools/fs_ls.sh

@@ -9,5 +9,5 @@ set -e
 
 main() {
     # shellcheck disable=SC2154
-    ls -1 "$argc_path" >> "$LLM_OUTPUT"
+    ls -1 "$argc_path" >> "$LLM_OUTPUT" 2>&1 || echo "No such path: $argc_path" >> "$LLM_OUTPUT"
 }

assets/functions/tools/fs_read.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+set -e
+
+# @describe Read a file with line numbers, offset, and limit. For directories, lists entries.
+# Prefer this over fs_cat for controlled reading. Use offset/limit to read specific sections.
+# Use the grep tool to find specific content before reading, then read with offset to target the relevant section.
+
+# @option --path! The absolute path to the file or directory to read
+# @option --offset The line number to start reading from (1-indexed, default: 1)
+# @option --limit The maximum number of lines to read (default: 2000)
+
+# @env LLM_OUTPUT=/dev/stdout The output path
+
+MAX_LINE_LENGTH=2000
+MAX_BYTES=51200
+
+main() {
+    # shellcheck disable=SC2154
+    local target="$argc_path"
+    local offset="${argc_offset:-1}"
+    local limit="${argc_limit:-2000}"
+
+    if [[ ! -e "$target" ]]; then
+        echo "Error: path not found: $target" >> "$LLM_OUTPUT"
+        return 1
+    fi
+
+    if [[ -d "$target" ]]; then
+        ls -1 "$target" >> "$LLM_OUTPUT" 2>&1
+        return 0
+    fi
+
+    local total_lines file_bytes
+    total_lines=$(wc -l < "$target" 2>/dev/null || echo 0)
+    file_bytes=$(wc -c < "$target" 2>/dev/null || echo 0)
+
+    if [[ "$file_bytes" -gt "$MAX_BYTES" ]] && [[ "$offset" -eq 1 ]] && [[ "$limit" -ge 2000 ]]; then
+        {
+            echo "Warning: Large file (${file_bytes} bytes, ${total_lines} lines). Showing first ${limit} lines."
+            echo "Use --offset and --limit to read specific sections, or use the grep tool to find relevant lines first."
+            echo ""
+        } >> "$LLM_OUTPUT"
+    fi
+
+    local end_line=$((offset + limit - 1))
+
+    sed -n "${offset},${end_line}p" "$target" 2>/dev/null | {
+        local line_num=$offset
+        while IFS= read -r line; do
+            if [[ ${#line} -gt $MAX_LINE_LENGTH ]]; then
+                line="${line:0:$MAX_LINE_LENGTH}... (truncated)"
+            fi
+            printf "%d: %s\n" "$line_num" "$line"
+            line_num=$((line_num + 1))
+        done
+    } >> "$LLM_OUTPUT"
+
+    if [[ "$end_line" -lt "$total_lines" ]]; then
+        echo "" >> "$LLM_OUTPUT"
+        echo "(${total_lines} total lines. Use --offset $((end_line + 1)) to read more.)" >> "$LLM_OUTPUT"
+    fi
+}

assets/functions/tools/get_current_weather.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env tsx
+
+import { appendFileSync, mkdirSync } from "fs";
+import { dirname } from "path";
+
+/**
+ * Get the current weather in a given location
+ * @param location - The city and optionally the state or country (e.g., "London", "San Francisco, CA").
+ */
+export async function run(location: string): string {
+  const encoded = encodeURIComponent(location);
+  const url = `https://wttr.in/${encoded}?format=4`;
+
+  const resp = await fetch(url);
+  const data = await resp.text();
+
+  const dest = process.env["LLM_OUTPUT"] ?? "/dev/stdout";
+  if (dest !== "-" && dest !== "/dev/stdout") {
+    mkdirSync(dirname(dest), { recursive: true });
+    appendFileSync(dest, data, "utf-8");
+  }
+
+  return data;
+}

assets/functions/tools/query_jira_issues.sh

@@ -1,11 +0,0 @@
-#!/usr/bin/env bash
-set -e
-
-# @meta require-tools jira
-# @describe Query for jira issues using a Jira Query Language (JQL) query
-# @option --jql-query! The Jira Query Language query to execute
-# @env LLM_OUTPUT=/dev/stdout The output path
-
-main() {
-  jira issue ls -q "$argc_jql_query" --plain >> "$LLM_OUTPUT"
-}

assets/functions/utils/prompt-utils.sh

@@ -121,7 +121,7 @@ _cursor_blink_off() {
 }
 
 _cursor_to() {
-  echo -en "\033[$1;$2H" >&2
+  echo -en "\033[$1;${2:-1}H" >&2
 }
 
 # shellcheck disable=SC2154
@@ -133,7 +133,7 @@ _key_input() {
     _read_stdin -rsn2 b
   fi
 
-  declare input="${a}${b}"
+  declare input="${a}${b:-}"
   case "$input" in
     "${ESC}[A" | "k") echo up ;;
     "${ESC}[B" | "j") echo down ;;
@@ -507,12 +507,14 @@ open_link() {
 
 guard_operation() {
   if [[ -t 1 ]]; then
-    ans="$(confirm "${1:-Are you sure you want to continue?}")"
+  	if [[ -z "$AUTO_CONFIRM" && -z "$LLM_AGENT_VAR_AUTO_CONFIRM" ]]; then
+			ans="$(confirm "${1:-Are you sure you want to continue?}")"
 
-    if [[ "$ans" == 0 ]]; then
-      error "Operation aborted!" 2>&1
-      exit 1
-    fi
+			if [[ "$ans" == 0 ]]; then
+				error "Operation aborted!" 2>&1
+				exit 1
+			fi
+		fi
   fi
 }
 
@@ -657,13 +659,13 @@ guard_path() {
     path="$(_to_real_path "$1")"
     confirmation_prompt="$2"
 
-    if [[ ! "$path" == "$(pwd)"* ]]; then
-      ans="$(confirm "$confirmation_prompt")"
+    if [[ ! "$path" == "$(pwd)"* && -z "$AUTO_CONFIRM" && -z "$LLM_AGENT_VAR_AUTO_CONFIRM" ]]; then
+			ans="$(confirm "$confirmation_prompt")"
 
-      if [[ "$ans" == 0 ]]; then
-        error "Operation aborted!" >&2
-        exit 1
-      fi
+			if [[ "$ans" == 0 ]]; then
+				error "Operation aborted!" >&2
+				exit 1
+			fi
     fi
   fi
 }

assets/roles/atlassian.md

@@ -0,0 +1,8 @@
+---
+enabled_mcp_servers: atlassian
+---
+You are the librarian for the company's Confluence and Jira knowledge bases. Your job is to help users find and retrieve
+information from these platforms. Use all tools at your disposal to answer user queries.
+
+Available Tools:
+{{__tools__}}

config.agent.example.yaml

@@ -17,6 +17,25 @@ agent_session: null              # Set a session to use when starting the agent.
 name: <agent-name>               # Name of the agent, used in the UI and logs
 description: <description>       # Description of the agent, used in the UI
 version: 1                       # Version of the agent
+# 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
+# prompt it to continue when incomplete tasks remain.
+# See the [Todo System documentation](https://github.com/Dark-Alex-17/loki/wiki/TODO-System) for more information
+auto_continue: false             # Enable automatic continuation when incomplete todos remain
+max_auto_continues: 10           # Maximum number of automatic continuations before stopping
+inject_todo_instructions: true   # Inject the default todo tool usage instructions into the agent's system prompt
+continuation_prompt: null        # Custom prompt used when auto-continuing (optional; uses default if null)
+# Sub-Agent Spawning System
+# Enable this agent to spawn and manage child agents in parallel.
+# See https://github.com/Dark-Alex-17/loki/wiki/Agents for detailed documentation.
+can_spawn_agents: false          # Enable the agent to spawn child agents
+max_concurrent_agents: 4         # Maximum number of agents that can run simultaneously
+max_agent_depth: 3               # Maximum nesting depth for sub-agents (prevents runaway spawning)
+inject_spawn_instructions: true  # Inject the default agent spawning instructions into the agent's system prompt
+summarization_model: null        # Model to use for summarizing sub-agent output (e.g. 'openai:gpt-4o-mini'); defaults to current model
+summarization_threshold: 4000    # Character threshold above which sub-agent output is summarized before returning to parent
+escalation_timeout: 300          # Seconds a sub-agent waits for a user interaction response before timing out (default: 5 minutes)
 mcp_servers:                     # Optional list of MCP servers that the agent utilizes
   - github                       # Corresponds to the name of an MCP server in the `<loki-config-dir>/functions/mcp.json` file
 global_tools:                    # Optional list of additional global tools to enable for the agent; i.e. not tools specific to the agent

config.example.yaml

@@ -27,25 +27,26 @@ sync_models_url: >               # URL to sync model changes from
   https://raw.githubusercontent.com/Dark-Alex-17/loki/refs/heads/main/models.yaml
 
 # ---- REPL Prompt ----
-# Custom REPL left/right prompts; see the [REPL Prompt Documentation](./docs/REPL-PROMPT.md) for more information
+# Custom REPL left/right prompts; see the [REPL Prompt Documentation](https://github.com/Dark-Alex-17/loki/wiki/REPL-Prompt) for more information
 left_prompt:
   '{color.red}{model}){color.green}{?session {?agent {agent}>}{session}{?role /}}{!session {?agent {agent}>}}{role}{?rag @{rag}}{color.cyan}{?session )}{!session >}{color.reset} '
 right_prompt:
   '{color.purple}{?session {?consume_tokens {consume_tokens}({consume_percent}%)}{!consume_tokens {consume_tokens}}}{color.reset}'
 
 # ---- Vault ----
-# See the [Vault documentation](./docs/VAULT.md) for more information on the Loki vault
+# See the [Vault documentation](https://github.com/Dark-Alex-17/loki/wiki/Vault) for more information on the Loki vault
 vault_password_file: null        # Path to a file containing the password for the Loki vault (cannot be a secret template)
 
 # ---- Function Calling ----
-# See the [Tools documentation](./docs/function-calling/TOOLS.md) for more details
+# See the [Tools documentation](https://github.com/Dark-Alex-17/loki/wiki/Tools) for more details
 function_calling: true           # Enables or disables function calling (Globally).
 mapping_tools:                   # Alias for a tool or toolset
-  fs: 'fs_cat,fs_ls,fs_mkdir,fs_rm,fs_write'
+  fs: 'fs_cat,fs_ls,fs_mkdir,fs_rm,fs_write,fs_read,fs_glob,fs_grep'
 enabled_tools: null              # Which tools to enable by default. (e.g. 'fs,web_search_loki')
 visible_tools:                   # Which tools are visible to be compiled (and are thus able to be defined in 'enabled_tools')
 #  - demo_py.py
 #  - demo_sh.sh
+#  - demo_ts.ts
   - execute_command.sh
 #  - execute_py_code.py
 #  - execute_sql_code.sh
@@ -53,13 +54,16 @@ visible_tools:                   # Which tools are visible to be compiled (and a
 #  - fetch_url_via_jina.sh
   - fs_cat.sh
   - fs_ls.sh
+#  - fs_read.sh
+#  - fs_glob.sh
+#  - fs_grep.sh
 #  - fs_mkdir.sh
 #  - fs_patch.sh
 #  - fs_write.sh
   - get_current_time.sh
 #  - get_current_weather.py
+#  - get_current_weather.ts
   - get_current_weather.sh
-  - query_jira_issues.sh
 #  - search_arxiv.sh
 #  - search_wikipedia.sh
 #  - search_wolframalpha.sh
@@ -70,14 +74,24 @@ visible_tools:                   # Which tools are visible to be compiled (and a
 #  - web_search_tavily.sh
 
 # ---- MCP Servers ----
-# See the [MCP Servers documentation](./docs/MCP-SERVERS.md) for more details
+# See the [MCP Servers documentation](https://github.com/Dark-Alex-17/loki/wiki/MCP-Servers) for more details
 mcp_server_support: true         # Enables or disables MCP servers (globally).
 mapping_mcp_servers:             # Alias for an MCP server or set of servers
   git: github,gitmcp
-enabled_mcp_servers: null        # Which MCP servers to enable by default (e.g. 'github,slack')
+enabled_mcp_servers: null        # Which MCP servers to enable by default (e.g. 'github,slack,ddg-search')
+
+# ---- 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
+# prompt it to continue when incomplete tasks remain.
+# See the [Todo System documentation](https://github.com/Dark-Alex-17/loki/wiki/TODO-System) for more information
+auto_continue: false              # Enable automatic continuation when incomplete todos remain (default: false)
+max_auto_continues: 10            # Maximum number of automatic continuations before stopping (default: 10)
+inject_todo_instructions: true    # Inject default todo usage instructions into the system prompt (default: true)
+continuation_prompt: null         # Custom prompt used when auto-continuing. If null, uses built-in default
 
 # ---- Session ----
-# See the [Session documentation](./docs/SESSIONS.md) for more information
+# See the [Session documentation](https://github.com/Dark-Alex-17/loki/wiki/Sessions) for more information
 save_session: null               # Controls the persistence of the session. If true, auto save; if false, don't auto-save save; if null, ask the user what to do
 compression_threshold: 4000      # Compress the session when the token count reaches or exceeds this threshold
 summarization_prompt: >          # The text prompt used for creating a concise summary of session message
@@ -86,13 +100,13 @@ summary_context_prompt: >        # The text prompt used for including the summar
   'This is a summary of the chat history as a recap: '
 
 # ---- RAG ----
-# See the [RAG Docs](./docs/RAG.md) for more details.
+# See the [RAG Docs](https://github.com/Dark-Alex-17/loki/wiki/RAG) for more details.
 rag_embedding_model: null        # Specifies the embedding model used for context retrieval
 rag_reranker_model: null         # Specifies the reranker model used for sorting retrieved documents; Loki uses Reciprocal Rank Fusion by default
 rag_top_k: 5                     # Specifies the number of documents to retrieve for answering queries
 rag_chunk_size: null             # Defines the size of chunks for document processing in characters
 rag_chunk_overlap: null          # Defines the overlap between chunks
-# Defines the query structure using variables like __CONTEXT__ and __INPUT__ to tailor searches to specific needs
+# Defines the query structure using variables like __CONTEXT__, __SOURCES__, and __INPUT__ to tailor searches to specific needs
 rag_template: |
   Answer the query based on the context while respecting the rules. (user query, some textual context and rules, all inside xml tags)
 
@@ -100,6 +114,10 @@ rag_template: |
   __CONTEXT__
   </context>
 
+  <sources>
+  __SOURCES__
+  </sources>
+
   <rules>
   - If you don't know, just say so.
   - If you are not sure, ask for clarification.
@@ -107,6 +125,7 @@ rag_template: |
   - If the context appears unreadable or of poor quality, tell the user then answer as best as you can.
   - If the answer is not in the context but you think you know the answer, explain that to the user then answer with your own knowledge.
   - Answer directly and without using xml tags.
+  - When using information from the context, cite the relevant source from the <sources> section.
   </rules>
 
   <user_query>
@@ -127,7 +146,7 @@ document_loaders:
     sh -c "yek $1 --json | jq 'map({ path: .filename, contents: .content })'"
 
 # ---- Clients ----
-# See the [Clients documentation](./docs/clients/CLIENTS.md) for more details
+# See the [Clients documentation](https://github.com/Dark-Alex-17/loki/wiki/Clients) for more details
 clients:
   # All clients have the following configuration:
   # - type: xxxx
@@ -184,6 +203,8 @@ clients:
   - type: gemini
     api_base: https://generativelanguage.googleapis.com/v1beta
     api_key: '{{GEMINI_API_KEY}}'                       # You can either hard-code or inject secrets from the Loki vault
+    auth: null                                          # When set to 'oauth', Loki will use OAuth instead of an API key
+                                                        # Authenticate with `loki --authenticate` or `.authenticate` in the REPL
     patch:
       chat_completions:
         '.*':
@@ -202,6 +223,8 @@ clients:
   - type: claude
     api_base: https://api.anthropic.com/v1              # Optional
     api_key: '{{ANTHROPIC_API_KEY}}'                    # You can either hard-code or inject secrets from the Loki vault
+    auth: null                                          # When set to 'oauth', Loki will use OAuth instead of an API key
+                                                        # Authenticate with `loki --authenticate` or `.authenticate` in the REPL
 
   # See https://docs.mistral.ai/
   - type: openai-compatible

config.role.example.md

@@ -1,5 +1,9 @@
 ---
-# Everything in this section is optional
+############################################
+## Everything in this section is optional ##
+############################################
+
+# Role Configuration
 name: <role-name>                     # The name of the role
 model: openai:gpt-4o                  # The model to use for this role
 temperature: 0.2                      # The temperature to use for this role when querying the model
@@ -8,5 +12,14 @@ enabled_tools: fs_ls,fs_cat           # A comma-separated list of tools to enabl
 enabled_mcp_servers: github,gitmcp    # A comma-separated list of MCP servers to enable for this role
 prompt: null                          # A custom prompt to use for this role that will immediately query
                                       # the model for output instead of using the instructions below
+# 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
+# prompt it to continue when incomplete tasks remain.
+# See the [Todo System documentation](https://github.com/Dark-Alex-17/loki/wiki/TODO-System) for more information
+auto_continue: false                  # Enable automatic continuation when incomplete todos remain (default: false)
+max_auto_continues: 10                # Maximum number of automatic continuations before stopping (default: 10)
+inject_todo_instructions: true        # Inject default todo tool usage instructions into the system prompt (default: true)
+continuation_prompt: null             # Custom prompt used when auto-continuing. If null, uses built-in default
 ---
 You are an expert at doing things. This is where you write the instructions for the role.

docs/AGENTS.md

@@ -1,430 +0,0 @@
-# Agents
-
-Agents in Loki follow the same style as OpenAI's GPTs. They consist of 3 parts:
-
-* [Role](./ROLES.md) - Tell the LLM how to behave
-* [RAG](./RAG.md) - Pre-built knowledge bases specifically for the agent
-* [Function Calling](./function-calling/TOOLS.md#tools) ([#2](./function-calling/MCP-SERVERS.md)) - Extends the functionality of the LLM through custom functions it can call
-
-![Agent example](./images/agents/sql.gif)
-
-Agent configuration files are stored in the `agents` subdirectory of your Loki configuration directory. The location of
-this directory varies between systems so you can use the following command to locate yours:
-
-```shell
-loki --info | grep 'agents_dir' | awk '{print $2}'
-```
-
-If you're looking for more example agents, refer to the [built-in agents](../assets/agents).
-
-## Quick Links
-<!--toc:start-->
-- [Directory Structure](#directory-structure)
-- [Metadata](#1-metadata)
-- [2. Define the Instructions](#2-define-the-instructions)
-  - [Static Instructions](#static-instructions)
-    - [Special Variables](#special-variables)
-    - [User-Defined Variables](#user-defined-variables)
-  - [Dynamic Instructions](#dynamic-instructions)
-  - [Variables](#variables)
-- [3. Initializing RAG](#3-initializing-rag)
-- [4. Building Tools for Agents](#4-building-tools-for-agents)
-  - [Limitations](#limitations)
-  - [.env File Support](#env-file-support)
-  - [Python-Based Agent Tools](#python-based-agent-tools)
-  - [Bash-Based Agent Tools](#bash-based-agent-tools)
-- [5. Conversation Starters](#5-conversation-starters)
-- [Built-In Agents](#built-in-agents)
-<!--toc:end-->
-
----
-
-## Directory Structure
-Agent configurations often have the following directory structure:
-
-```
-<loki-config-dir>/agents
-    └── my-agent
-        ├── config.yaml
-        ├── tools.sh
-            or
-        ├── tools.py
-```
-
-This means that agent configurations often are only two files: the agent configuration file (`config.yaml`), and the 
-tool definitions (`agents/my-agent/tools.sh` or `tools.py`).
-
-To see a full example configuration file, refer to the [example agent config file](../config.agent.example.yaml).
-
-The best way to understand how an agent is built is to go step by step in the following manner:
-
----
-
-## 1. Metadata
-Agent configurations have the following settings available to customize each agent:
-
-```yaml
-# Model Configuration
-model: openai:gpt-4o                 # Specify the LLM to use
-temperature: null                    # Set default temperature parameter, range (0, 1)
-top_p: null                          # Set default top-p parameter, with a range of (0, 1) or (0, 2), depending on the model
-# Agent Metadata Configuration
-agent_session: null                  # Set a session to use when starting the agent. (e.g. temp, default); defaults to globally set agent_session
-# Agent Configuration
-name: <agent-name>                   # Name of the agent, used in the UI and logs
-description: <description>           # Description of the agent, used in the UI
-version: 1                           # Version of the agent
-# Function Calling Configuration
-mcp_servers:                         # Optional list of MCP servers that the agent utilizes
-  - github                           # Corresponds to the name of an MCP server in the `<loki-config-dir>/functions/mcp.json` file
-global_tools:                        # Optional list of additional global tools to enable for the agent; i.e. not tools specific to the agent
-  - web_search
-  - fs
-  - python
-```
-
-As mentioned previously: Agents utilize function calling to extend a model's capabilities. However, agents operate in 
-isolated environment, so in order for an agent to use a tool or MCP server that you have defined globally, you must 
-explicitly state which tools and/or MCP servers the agent uses. Otherwise, it is assumed that the agent doesn't use any 
-tools outside its own custom defined tools.
-
-And if you don't define a `agents/my-agent/tools.sh` or `agents/my-agent/tools.py`, then the agent is really just a 
-`role`.
-
-You'll notice there's no settings for agent-specific tooling. This is because they are handled separately and 
-automatically. See the [Building Tools for Agents](#4-building-tools-for-agents) section below for more information.
-
-To see a full example configuration file, refer to the [example agent config file](../config.agent.example.yaml).
-
-## 2. Define the Instructions
-At their heart, agents function similarly to roles in that they tell the model how to behave. Agent configuration files
-have the following settings for the instruction definitions:
-
-```yaml
-dynamic_instructions:     # Whether to use dynamically generated instructions for the agent; if false, static instructions are used. False by default.
-instructions:             # Static instructions for the LLM; These are ignored if dynamic instructions are used
-variables:                # An array of optional variables that the agent expects and uses
-```
-
-### Static Instructions
-By default, Loki agents use statically defined instructions. Think of them as being identical to the instructions for a
-[role](./ROLES.md#instructions), because they virtually are. 
-
-**Example:**
-```yaml
-instructions: |
-  You are an AI agent designed to demonstrate agentic capabilities
-```
-
-Just like roles, agents support variable interpolation at runtime. There's two types of variables that can be 
-interpolated into the instructions at runtime: special variables (like roles have), and user-defined variables. Just 
-like roles, variables are interpolated into your instructions anywhere Loki sees the `{{variable}}` syntax.
-
-#### Special Variables
-The following special variables are provided by Loki at runtime and can be injected into your agent's instructions:
-
-| Name            | Description                                                         | Example                    |
-|-----------------|---------------------------------------------------------------------|----------------------------|
-| `__os__`        | Operating system name                                               | `linux`                    |
-| `__os_family__` | Operating system family                                             | `unix`                     |
-| `__arch__`      | System architecture                                                 | `x86_64`                   |
-| `__shell__`     | The current user's default shell                                    | `bash`                     |
-| `__locale__`    | The current user's preferred language and region settings           | `en-US`                    |
-| `__now__`       | Current timestamp in ISO 8601 format                                | `2025-11-07T10:15:44.268Z` |
-| `__cwd__`       | The current working directory                                       | `/tmp`                     |
-| `__tools__`     | A list of the enabled tools (global + mcp servers + agent-specific) |                            |
-
-#### User-Defined Variables
-Agents also support user-defined variables that can be interpolated into the instructions, and are made available to any
-agent-specific tools you define (see [Building Tools for Agents](#4-building-tools-for-agents) for more details on how to 
-create agent-specific tooling).
-
-The `variables` setting in an agent's config has the following fields:
-
-| Field         | Required | Description                                                                                        |
-|---------------|----------|----------------------------------------------------------------------------------------------------|
-| `name`        | *        | The name of the variable                                                                           |
-| `description` | *        | The description of the field                                                                       |
-| `default`     |          | A default value for the field. If left undefined, the user will be prompted for a value at runtime |
-
-These variables can be referenced in both the agent's instructions, and in the tool definitions via `LLM_AGENT_VAR_<name>`.
-
-**Example:**
-```yaml
-instructions: |
-  You are an agent who answers questions about a user's system.
-
-  <tools>
-  {{__tools__}}
-  </tools>
-
-  <system>
-  os: {{__os__}}
-  os_family: {{__os_family__}}
-  arch: {{__arch__}}
-  shell: {{__shell__}}
-  locale: {{__locale__}}
-  now: {{__now__}}
-  cwd: {{__cwd__}}
-  </system>
-
-  <user>
-  username: {{username}}
-  </user>
-variables:
-  - name: username                 # Accessible from the tool definitions via the `LLM_AGENT_VAR_USERNAME` environment variable
-    description: Your user name
-```
-
-### Dynamic Instructions
-Sometimes you may find it useful to dynamically generate instructions on startup. Whether that be via a call to Loki
-itself to generate them, or by some other means. Loki supports this type of behavior using a special function defined
-in your `agents/my-agent/tools.py` or `agents/my-agent/tools.sh`.
-
-**Example: Instructions for a JSON-reader agent that specializes on each JSON input it receives**
-`agents/json-reader/tools.py`:
-```python
-import json
-from pathlib import Path
-from genson import SchemaBuilder
-
-def _instructions():
-    """Generates instructions for the agent dynamically"""
-    value = input("Enter a JSON file path OR paste raw JSON: ").strip()
-    if not value:
-        raise SystemExit("A file path or JSON string is required.")
-
-    p = Path(value)
-    if p.exists() and p.is_file():
-        json_file_path = str(p.resolve())
-        json_text = p.read_text(encoding="utf-8")
-    else:
-        try:
-            json.loads(value)
-        except json.JSONDecodeError as e:
-            raise SystemExit(f"Input is neither a file nor valid JSON.\n{e}")
-        json_file_path = "<provided-inline-json>"
-        json_text = value
-
-    try:
-        data = json.loads(json_text)
-    except json.JSONDecodeError as e:
-        raise SystemExit(f"Provided content is not valid JSON.\n{e}")
-
-    builder = SchemaBuilder()
-    builder.add_object(data)
-    json_schema = builder.to_schema()
-    return f"""
-        You are an AI agent that can view and filter JSON data with jq.
-        
-        ## Context
-        json_file_path: {json_file_path}
-        json_schema: {json.dumps(json_schema, indent=2)}
-    """
-```
-
-or
-
-`agents/json-reader/tools.sh`:
-```bash
-#!/usr/bin/env bash
-set -e
-
-# @meta require-tools jq,genson
-# @env LLM_OUTPUT=/dev/stdout The output path
-
-# @cmd Generates instructions for the agent dynamically
-_instructions() {
-	read -r -p "Enter a JSON file path OR paste raw JSON: " value
-	
-	if [[ -z "${value}" ]]; then
-		echo "A file path or JSON string is required" >&2
-		exit 1
-	fi 
-	json_file_path=""
-    inline_temp=""
-    cleanup() {
-      [[ -n "${inline_temp:-}" && -f "${inline_temp}" ]] && rm -f "${inline_temp}"
-    }
-    trap cleanup EXIT
-    
-    if [[ -f "${value}" ]]; then
-      json_file_path="$(realpath "${value}")"
-      if ! jq empty "${json_file_path}" >/dev/null 2>&1; then
-        echo "Error: File does not contain valid JSON: ${json_file_path}" >&2
-        exit 1
-      fi
-    else
-      inline_temp="$(mktemp)"
-      printf "%s" "${value}" > "${inline_temp}"
-      if ! jq empty "${inline_temp}" >/dev/null 2>&1; then
-        echo "Error: Input is neither a file nor valid JSON." >&2
-        exit 1
-      fi
-      json_file_path="<provided-inline-json>"
-    fi
-    
-    source_file="${json_file_path}"
-    if [[ "${json_file_path}" == "<provided-inline-json>" ]]; then
-      source_file="${inline_temp}"
-    fi
-    
-    json_schema="$(genson < "${source_file}" | jq -c '.')"
-	cat <<EOF >> "$LLM_OUTPUT"
-You are an AI agent that can view and filter JSON data with jq.
-
-## Context
-json_file_path: ${json_file_path}
-json_schema: ${json_schema}
-EOF
-}
-```
-
-For more information on how to create custom tools for your agent and the structure of the `agent/my-agent/tools.sh` or 
-`agent/my-agent/tools.py` files, refer to the [Building Tools for Agents](#4-building-tools-for-agents) section below.
-
-#### Variables
-All the same variable interpolations supported by static instructions is also supported by dynamic instructions. For 
-more information on what variables are available and how to use them, refer to the [Special Variables](#special-variables)
-and [User-Defined Variables](#user-defined-variables) sections above.
-
-## 3. Initializing RAG
-Each agent you create also has a dedicated knowledge base that adds additional context to your queries and helps the LLM
-answer queries effectively. The documents to load into RAG are defined in the `documents` array of your agent 
-configuration file:
-
-```yaml
-documents:
-  - https://www.ohdsi.org/data-standardization/
-  - https://github.com/OHDSI/Vocabulary-v5.0/wiki/**
-  - OMOPCDM_ddl.sql       # Relative path to agent (i.e. file lives at '<loki-config-dir>/agents/my-agent/OMOPCDM_ddl.sql')
-```
-
-These documents use the same syntax as those you'd define when constructing RAG normally. To see all the available types
-of documents that Loki supports and how to use custom document loaders, refer to the [RAG documentation](./RAG.md#supported-document-sources).
-
-Anytime your agent starts up, it will automatically be using the RAG you've defined here.
-
-## 4. Building Tools for Agents
-Building tools for agents is virtually identical to building custom tools, with one slight difference: instead of 
-defining a single function that gets executed at runtime (e.g. `main` for bash tools and `run` for Python tools), agent
-tools define a number of *subcommands*.
-
-### Limitations
-You can only utilize either a bash-based `<loki-config-dir>/agents/my-agent/tools.sh` or a Python-based 
-`<loki-config-dir>/agents/my-agent/tools.py`. However, if it's easier to achieve a task in one language vs the other, 
-you're free to define other scripts in your agent's configuration directory and reference them from the main 
-`tools.py/sh` file. **Any scripts *not* named `tools.{py,sh}` will not be picked up by Loki's compiler**, meaning they 
-can be used like any other set of scripts.
-
-It's important to keep in mind the following:
-
-* **Do not give agents the same name as an executable**. Loki compiles the tools for each agent into a binary that it
-  temporarily places on your path during execution. If you have a binary with the same name as your agent, then your 
-  shell may execute the existing binary instead of your agent's tools
-* **`LLM_ROOT_DIR` points to the agent's configuration directory**. This is where agents differ slightly from normal 
-  tools: The `LLM_ROOT_DIR` environment variable does *not* point to the `functions/tools` directory like it does in 
-  global tools. Instead, it points to the agent's configuration directory, making it easier to source scripts and other
-  miscellaneous files
-
-### .env File Support
-When Loki loads an agent, it will also search the agent's configuration directory for a `.env` file. If found, all 
-environment variables defined in the file will be made available to the agent's tools.
-
-### Python-Based Agent Tools
-Python-based tools are defined exactly the same as they are for custom tool definitions. The only difference is that 
-instead of a single `run` function, you define as many as you like with whatever arguments you like.
-
-**Example:**
-`agents/my-agent/tools.py`
-```python
-import urllib.request
-
-def get_ip_info():
-  """
-  Get your IP information
-  """
-  with urllib.request.urlopen("https://httpbin.org/ip") as response:
-    data = response.read()
-    return data.decode('utf-8')
-
-def get_ip_address_from_aws():
-    """
-    Find your public IP address using AWS
-    """
-    with urllib.request.urlopen("https://checkip.amazonaws.com") as response:
-        data = response.read()
-        return data.decode('utf-8')
-```
-
-Loki automatically compiles these as separate functions for the LLM to call. No extra work is needed. Just make sure you
-follow all the same steps to define each function as you would when creating custom Python tools.
-
-For more information on how to build tools in Python, refer to the [custom Python tools documentation](./function-calling/CUSTOM-TOOLS.md#custom-python-based-tools)
-
-### Bash-Based Agent Tools
-Bash-based agent tools are virtually identical to custom bash tools, with only one difference. Instead of defining a 
-single entrypoint via the `main` function, you actually define as many subcommands as you like.
-
-**Example:**
-`agents/my-agent/tools.sh`
-```bash
-#!/usr/bin/env bash
-
-# @env LLM_OUTPUT=/dev/stdout The output path
-# @describe Discover network information about your computer and its place in the internet
-
-# Use the `@cmd` annotation to define subcommands for your script.
-# @cmd Get your IP information
-get_ip_info() {
-  curl -fsSL https://httpbin.org/ip >> "$LLM_OUTPUT"
-}
-
-# @cmd Find your public IP address using AWS
-get_ip_address_from_aws() {
-  curl -fsSL https://checkip.amazonaws.com >> "$LLM_OUTPUT"
-}
-```
-To compile the script so it's executable and testable:
-```bash
-$ loki --build-tools
-```
-
-Then you can execute your script (assuming your current working directory is `agents/my-agent`):
-```bash
-$ ./tools.sh get_ip_info
-$ ./tools.sh get_ip_address_from_aws
-```
-
-All other special annotations (`@env`, `@arg`, `@option` `@flags`) apply to subcommands as well, so be sure to follow 
-the same syntax ad formatting as is used to create custom bash tools globally.
-
-For more information on how to write, [build and test](function-calling/CUSTOM-BASH-TOOLS.md#execute-and-test-your-bash-tools) tools in bash, refer to the 
-[custom bash tools documentation](function-calling/CUSTOM-BASH-TOOLS.md).
-
-## 5. Conversation Starters
-It's often helpful to also have some conversation starters so users know what kinds of things the agent is capable of 
-doing. These are available in the REPL via the `.starter` command and are selectable.
-
-They are defined using the `conversation_starters` setting in your agent's configuration file:
-
-**Example:**
-`agents/my-agent/config.yaml`:
-```yaml
-conversation_starters:
-  - What is my username?
-  - What is my current shell?
-  - What is my ip?
-  - How much disk space is left on my PC??
-  - How to create an agent?
-```
-
-![Example Conversation Starters](./images/agents/conversation-starters.gif)
-
-## Built-In Agents
-Loki comes packaged with some useful built-in agents:
-* `coder`: An agent to assist you with all your coding tasks
-* `demo`: An example agent to use for reference when learning to create your own agents
-* `jira-helper`: An agent that assists you with all your Jira-related tasks
-* `sql`: A universal SQL agent that enables you to talk to any relational database in natural language
-

docs/AICHAT-MIGRATION.md

@@ -1,211 +0,0 @@
-# AIChat to Loki Migration Guide
-Loki originally started as a fork of AIChat but has since evolved into its own separate project with separate goals.
-
-As a result, there's some changes you'll need to make to your AIChat configuration to be able to use Loki.
-
-Be sure you've followed the [first-time setup steps](../README.md#first-time-setup) so that the Loki configuration 
-directory and subdirectories exist and is populated with the built-in defaults.
-
-## Global Configuration File
-You should be able to copy/paste your AIChat configuration file into your Loki configuration directory. Since the 
-location of the Loki configuration directory varies between systems, you can use the following command to locate your
-config directory:
-
-```shell
-loki --info | grep 'config_dir' | awk '{print $2}'
-```
-
-Then, you'll need to make the following changes:
-
-* `function_calling` -> `function_calling_support`
-* `use_tools` -> `enabled_tools`
-* `agent_prelude` -> `agent_session`
-* `compress_threshold` -> `compression_threshold`
-* `summarize_prompt` -> `summarization_prompt`
-* `summary_prompt` -> `summary_context_prompt`
-
-## Roles
-Locate your `roles` directory using the following command:
-
-```shell
-loki --info | grep 'roles_dir' | awk '{print $2}'
-```
-
-Update any roles that have `use_tools` to `enabled_tools`.
-
-## Sessions
-Locate your `sessions` directory using the following command:
-
-```shell
-loki --info | grep 'sessions_dir' | awk '{print $2}'
-```
-
-Update the following settings:
-* `use_tools` -> `enabled_tools`
-* `compress_threshold` -> `compression_threshold`
-* `summarize_prompt` -> `summarization_prompt`
-* `summary_prompt` -> `summary_context_prompt`
-
----
-
-# LLM Functions Changes
-Probably the most significant difference between AIChat and Loki is how tools are handled. So if you cloned the 
-[llm-functions](https://github.com/sigoden/llm-functions) repo, you'll need to make the following changes.
-
-**Note: JavaScript functions are not supported in Loki.**
-
-The following guide assumes you're using the `llm-functions` repository as your base for custom functions, and thus
-follows that directory structure.
-
-## Agents
-Agents are now all handled in one place: the `agents` directory (`<loki-config-dir>/agents`):
-
-```shell
-loki --info | grep 'agents_dir' | awk '{print $2}'
-```
-
-And instead of separate `index.yaml` and `config.yaml` files, they're now both in a single `config.yaml` file.
-
-So now for all of your agents, copy all the contents of those directories to the corresponding directory in the Loki 
-`agents` directory. Then make the following changes:
-
-* Copy the contents of your `<aichat-config-dir>/functions/agents` directory into `<loki-config-dir/agents`
-* Merge `index.yaml` into `config.yaml`
-  * If you never created a custom `config.yaml` file, then simply rename `index.yaml` to `config.yaml`
-  * If you've defined an `agent_prelude`, rename that field to `agent_session`
-* Convert all JavaScript tools to either Python or Bash
-* For Bash `tools.sh`: Remove the following line:
-  ```bash
-  eval "$(argc --argc-eval "$0" "$@")"
-  ```
-* Any `tools.txt` files you have that define what global functions the agent uses is now replaced by the `global_tools`
-  field in the agent's `config.yaml`. So for example: If your `tools.txt` looks like this:
-  ```text
-  fs_mkdir.sh
-  fs_ls.sh
-  fs_patch.sh
-  fs_cat.sh
-  ```
-  then you need to add the following to your agent's `config.yaml`:
-  ```yaml
-  global_tools:
-    - fs_mkdir.sh
-    - fs_ls.sh
-    - fs_patch.sh
-    - fs_cat.sh
-  ```
-* If you have any bash `tools.sh` that depend on the utility scripts in the `llm-functions` repository, they've been 
-  replaced by built-in utility scripts. So use the following to replace any matching lines in your `tools.sh` files:
-  ```bash
-  ##################
-  ## Scripts file ##
-  ##################
-  ROOT_DIR="${LLM_ROOT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
-  # replace with
-  source "$LLM_PROMPT_UTILS_FILE"
-  
-  #######################
-  ## guard_path script ##
-  #######################
-  "$ROOT_DIR/utils/guard_path.sh"
-  # replace with
-  guard_path
-  
-  ############################
-  ## guard_operation script ##
-  ############################
-  "$ROOT_DIR/utils/guard_operation.sh"
-  # replace with
-  guard_operation
-  
-  ######################
-  ## patch.awk script ##
-  ######################
-  awk -f "$ROOT_DIR/utils/patch.awk"
-  # replace with
-  patch_file
-  ```
-  
-When you're done with this migration, you should have the following:
-
-* No more `functions/agents` directory
-* No `functions/agents.txt` file (Loki assumes that if the agent directory exists, it is loadable)
-* No `<loki-config-dir>/agents/<agent-name>/tools.txt`
-* No `<loki-config-dir>/agents/<agent-name>/index.yaml`
-
-## Functions
-Loki consolidates much of the `llm-functions` repo functionality into one binary. So this means
-
-* There's no need to have `argc` installed anymore
-* No separate repository to manage
-* No `tools.txt`
-* No `functions.json`
-* No `functions/mcp` directory at all
-* No `functions/scripts`
-
-Here's how to migrate your functions over to Loki from the `llm-functions` repository.
-
-* Copy your AIChat `<aichat-config-dir>/functions` directory into your Loki config directory
-* Delete the following files and directories from your `<loki-config-dir>/functions` directory:
-  * `scripts/`
-  * `agents.txt`
-  * `functions.json`
-  * `Argcfile.sh`
-  * `README.md` (irrelevant now)
-  * `LICENSE` (irrelevant now)
-  * `utils/guard_operation.sh`
-  * `utils/guard_path.sh`
-  * `utils/patch.awk`
-* Everything in `tools.txt` now lives in the global config file under the `visible_tools` setting:
-  ```text
-  get_current_weather.sh
-  execute_command.sh
-  web_search.sh
-  #execute_py_code.py
-  query_jira_issues.sh
-  ```
-  becomes the following in your `<loki-config-dir>/config.yaml`
-  ```yaml
-  visible_tools:
-    - get_current_weather.sh
-    - execute_command.sh
-    - web_search.sh
-    # - web_search.sh
-    - query_jira_issues.sh
-  ```
-* If you've defined a `functions/mcp.json` file, you can leave it alone.
-* Similarly to agents, if you have any bash `tools.sh` that depend on the utility scripts in the `llm-functions` 
-  repository, they've been replaced by built-in utility scripts. So use the following to replace any matching lines in 
-  your `tools.sh` files:
-  ```bash
-  ##################
-  ## Scripts file ##
-  ##################
-  ROOT_DIR="${LLM_ROOT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
-  # replace with
-  source "$LLM_PROMPT_UTILS_FILE"
-  
-  #######################
-  ## guard_path script ##
-  #######################
-  "$ROOT_DIR/utils/guard_path.sh"
-  # replace with
-  guard_path
-  
-  ############################
-  ## guard_operation script ##
-  ############################
-  "$ROOT_DIR/utils/guard_operation.sh"
-  # replace with
-  guard_operation
-  
-  ######################
-  ## patch.awk script ##
-  ######################
-  awk -f "$ROOT_DIR/utils/patch.awk"
-  # replace with
-  patch_file
-  ```
-  
-Refer to the [custom bash tools docs](./function-calling/CUSTOM-BASH-TOOLS.md) to learn how to compile and test bash 
-tools in Loki without needing to use `argc`.

docs/ENVIRONMENT-VARIABLES.md

@@ -1,106 +0,0 @@
-# Environment Variables
-
-Loki is designed to be highly dynamic and customizable. As a result, Loki utilizes a number of environment variables
-that can be used to modify its behavior at runtime without needing to modify the existing configuration files.
-
-Loki also supports defining environment variables via a `.env` file in the Loki configuration directory. This directory
-varies between systems, so you can find the location of your configuration directory using the following command:
-
-```shell
-loki --info | grep 'config_dir' | awk '{print $2}'
-```
-
-## Quick Links
-<!--toc:start-->
-- [Global Configuration Related Variables](#global-configuration-related-variables)
-- [Client Related Variables](#client-related-variables)
-- [Files and Directory Related Variables](#files-and-directory-related-variables)
-- [Agent Related Variables](#agent-related-variables)
-- [Logging Related Variables](#logging-related-variables)
-<!--toc:end-->
-
----
-
-## Global Configuration Related Variables
-All configuration items in the global config file have environment variables that can be overridden at runtime. To see
-all configuration options and more thorough descriptions, refer to the [example config file](../config.example.yaml).
-
-Below are the most commonly used configuration settings and their corresponding environment variables:
-
-| Setting                    | Environment Variable            |
-|----------------------------|---------------------------------|
-| `model`                    | `LOKI_MODEL`                    |
-| `temperature`              | `LOKI_TEMPERATURE`              |
-| `top_p`                    | `LOKI_TOP_P`                    |
-| `stream`                   | `LOKI_STREAM`                   |
-| `save`                     | `LOKI_SAVE`                     |
-| `editor`                   | `LOKI_EDITOR`                   |
-| `wrap`                     | `LOKI_WRAP`                     |
-| `wrap_code`                | `LOKI_WRAP_CODE`                |
-| `save_session`             | `LOKI_SAVE_SESSION`             |
-| `compression_threshold`    | `LOKI_COMPRESSION_THRESHOLD`    |
-| `function_calling_support` | `LOKI_FUNCTION_CALLING_SUPPORT` |
-| `enabled_tools`            | `LOKI_ENABLED_TOOLS`            |
-| `mcp_server_support`       | `LOKI_MCP_SERVER_SUPPORT`       |
-| `enabled_mcp_servers`      | `LOKI_ENABLED_MCP_SERVERS`      |
-| `rag_embedding_model`      | `LOKI_RAG_EMBEDDING_MODEL`      |
-| `rag_reranker_model`       | `LOKI_RAG_RERANKER_MODEL`       |
-| `rag_top_k`                | `LOKI_RAG_TOP_K`                |
-| `rag_chunk_size`           | `LOKI_RAG_CHUNK_SIZE`           |
-| `rag_chunk_overlap`        | `LOKI_RAG_CHUNK_OVERLAP`        |
-| `highlight`                | `LOKI_HIGHLIGHT`                |
-| `theme`                    | `LOKI_THEME`                    |
-| `serve_addr`               | `LOKI_SERVE_ADDR`               |
-| `user_agent`               | `LOKI_USER_AGENT`               |
-| `save_shell_history`       | `LOKI_SAVE_SHELL_HISTORY`       |
-| `sync_models_url`          | `LOKI_SYNC_MODELS_URL`          |
-
-
-## Client Related Variables
-The following environment variables are available for clients in Loki:
-
-| Environment Variable                   | Description                                                                                                                                                                                                                                             |
-|----------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `{client}_API_KEY`                     | For clients that require an API key, you can define the keys either through environment variables or <br>using the [vault](./VAULT.md). The variables are named after the client to which they apply; <br>e.g. `OPENAI_API_KEY`, `GEMINI_API_KEY`, etc. |
-| `LOKI_PLATFORM`                        | Combine with `{client}_API_KEY` to run Loki without a configuration file. <br>This variable is ignored if a configuration file exists.                                                                                                                  |
-| `LOKI_PATCH_{client}_CHAT_COMPLETIONS` | Patch chat completion requests to models on the corresponding client; Can modify the URL, body, <br>or headers.                                                                                                                                         | 
-| `LOKI_SHELL`                           | Specify the shell that Loki should be using when executing commands                                                                                                                                                                                     |
-
-## Files and Directory Related Variables
-You can also customize the files and directories that Loki loads its configuration files from:
-
-| Environment Variable | Description                                                            | Default Value                   |
-|----------------------|------------------------------------------------------------------------|---------------------------------|
-| `LOKI_CONFIG_DIR`    | Customize the location of the Loki configuration directory.            | `<user-config-dir>/loki`        |
-| `LOKI_ENV_FILE`      | Customize the location of the `.env` file to load at startup.          | `<loki-config-dir>/.env`        |
-| `LOKI_CONFIG_FILE`   | Customize the location of the global `config.yaml` configuration file. | `<loki-config-dir>/config.yaml` |
-| `LOKI_ROLES_DIR`     | Customize the location of the `roles` directory.                       | `<loki-config-dir>/roles`       |
-| `LOKI_SESSIONS_DIR`  | Customize the location of the `sessions` directory.                    | `<loki-config-dir>/sessions`    |
-| `LOKI_RAGS_DIR`      | Customize the location of the `rags` directory.                        | `<loki-config-dir>/rags`        |
-| `LOKI_FUNCTIONS_DIR` | Customize the location of the `functions` directory.                   | `<loki-config-dir>/functions`   |
-
-## Agent Related Variables
-You can also customize the location of full agent configurations using the following environment variables:
-
-| Environment Variable         | Description                                                                                                                         |
-|------------------------------|-------------------------------------------------------------------------------------------------------------------------------------|
-| `<AGENT_NAME>_CONFIG_FILE    | Customize the location of the agent's configuration file; e.g. `SQL_CONFIG_FILE`                                                    |
-| `<AGENT_NAME>_MODEL`         | Customize the `model` used for the agent; e.g `SQL_MODEL`                                                                           |
-| `<AGENT_NAME>_TEMPERATURE`   | Customize the `temperature` used for the agent; e.g. `SQL_TEMPERATURE`                                                              |
-| `<AGENT_NAME>_TOP_P`         | Customize the `top_p` used for the agent; e.g. `SQL_TOP_P`                                                                          |
-| `<AGENT_NAME>_GLOBAL_TOOLS`  | Customize the `global_tools` that are enabled for the agent (a JSON string array); e.g. `SQL_GLOBAL_TOOLS`                          |
-| `<AGENT_NAME>_MCP_SERVERS`   | Customize the `mcp_servers` that are enabled for the agent (a JSON string array); e.g. `SQL_MCP_SERVERS`                            |
-| `<AGENT_NAME>_AGENT_SESSION` | Customize the `agent_session` used with the agent; e.g. `SQL_SESSION`                                                               |
-| `<AGENT_NAME>_INSTRUCTIONS`  | Customize the `instructions` for the agent; e.g. `SQL_INSTRUCTIONS`                                                                 |
-| `<AGENT_NAME>_VARIABLES`     | Customize the `variables` used for the agent (in JSON format of `[{"key1": "value1", "key2": "value2"}]`); <br>e.g. `SQL_VARIABLES` |
-
-## Logging Related Variables
-The following variables can be used to change the log level of Loki or the location of the log file:
-
-| Environment Variable | Description                                 | Default Value                    |
-|----------------------|---------------------------------------------|----------------------------------|
-| `LOKI_LOG_LEVEL`     | Customize the log level of Loki             | `INFO`                           |
-| `LOKI_LOG_FILE`      | Customize the location of the Loki log file | `<user-cache-dir>/loki/loki.log` |
-
-**Pro-Tip:** You can always tail the Loki logs using the `--tail-logs` flag. If you need to disable color output, you
-can also pass the `--disable-log-colors` flag as well.

docs/MACROS.md

@@ -1,103 +0,0 @@
-# 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

docs/RAG.md

@@ -1,299 +0,0 @@
-# RAG
-Retrieval Augmented Generation (RAG) is a method of minimizing LLM hallucinations and extending the model's context 
-without consuming a significant portion of the context length. It uses documents and other additional resources that you
-provide to give the model more context for all of your prompts.
-
-Loki has a built-in vector database and full-text search engine to support RAG knowledge bases for your queries.
-
-The generated knowledge bases are stored in the `rag` subdirectory of your Loki configuration directory. The location of 
-this directory varies by system, so you can use the following command to find your RAG directory:
-
-```shell
-loki --info | grep 'rags_dir' | awk '{print $2}'
-```
-
-## Quick Links
-<!--toc:start-->
-- [Usage](#usage)
-  - [Persistent RAG](#persistent-rag)
-  - [Ephemeral RAG](#ephemeral-rag)
-- [How It Works](#how-it-works)
-    - [1. Build](#1-build)
-    - [2. Lookup](#2-lookup)
-    - [2a. Reranking (Optional)](#2a-reranking-optional)
-    - [3. Prompt](#3-prompt)
-- [Supported Document Sources](#supported-document-sources)
-- [Document Loaders](#document-loaders)
-  - [Document Loader Usage](#document-loader-usage)
-- [Advanced Customizations](#advanced-customizations)
-  - [Embedding Model](#embedding-model)
-  - [Reranker](#reranker)
-  - [Chunk Size](#chunk-size)
-    - [Trade-Offs](#chunk-size-trade-offs)
-  - [Chunk Overlap](#chunk-overlap)
-  - [Top K](#top-k)
-    - [Trade-Offs](#top-k-trade-offs)
-  - [RAG Template](#rag-template)
-<!--toc:end-->
-
----
-
-## Usage
-There's two ways to use RAG in Loki: A persistent RAG that can be loaded on-demand for queries, and an ephemeral one for
-adding RAG to a single specific query.
-
-### Persistent RAG
-In the REPL, persistent RAG is initialized via the `.rag` command:
-
-![Persistent RAG example](./images/rag/persistent-rag.gif)
-
-The generated RAG is then saved to the `rag` subdirectory of the Loki configuration, and can then be loaded whenever you
-want that knowledge base via either `.rag <name>` or `loki --rag <RAG>`.
-
-### Ephemeral RAG
-Short-lived RAG that is only used for a single session or query is loaded using `.file`/`--file`.
-
-You can use it to either execute a prompt from a file, or for temporary RAG. The difference is the usage of the `--` 
-separator. If you only specify a filename and no `--` separator, Loki will know to read the file contents and pass them 
-as a query to the model. Otherwise, the `--` separator is read to indicate that this is the end of the list of documents
-to load into the ephemeral RAG, and what follows is the query to pass to the model.
-
-```shell
-.file prompt.md # Read the file as a prompt
-.file %% -- translate the last reply to italian
-.file `git diff` -- generate a commit message
-```
-
-![Ephemeral RAG Example](./images/rag/ephemeral-rag.gif)
-
-Once the session ends, this RAG will no longer be accessible and is only visible to the current session.
-
-#### The `%%` Document Type
-In addition to the usual documents that can be specified for persistent RAG, ephemeral RAG has a special `%%` value. 
-This value references the content of the last reply. So you can use it like this:
-
-```shell
-.file %% -- translate the last reply to italian
-```
-
-The `--` indicates that this is the end of your documents and the beginning of your prompt.
-
-#### The `cmd` Document Type
-Loki also lets you use command outputs for ephemeral RAG input. Simply enclose the command in backticks:
-
-```shell
-.file `git diff` -- generate a commit message
-```
-
-The `--` indicates that this is the end of your documents and the beginning of your prompt.
-
-## How It Works
-#### 1. Build
-When you define RAG, Loki will first "build" the RAG. This means that Loki will consume the documents you specified and
-generate [embeddings](https://huggingface.co/spaces/hesamation/primer-llm-embedding) for that text. This essentially just means that Loki translates the document into a language 
-the LLM can understand.
-
-These embeddings are then stored in an in-memory vector database.
-
-#### 2. Lookup
-Loki sits between you and the model. So when you submit a prompt to the model, before Loki ever sends it, it will first 
-convert your prompt into embeddings (LLM language), and look for relevant snippets of text in the vector database.
-
-Loki then passes the top `n`-snippets of text that it finds in the vector database as additional context to the model
-before your prompt.
-
-#### 2a. Reranking (Optional)
-The lookup for relevant snippets of texts uses embeddings to find text that is semantically similar to your prompt, and 
-returns the top `n`-results. This often works fairly well, however these top results aren't always the most relevant for
-answering the specific query.
-
-Reranking improves these initial results (say, the top 20-100 text snippets) and re-scores them using a more 
-sophisticated model. The reranker model will rank documents by their actual usefulness for answering the query to ensure
-the most relevant context is passed to the model alongside your query.
-
-This reranking model can be customized for each RAG you build in Loki. See the [Custom Reranker](#reranker) section
-below for more details on how to customize this.
-
-#### 3. Prompt
-Finally, the text snippets that were looked up in RAG are passed to the model as additional context to your prompt, 
-giving the model query-specific context to answer your question.
-
-## Supported Document Sources
-Loki supports a number of document sources that can be used for RAG:
-
-| Source                   | Example                                                               | Comments                                                                                                                                                 |
-|--------------------------|-----------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Files                    | `/tmp/dir1/file1;/tmp/dir1/file2`                                     |                                                                                                                                                          | 
-| Directory                | `/tmp/dir`                                                            | Picks up all files in a directory and all its subdirectories                                                                                             |
-| Directory (extensions}   | `/tmp/dir2/**/*.{md,txt}`                                             | Finds all files in all subdirectories with the specified extensions                                                                                      |
-| Recursive Filename       | `/tmp/*/LOKI.md`                                                      | The following files will be picked up: <br><ul><li>`/tmp/dir1/LOKI.md`</li><li>`/tmp/dir2/subdir1/LOKI.md`</li><li>`/tmp/dir2/subdir2/LOKI.md`</li></ul> |
-| URL                      | `https://www.ohdsi.org/data-standardization/`                         | Downloads and loads the specified webpage into the <br>knowledge base                                                                                    |
-| Recursive URL (Websites) | `https://github.com/OHDSI/Vocabulary-v5.0/wiki/**`                    | Crawls all pages under the given URL and loads them <br>into the knowledge base                                                                          |
-| Document Loader (custom) | `jina:https://cloud.google.com/bigquery/docs/reference/standard-sql/` | Use a custom document loader to parse the given document                                                                                                 | 
-
-## Document Loaders
-Loki only has built-in support for loading text files. But that functionality can be extended to read all kinds of files
-into your knowledge bases. These custom loaders are used by both RAG and for documents specified using the 
-`.file`/`--file` flags.
-
-In the global configuration file, you can specify loaders for specific document types using the `document_loaders` 
-setting. Each loader is defined by specifying a name and then a command that Loki will execute to load the document.
-
-The following variables are interpolated at runtime by Loki and can be used as placeholders in your command definitions:
-* `$1` (Required) - The input file
-* `$2` (Optional) - The output file. If omitted, `stdout` is used as the output destination
-
-**Note:** It is your responsibility to ensure that any tools used to parse documents into text that Loki can read are 
-installed on your system and are available on your `$PATH`. Loki does not have any built-in way of installing 
-dependencies for document loaders for you.
-
-The following are some example loaders:
-```yaml
-document_loaders:
-  pdf: 'pdftotext $1 -'                                                                 # Use pdftotext to convert a PDF file to text
-                                                                                        # (see https://poppler.freedesktop.org for details on how to install pdftotext)
-  docx: 'pandoc --to plain $1'                                                          # Use pandoc to convert a .docx file to text
-                                                                                        # (see https://pandoc.org for details on how to install pandoc)
-  jina: 'curl -fsSL https://r.jina.ai/$1 -H "Authorization: Bearer {{JINA_API_KEY}}'    # Use Jina to translate a website into text;
-                                                                                        # Requires a Jina API key to be added to the Loki vault
-  git: >                                                                                # Use yek to load a git repository into the knowledgebase (https://github.com/bodo-run/yek)
-    sh -c "yek $1 --json | jq 'map({ path: .filename, contents: .content })'" 
-```
-
-### Document Loader Usage
-Once you have your loaders defined, you can specify when Loki should use them by prefixing any RAG file/directory/URI 
-with the name of the loader.
-
-**Example: Load a git repo into RAG**
-![Git Repo Loader Example](./images/rag/git-loader.png)
-
-**Example: Use pdf loader for ephemeral RAG**
-```shell
-$ loki --file pdf:some-file.pdf
-```
-
-## Advanced Customizations
-For those familiar with RAG, Loki exposes a handful of advanced global settings that can be used to tweak your default
-RAG configurations.
-
-### Embedding Model
-When Loki queries your RAG knowledge bases, it needs to first convert your query into embeddings. By default, Loki uses 
-the same embedding model that was used to create the knowledge base in the first place.
-
-This can be customized to any other embedding model available in your configured clients by setting the 
-`rag_embedding_model` setting in your global Loki configuration file:
-
-```yaml
-rag_embedding_model: null        # Specifies the embedding model used for context retrieval
-```
-
-### Reranker
-By default, Loki uses [Reciprocal Rank Fusion (RRF)](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/reciprocal-rank-fusion) to merge vector and keyword search results.
-
-You can change the default reranker model to any other reranking model in your configured clients. To change the default
-reranker model, simply change the value of the `rag_reranker_model` setting in your global configuration file:
-
-```yaml
-rag_reranker_model: null       # By default, 
-```
-
-### Chunk Size
-In the context of RAG, the chunk size is the maximum length of each text chunk (measured in characters) that is created 
-when splitting documents. In Loki, this defaults to `2000` characters.
-
-You can specify a different global default by setting the `rag_chunk_size` property in your global configuration file:
-
-```yaml
-rag_chunk_size: null             # Defines the size of chunks for document processing in characters
-```
-
-#### Chunk Size Trade-Offs
-Keep in mind the following trade-offs when changing the chunk size:
-
-* **Smaller chunks (e.g. 256 characters):** More precise retrieval, better semantic focus, but may lack context or split
-  important information
-* **Larger chunks (e.g. 1024 characters):** More context preserved, fewer chunks to manage, but less precise matching 
-  and more noise in retrieved document
-
-### Chunk Overlap
-Chunk overlap in RAG is the number of characters that overlap between consecutive chunks to maintain continuity. 
-
----
-
-**Example:** If the following sentence is cut off at the end of one chunk
-
-`I was doing fine until someone brought up`
-
-You'll ideally want that full sentence to be picked up at the beginning of the next chunk to make sure the full meaning 
-is captured. So in this example, if your chunk overlap is 42 characters, then the start of the next chunk would look
-like this:
-
-`I was doing fine until someone brought up the game. <next sentence>`
-
----
-
-Often, this value is 10%-20% of the chunk size.
-
-By default, in Loki, this value is 5% the chunk size. You can override this and specify the default chunk overlap (in 
-characters) that Loki should use as a global default by setting the `rag_chunk_overlap` property in the global Loki 
-configuration file:
-
-```yaml
-rag_chunk_overlap: null          # Defines the overlap between chunks
-```
-
-### Top K
-In RAG, `top_k` represents the top `k`-chunks to return from the vector database query. Think of it like if you search 
-something on Google and only care about the top 10 results, that's what you'll use for your context.
-
-In Loki, the default value for this is `5`. You can customize this global default by setting the `rag_top_k` property in
-your global configuration file:
-
-```yaml
-rag_top_k: 5                     # Specifies the number of documents to retrieve for answering queries
-```
-
-#### Top K Trade-Offs
-When customizing this value, keep in mind the following trade-offs so you get the best performance:
-
-* **Lower top_k (e.g. 3):** Faster, more focused context, lower cost, but risks missing relevant information
-* **Higher top_k (e.g. 10):** More comprehensive coverage, but more noise, higher latency, increased token costs, and 
-  potential context window constraints
-
-### RAG Template
-When you use RAG in Loki, after Loki performs the lookup for relevant chunks of text to add as context to your query, it
-will add the retrieved text chunks as context to your query before sending it to the model. The format of this context
-is determined by the `rag_template` setting in your global Loki configuration file.
-
-This template utilizes two placeholders:
-* `__INPUT__`: The user's actual query
-* `__CONTEXT__`: The context retrieved from RAG
-
-These placeholders are replaced with the corresponding values into the template and make up what's actually passed to 
-the model at query-time.
-
-The default template that Loki uses is the following:
-
-```text
-Answer the query based on the context while respecting the rules. (user query, some textual context and rules, all inside xml tags)
-
-<context>
-__CONTEXT__
-</context>
-
-<rules>
-- If you don't know, just say so.
-- If you are not sure, ask for clarification.
-- Answer in the same language as the user query.
-- If the context appears unreadable or of poor quality, tell the user then answer as best as you can.
-- If the answer is not in the context but you think you know the answer, explain that to the user then answer with your own knowledge.
-- Answer directly and without using xml tags.
-</rules>
-
-<user_query>
-__INPUT__
-</user_query>
-```
-
-You can customize this template by specifying the `rag_template` setting in your global Loki configuration file. Your 
-template *must* include both the `__INPUT__` and `__CONTEXT__` placeholders in order for it to be valid.

docs/REPL-PROMPT.md

@@ -1,117 +0,0 @@
-# Customize REPL Prompt
-
-The prompt you see when you start the Loki REPL can be customized to your liking. This is achieved via the `left_prompt`
-and `right_prompt` settings in the global Loki configuration file:
-
-```yaml
-left_prompt: '{color.red}{model}){color.green}{?session {?agent {agent}>}{session}{?role /}}{!session {?agent {agent}>}}{role}{?rag @{rag}}{color.cyan}{?session )}{!session >}{color.reset} '
-right_prompt: '{color.purple}{?session {?consume_tokens {consume_tokens}({consume_percent}%)}{!consume_tokens {consume_tokens}}}{color.reset}'
-```
-
-The location of the global configuration file differs between systems, so you can use the following command to find your
-global configuration file's location:
-
-```shell
-loki --info | grep 'config_file' | awk '{print $2}'
-```
-
-## Quick Links
-<!--toc:start-->
-- [Syntax](#syntax)
-- [Variables](#variables)
-<!--toc:end-->
-
-## Syntax
-The syntax for the prompts consists of plain text and templates contained in `{...}`. The plain text is 
-printed exactly as given. 
-
-The syntax for the templates `{...}` is as follows:
-
-* `{variable}` - Replaced with the value of `variable`
-* `{?variable <template>}` - Evaluate the `<template>` when `variable` is evaluated to `true`
-* `{!variable <template>}` - Evaluate the `<template>` when `variable` is evaluated to `false`
-
-Where a `<template>` is another expression consisting of plain text and/or more special computations inside `{...}`.
-
-Variables are evaluated to also be "truthy"; that is, if a variable is undefined, it is considered to be the exact same
-as if that variable's value was `false`.
-
-**Example 1: Simple Boolean Usage**
-For the prompt `{?variable yay}{!variable boo}`, if `variable=true`, then the output will be
-```
-yay
-```
-
-And if `variable=false`:
-```
-boo
-```
-
-**Example 2: Nested Expressions**
-For the prompt `{?variable {!variable2 yay}>}`, and assuming
-* `variable=true`
-* `variable2=false`
-the output will be
-```
-yay>
-```
-
-If `variable2=true`, the output will be empty.
-
-If `variable=false`, the output will be empty.
-
-## Variables
-The following variables and output modifiers are available to you when you're creating your prompts:
-
-```yaml
-# Model Variables
-model: openai:gpt-4            # The active model's full name
-client_name: openai            # The name of the client serving the active model
-model_name: gpt-4              # The aliased name of the active model
-max_input_tokens: 4096         # The maximum number of input tokens for the active model
-
-# Configuration Variables
-temperature: 1.0               # The temperature for the active model
-top_p: 0.9                     # The top_p for the active model
-dry_run: true                  # Whether the given command is flagged to be a dry run
-stream: false                  # Whether streaming responses are enabled
-save: true                     # Whether shell history is saved
-wrap: 120                      # The number of characters to allow before wrapping around output to the next line
-
-# Role Variables
-role: code                     # The active role 
-
-# Session Variables
-session: temp                  # The name of the active session
-dirty: false                   # Whether the session settings have been updated but not persisted
-consume_tokens: 200            # The number of tokens consumed
-consume_percent: 1%            # The percentage of tokens consumed to the maximum input tokens
-user_messages_len: 0           # The total number of sent user messages 
-
-# RAG Variables
-rag: temp                      # The name of the active RAG
-
-# Agent Variables
-agent: todo-sh                 # The name of the active agent
-
-# ANSI COLORS
-color.reset:
-color.black:
-color.dark_gray:
-color.red:
-color.light_red:
-color.green:
-color.light_green:
-color.yellow:
-color.light_yellow:
-color.blue:
-color.light_blue:
-color.purple:
-color.light_purple:
-color.magenta:
-color.light_magenta:
-color.cyan:
-color.light_cyan:
-color.white:
-color.light_gray:
-```

docs/REPL.md

@@ -1,250 +0,0 @@
-# Loki REPL Guide
-In addition to being a CLI, Loki also has a built-in REPL (Read-Execute-Print-Loop). This enables users to quickly try
-out prompts, commands, configurations, and everything in between without having to modify the same command every time.
-
-You can enter the REPL by simply typing `loki` without any follow-up flags or arguments.
-## Quick Links
-<!--toc:start-->
-- [Features](#features)
-- [REPL Commands](#repl-commands)
-    - [`.model` - Change the current LLM](#model---change-the-current-llm)
-    - [`.role` - Role management](#role---role-management)
-    - [`.prompt` - Set a temporary role using a prompt](#prompt---set-a-temporary-role-using-a-prompt)
-    - [`.session` - Session management](#session---session-management)
-    - [`.agent` - Chat with an AI agent](#agent---chat-with-an-ai-agent)
-    - [`.rag` - Chat with documents](#rag---chat-with-documents)
-    - [`.macro` - Execute a macro](#macro---execute-a-macro)
-    - [`.file` - Read files and use them as input](#file---read-files-and-use-them-as-input)
-    - [`.vault` - Manage the Loki vault](#vault---manage-the-loki-vault)
-    - [`.continue` - Continue the previous response](#continue---continue-the-previous-response)
-    - [`.regenerate` - Regenerate the last response](#regenerate---regenerate-the-last-response)
-    - [`.copy` - Copy the last response to your clipboard](#copy---copy-the-last-response-to-your-clipboard)
-    - [`.set` - Adjust runtime settings](#set---adjust-runtime-settings)
-    - [`.edit` - Modify configuration files](#edit---modify-configuration-files)
-    - [`.delete` - Delete configurations from Loki](#delete---delete-configurations-from-loki)
-    - [`.info` - Display information about the current mode](#info---display-information-about-the-current-mode)
-    - [`.exit` - Exit an agent/role/session/rag or the Loki REPL itself](#exit---exit-an-agentrolesessionrag-or-the-loki-repl-itself)
-    - [`.help` - Show the help guide](#help---show-the-help-guide)
-<!--toc:end-->
-
----
-
-## Features
-The REPL has features that are intended to make your Loki experience as easy and as enjoyable as possible! This includes
-things like
-
-* **Tab Autocompletion:** Every command in the REPL (i.e. everything that starts with a `.`) has fuzzy search auto 
-  completions. 
-  * `.<tab>` to complete REPL commands
-  * `.model <tab>` to complete chat models
-  * `.set <tab>` to complete configuration keys
-  * `.set key <tab>` to complete configuration values
-* **Multi-Line Prompts:** You can also type prompts that span more than one line to help organize your thoughts. This 
-  can be done in the following ways:
-  * `Ctrl-o` to open the current input buffer in your preferred editor (either the value of `editor` or `$EDITOR`)
-  * You can paste multi-line text
-  * You can type `:::` to start multi-line editing, and use `:::` to finish it.
-  * And finally, you can use hotkeys like `{ctrl/shift/alt}+enter` or `ctrl-j` to insert a new line directly in the 
-    REPL.
-* **History Search** Press `ctrl+r` to search the REPL history, and navigate it with `↑↓`
-* **Configurable Keybindings:** You can switch between `emacs` style keybindings or `vi` style keybindings
-* [**Custom REPL Prompt:**](./REPL-PROMPT.md) You can even customize the REPL prompt to display information about the 
-  current context in the prompt
-
----
-
-## REPL Commands
-All REPL commands begin with a `.` to indicate that they're not part of a prompt. The following list details the 
-commands available in Loki:
-
-### `.model` - Change the current LLM
-When browsing models in the REPL, use the following legend to understand the purpose of each column in the model table:
-```
-openai:gpt-4o     128000 /     4096  |       5 /     15    👁 ⚒ 
-|                 |            |             |       |     |  └─ supports function calling
-|                 |            |             |       |     └─ support vision (multi-modal)
-|                 |            |             |       └─ output price ($/1M)
-|                 |            |             └─ input price ($/1M)
-|                 |            |
-|                 |            └─ max output tokens
-|                 └─ max input tokens
-└─ model id
-```
-![model](./images/repl/model.gif)
-
-For more information about how to add models to Loki, refer to the [clients documentation](./clients/CLIENTS.md).
-
-### `.role` - Role management
-Loki offers the following commands to manage your roles:
-
-| Command      | Description                                                             |
-|--------------|-------------------------------------------------------------------------|
-| `.role`      | Create or switch to a role                                              |
-| `.info role` | Show information about the active role                                  |
-| `.edit role` | Open the active role's configuration file in your preferred text editor |
-| `.save role` | Save the active role and its configurations to a configuration file     |
-| `.exit role` | Exit the active role                                                    |
-
-![role](./images/roles/code.gif)
-
-For more information about roles in Loki and how to build them, refer to the [roles documentation](./ROLES.md).
-
-### `.prompt` - Set a temporary role using a prompt
-If you need to create a temporary role that you want to discard after use, you use `.prompt`. `.prompt`-based roles 
-cannot be persisted to a file and saved.
-
-![prompt-role](./images/roles/prompt-role.gif)
-
-### `.session` - Session management
-Use the following commands to manage sessions in Loki:
-
-| Command             | Description                                                                                 |
-|---------------------|---------------------------------------------------------------------------------------------|
-| `.session`          | Start or switch to a session                                                                |
-| `.empty session`    | Clear all messages for the active session                                                   |
-| `.compress session` | Compress the session messages using the `summarization_prompt` setting in the global config |
-| `.info session`     | Display information about the active session                                                |
-| `.edit session`     | Open the active session's configuration in your preferred text editor                       |
-| `.save session`     | Save the active session to a `session` configuration file                                   |
-| `.exit session`     | Exit the active session                                                                     |
-
-![sessions](./images/sessions/sessions-example.gif)
-
-For more information on sessions and how to use them in Loki, refer to the [sessions documentation](./SESSIONS.md).
-
-### `.agent` - Chat with an AI agent
-Loki lets you build OpenAI GPT-style agents. The following commands let you interact with and manage your agents in 
-Loki:
-
-| Command              | Description                                                |
-|----------------------|------------------------------------------------------------|
-| `.agent`             | Use an agent                                               |
-| `.starter`           | Display and use conversation starters for the active agent |
-| `.edit agent-config` | Open the agent configuration in your preferred text editor |
-| `.info agent`        | Display information about the active agent                 |
-| `.exit agent`        | Leave the active agent                                     |
-
-![agent](./images/agents/sql.gif)
-
-For more information on agents in Loki and how to create them, refer to the [agents documentation](./AGENTS.md).
-
-### `.rag` - Chat with documents
-RAG (Retrieval Augmented Generation) enables you to load documents into the LLM so you can ask questions about it or 
-complete tasks using the documents as additional context.
-
-| Command          | Description                                                                  |
-|------------------|------------------------------------------------------------------------------|
-| `.rag`           | Initialize or access a RAG                                                   |
-| `.edit rag-docs` | Add or remove documents from the active RAG using your preferred text editor |
-| `.rebuild rag`   | Rebuild the active RAG to accommodate document changes                       |
-| `.sources rag`   | Show a works-cited of the sources used in the last query                     |
-| `.info rag`      | Display information about the active RAG                                     |
-| `.exit rag`      | Exit the active RAG                                                          |
-
-![rag](./images/rag/persistent-rag.gif)
-
-For more information about RAG in Loki and how to utilize it, refer to the [rag documentation](./RAG.md).
-
-### `.macro` - Execute a macro
-Macros in Loki are like "scripts" of commands that can be run in isolated environments; that means they do not use any
-active settings and use the same settings they had when written. They are created/executed using the `.macro <name>` 
-command.
-
-![macro](./images/macros/macros-example.gif)
-
-For more information on macros in Loki and how to create them, refer to the [macros documentation](./MACROS.md).
-
-### `.file` - Read files and use them as input
-Loki lets you specify any number of documents that you can load and use as ephemeral RAG to chat with the LLM. To see
-what files or values you can pass to it, simply run the command `.file` with no arguments:
-
-```shell
-openai:gpt-4o)> .file
-Usage: .file <file|dir|url|%%|cmd>... [-- <text>...]
-```
-
-![ephemeral-rag](./images/rag/ephemeral-rag.gif)
-
-For more information about ephemeral RAG, refer to the [ephemeral RAG documentation](./RAG.md#ephemeral-rag).
-
-### `.vault` - Manage the Loki vault
-The Loki vault lets users store sensitive secrets and credentials securely so that there's no plaintext secrets
-anywhere in your configurations.
-
-![vault](./images/vault/vault-demo.gif)
-
-For more information about the Loki vault, refer to the [vault documentation](./VAULT.md).
-
-### `.continue` - Continue the previous response
-When you have a response that exceeds the context length, you can use the `.continue` command to continue the generation
-of the last response.
-
-![continue](./images/repl/continue.gif)
-
-### `.regenerate` - Regenerate the last response
-If ever your response is interrupted, or you want to try generating it again, you can use the `.regenerate` command to do
-this without having to retype your query:
-
-![regenerate](./images/repl/regenerate.gif)
-
-### `.copy` - Copy the last response to your clipboard
-If you're trying to copy the last response (like copying some code), you can use the `.copy` command to copy the entire
-last response to your system clipboard:
-
-![copy](./images/repl/copy.gif)
-
-### `.set` - Adjust runtime settings
-You can use `.set` to adjust select settings at runtime. This is useful when you're experimenting with settings and want
-to know how they'll affect Loki. To persist the changes you make, be sure to update them in the global configuration 
-file.
-
-![set](./images/repl/set.gif)
-
-### `.edit` - Modify configuration files
-The `.edit` command lets you modify configuration files for the current mode of the REPL. It will open the selected 
-configuration in your preferred text editor. It lets you modify the following configurations:
-
-* `.edit config` - Modify the global configuration
-* `.edit role` - Modify the active role's configuration
-* `.edit session` - Modify the active session's configuration
-* `.edit agent-config` - Modify the active agent's configuration
-* `.edit rag-docs` - Add or remove documents from the active RAG
-
-### `.delete` - Delete configurations from Loki
-The `.delete` command allows you to delete entities in Loki without having to directly run `rm -rf` on the configuration 
-directory or file corresponding to the target entity. You can use it to delete the following entities:
-
-* `.delete role` - Delete select roles
-* `.delete session` - Delete select sessions
-* `.delete macro` - Delete select macros
-* `.delete rag` - Delete select RAGs
-* `.delete agent-data` - Delete select agent's configurations and all tools
-
-### `.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.
-
-The following entities are supported:
-
-| Command         | Description                                                 |
-|-----------------|-------------------------------------------------------------|
-| `.info`         | Display system information (identical to the `--info` flag) |
-| `.info role`    | Display information about the active role                   |
-| `.info session` | Display information about the active session                |
-| `.info agent`   | Display information about the active agent                  |
-| `.info rag`     | Display information about the active RAG                    |
-
-### `.exit` - Exit an agent/role/session/rag or the Loki REPL itself
-The `.exit` command is used to move between modes in the Loki REPL.
-
-| Command         | Description             |
-|-----------------|-------------------------|
-| `.exit role`    | Exit the active role    |
-| `.exit session` | Exit the active session |
-| `.exit agent`   | Exit the active agent   |
-| `.exit rag`     | Exit the active RAG     |
-| `.exit`         | Exit the Loki REPL      |
-
-### `.help` - Show the help guide
-Just like with any shell or REPL, you sometimes need a little help and want to know what commands are available to you.
-That's when you use the `.help` command.

docs/ROLES.md

@@ -1,266 +0,0 @@
-# Roles
-When customizing the behavior or LLMs, we use roles to "constrain" the responses or behavior of the LLM to whatever
-purpose we desire. 
-
-Think of them kind of like a baby: That baby can grow up to do anything! Be a resume builder, teacher, engineer, etc.
-
-The only difference is that with roles, we're explicitly telling the LLM what we want it to be. Also: the LLM is already
-grown up so we don't have to wait!
-
-![Role demo](./images/roles/code.gif)
-
-## Quick Links
-<!--toc:start-->
-- [Role Definition](#role-definition)
-  - [Metadata Header](#metadata-header)
-  - [Instructions](#instructions)
-  - [Special Case: Metadata Header Only](#special-case-metadata-header-only)
-- [Prompt Types](#prompt-types)
-  - [Embedded Prompts](#embedded-prompts)
-  - [System Prompts](#system-prompts)
-  - [Few-Shot Prompt](#few-shot-prompt)
-- [Built-In Roles](#built-in-roles)
-<!--toc:end-->
-
----
-
-## Role Definition
-Roles in Loki are Markdown files that live in the `roles` directory of your Loki configuration. Loki configuration 
-locations vary between systems, so you can use the following command to find the location of your roles configuration
-directory:
-
-```shell
-loki --info | grep 'roles_dir' | awk '{print $2}'
-```
-
-All role configuration files have two parts: The metadata header, and the instructions.
-
-**Example:** An expert resume builder role that specializes in helping users build and refine their resumes.
-```markdown
----
-# This is the metadata header
-name: resume-builder
-model: openai:gpt-4o
-temperature: 0.2
-top_p: 0
-enabled_tools: fs_ls,fs_cat
-enabled_mcp_servers: github
----
-<!-- This is the instructions -->
-You are an expert resume builder.
-```
-
-To see a full example configuration for a role, refer to the [example role configuration](../config.role.example.md) 
-file in the root of the repo.
-
-### Metadata Header
-The metadata header in all role configuration files is completely optional. It lets you define role-specific settings
-for each role that make the model work the way you want for your role. This includes things like forcing your role to
-always use a specific model, set of tools, and tailoring the hyperparameters of the model for your role.
-
-The header consists of a YAML-formatted list of settings that let you customize the model behavior for your role. These 
-settings sit between `---` separators in your role configuration so Loki knows they're not part of the instructions you 
-want to feed the model.
-
-The following table lists the available configuration settings and their default values (if undefined):
-
-| Setting               | Default                                                        | Description                                                                                                   |
-|-----------------------|----------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|
-| `name`                | The name of the role markdown file                             | The name of the role                                                                                          |
-| `model`               | Default configured model or currently in-use model (REPL mode) | The preferred model to use with this role                                                                     |
-| `temperature`         | Default `temperature` for the preferred model                  | Controls the creativity and randomness of the model's responses                                               |
-| `top_p`               | Default `top_p` for the preferred model                        | Alternative way to control the model's output diversity, affecting the <br>probability distribution of tokens |
-| `enabled_tools`       | Global setting for `enabled_tools`                             | The tools that this role utilizes                                                                             |
-| `enabled_mcp_servers` | Global setting for `enabled_mcp_servers`                       | The MCP servers that this role utilizes                                                                       |
-| `prompt`              | `null`                                                         | See [Prompt Types](#prompt-types) for detailed usage                                                          | 
-
-### Instructions
-The instructions for a role is what you use to tell the model how you want it to behave. This typically consists of one 
-or two sentences, but can be more. To see some examples, look at the [built-in roles](../assets/roles) to see how they are defined.
-
-**Pro-Tip:** The struggle to create good instructions for a role (or any other kind of instructions for your model) is 
-so common, that Loki comes with a role to help you write instructions for roles! Simply invoke the role to start 
-creating a role with the `create-prompt` role:
-
-```shell
-loki -r create-prompt
-```
-
-### Special Case: Metadata Header Only
-When instructions are defined, the metadata header is optional. However sometimes we want a way to enable specific 
-functions or MCP servers when prompting different models. In this situation, you need only specify the metadata header 
-to just enable these settings as you like.
-
-**Example: Role that enables all filesystem tools**
-`roles/filesystem-functions.md`
-```markdown
----
-enabled_tools: fs_ls,fs_cat,fs_mkdir,fs_patch,fs_write
----
-```
-
-**Example: Role that enables the GitHub MCP server with the ollama:deepseek-r1 model**
-`roles/github.md`
-```markdown
----
-model: ollama:deepseek-r1
-enabled_mcp_servers: github
----
-```
-
-For more examples of this special use case of roles, you can look at the role configuration files for the following
-built-in roles:
-
-* [explain-shell](../assets/roles/explain-shell.md) - Explains cryptic shell commands in natural language
-* [functions](../assets/roles/functions.md) - Enables all available functions (i.e. all globally `visible_functions`)
-* [mcp-servers](../assets/roles/mcp-servers.md) - Enables all available MCP servers
-
-## Special Variables
-Loki has a set of built-in special variables that it will inject into your role's instructions if it finds them in the 
-`{{variable_name}}` syntax. The available special variables are listed below:
-
-| Name            | Description                                               | Example                    |
-|-----------------|-----------------------------------------------------------|----------------------------|
-| `__os__`        | Operating system name                                     | `linux`                    |
-| `__os_family__` | Operating system family                                   | `unix`                     |
-| `__arch__`      | System architecture                                       | `x86_64`                   |
-| `__shell__`     | The current user's default shell                          | `bash`                     |
-| `__locale__`    | The current user's preferred language and region settings | `en-US`                    |
-| `__now__`       | Current timestamp in ISO 8601 format                      | `2025-11-07T10:15:44.268Z` |
-| `__cwd__`       | The current working directory                             | `/tmp`                     |
-
-## Prompt Types
-In Loki, you can also create roles with pre-configured prompts so you can template prompts for your use cases. This is 
-the purpose of the `prompt` field in the role's metadata header. 
-
-There's three types of prompts you can create:
-
-### Embedded Prompts
-Embedded prompts let you create templated prompts for any input given to it. They are ideal for concise, input-driven
-replies from the model. The input that users pass to Loki are injected into your prompt via a `__INPUT__` placeholder in 
-your prompt.
-
-**Example: Role to convert the given input to TOML**
-`roles/convert-to-toml.md`
-```markdown
----
-prompt: convert __INPUT__ to TOML
----
-Convert the given input to TOML format. Exclude any markdown formatting or code blocks and only output code.
-```
-Usage:
-```shell
-$ loki -r json-to-toml '{"test":"hi me"}'
-test = "hi me"
-```
-
-Without the instructions (i.e. the prompt after the metadata header), this role would simply generate the following 
-message for the model:
-
-```json
-[
-  {"role":  "user", "content": "convert {\"test\":\"hi me\"} to TOML"}
-]
-```
-
-### System Prompts
-System prompts let you set the general context of the LLMs behavior. This is no different than other system prompts you
-define in ChatGPT, Claude, Open WebUI, etc.
-
-They are essentially Embedded Prompts without an `__INPUT__` placeholder.
-
-**Example: Role to convert all input words to emoji**
-`roles/emoji.md`
-```markdown
----
-prompt: convert my words to emojis
----
-Convert all given input words into emojis
-```
-Usage:
-```shell
-$ loki -r emoji music joy
-🎵 😊
-```
-
-Without the instructions (i.e. the prompt after the metadata header), this role would simply generate the following 
-messages for the model:
-
-```json
-[
-  {"role": "system", "content":  "convert my words to emojis"},
-  {"role": "user", "content":  "music joy"}
-]
-```
-
-### Few-Shot Prompt
-[Few-Shot prompting](https://www.promptingguide.ai/techniques/fewshot) is a technique to enable in-context learning for LLMs by providing examples in the prompt to steer 
-the model to better performance. In Loki, this is done as an extension of System Prompts.
-
-**Example: Role to output code only**
-`roles/code-generator.md`
-~~~markdown
----
-prompt: |-
-    Output code only without comments or explanations.
-    ### INPUT:
-    async sleep in js
-    ### OUTPUT:
-    ```javascript
-    async function timeout(ms) {
-      return new Promise(resolve => setTimeout(resolve, ms));
-    }
-    ```
----
-Output code only in response to the user's request
-~~~
-Usage:
-~~~shell
-$ loki -r code-generator python add two numbers
-```python
-# Function to add two numbers
-def add_numbers(num1, num2):
-    return num1 + num2
-
-# Example usage
-number1 = 5
-number2 = 7
-
-result = add_numbers(number1, number2)
-print(f"The sum of {number1} and {number2} is {result}.")
-```
-~~~
-
-Without the instructions (i.e. the prompt after the metadata header), this role would simply generate the following
-messages for the model:
-
-```json
-[
-  {"role": "system", "content": "Output code only without comments or explanations."},
-  {"role": "user", "content": "async sleep in js"},
-  {"role": "assistant", "content": "```javascript\nasync function timeout(ms) {\n  return new Promise(resolve => setTimeout(resolve, ms));\n}\n```"},
-  {"role": "user", "content": "python add two numbers"}
-]
-```
-
-## Built-In Roles
-Loki comes packaged with some useful built-in roles. These are also good examples if you're looking for more examples on
-how to make your own roles, so be sure to check out the [built-in role definitions](../assets/roles) if you're looking 
-for more examples.
-
-* `code`: Generates code (used by `loki -c`)
-* `create-prompt`: Creates a prompt based on the user's input
-* `create-title`: Creates 3-6 word titles based on the user's input
-* `explain-shell`: Explains shell commands
-* `functions`: Enable all globally-visible functions
-* `github`: Interact with GitHub using natural language
-* `mcp-servers`: Enables all MCP servers
-* `repo-analyzer`: Ask questions about the code repository in the current working directory
-* `shell`: Convert natural language into shell commands (used by `loki -e`)
-* `slack`: Interact with Slack using natural language
-
-## Temporary Roles
-Loki also enables you to create temporary roles that will be discarded once you're finished with them. This is done via 
-the `.prompt/--prompt` command:
-
-![prompt role](./images/roles/prompt-role.gif)

docs/SESSIONS.md

@@ -1,44 +0,0 @@
-# Sessions
-By default, Loki does not send back all previous messages in a conversation to the model. This means that each time you 
-query a model, it's essentially a one-off. However, Loki does support chat-like conversations with LLMs via its 
-`sessions` mechanism.
-
-Sessions in Loki enable the familiar conversational interactions with LLMs. This means you can reference previous 
-answers and ask follow-up questions and the model will know what you're referring to.
-
-Sessions can be temporary, or can be saved so you can continue conversations at a later time.
-
-Saved sessions are stored in the `sessions` subdirectory of the Loki configuration directory. The location of the 
-`sessions` directory varies by system, so you can use the following command to find the `sessions` directory if you need 
-it:
-
-```shell
-loki --info | grep 'sessions_dir' | awk '{print $2}'
-```
-
-## Usage
-When you use a session in Loki, you can either persist it or discard it once you're done. Sessions you discard are then
-just considered 'temporary' sessions.
-
-![Persistent Session Example](./images/sessions/sessions-example.gif)
-
-Sessions you persist and then load again later will inherit the same configuration as was used during the last usage of 
-that session. That is to say, if you had certain tools or MCP servers enabled when you were last in that session, they 
-will be available again when you continue that session.
-
-## Configuration
-Session behavior can be configured from the global Loki configuration file. The location of this file varies between 
-systems so you can use the following command to locate it on your system:
-
-```shell
-loki --info | grep 'config_file' | awk '{print $2}'
-```
-
-The following settings are available to customize the default behavior of sessions globally:
-
-| Setting                  | Description                                                                                                                                                                                                                                                                                                                                                            |
-|--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `save_session`           | Controls the persistence of the session. <br><ul><li>If `true`, then any time you're in a session, changes will auto-save unless explicitly defined otherwise.</li> <li>If `false`, then any time you're in a session, changes will not auto-save unless explicitly specified otherwise.</li><li>If `null`, Loki will always prompt the user for what to do.</li></ul> |
-| `compression_threshold`  | Defines the token count threshold at which Loki will compress the session to save on the context length                                                                                                                                                                                                                                                                |
-| `summarization_prompt`   | This is the prompt that is used to compress the session up to a given point when compression is triggered                                                                                                                                                                                                                                                              |
-| `summary_context_prompt` | This is the prompt that's used to add the summarized conversation generated by the `summarization_prompt` as context to the model                                                                                                                                                                                                                                      |

docs/SHELL-INTEGRATIONS.md

@@ -1,104 +0,0 @@
-# Loki Shell Integrations
-Loki supports the following integrations with a handful of shell environments to enhance user experience and streamline workflows.
-
-## Tab Completions
-### Dynamic
-Dynamic tab completions are supported by Loki to assist users in quickly completing commands, options, and arguments.
-You can enable it by using the corresponding command for your shell. To enable dynamic tab completions for every
-shell session (i.e. persistently), add the corresponding command to your shell's configuration file as indicated:
-
-```shell
-# Bash
-# (add to: `~/.bashrc`)
-source <(COMPLETE=bash loki) 
-
-# Zsh
-# (add to: `~/.zshrc`)
-source <(COMPLETE=zsh loki)
-
-# Fish
-# (add to: `~/.config/fish/config.fish`)
-source <(COMPLETE=fish loki | psub)
-
-# Elvish
-# (add to: `~/.elvish/rc.elv`)
-eval (E:COMPLETE=elvish loki | slurp)
-
-# PowerShell
-# (add to: `$PROFILE`)
-$env:COMPLETE = "powershell"
-loki | Out-String | Invoke-Expression
-```
-
-At the time of writing, `nushell` is not yet fully supported for dynamic tab completions due to limitations
-in the [`clap`](https://crates.io/crates/clap) crate. However, `nushell` support is being actively developed, and will
-be added in a future release.
-
-Progress on this feature can be tracked in the following issue: [Clap Issue #5840](https://github.com/clap-rs/clap/issues/5840).
-
-### Static
-Static tab completions (i.e. pre-generated completion scripts that are not context aware) can also be generated using the
-`--completions` flag. You can enable static tab completions by using the corresponding commands for your shell. These commands
-will enable them for every shell session (i.e. persistently):
-
-```shell
-# Bash
-echo 'source <(loki --completions bash)' >> ~/.bashrc
-
-# Zsh
-echo 'source <(loki --completions zsh)' >> ~/.zshrc
-
-# Fish
-echo 'loki --completions fish | source' >> ~/.config/fish/config.fish
-
-# Elvish
-echo 'eval (loki --completions elvish | slurp)' >> ~/.elvish/rc.elv
-
-# Nushell
-[[ -d ~/.config/nushell/completions ]] || mkdir -p ~/.config/nushell/completions
-loki --completions nushell | save -f ~/.config/nushell/completions/loki.nu
-echo 'use ~/.config/nushell/completions/cli.nu *' >> ~/.config/nushell/config.nu
-
-# PowerShell
-Add-content $PROFILE "loki --completions powershell | Out-String | Invoke-Expression"
-```
-
-## Shell Assistant
-Loki has an `-e,--execute` flag that allows users to run natural language commands directly from the CLI. It accepts
-natural language input and translates it into executable shell commands.
-
-![Shell Assistant Demo](./images/shell_integrations/assistant.gif)
-
-## Intelligent Command Completions
-Loki also provides shell scripts that bind `Alt-e` to `loki -e "<current command line>"`, allowing users to generate
-commands from natural text directly without invoking the CLI.
-
-For example:
-
-```shell
-$ find all typescript files with more than 100 lines<Alt-e>
-# Gets replaced with
-$ find . -name '*.ts' -type f -exec awk 'NR>100{exit 1}' {} \; -print
-```
-
-To use the CLI helper, add the content of the appropriate integration script for your shell to your shell configuration file:
-* [Bash Integration](../scripts/shell-integration/integration.bash) (add to: `~/.bashrc`)
-* [Zsh Integration](../scripts/shell-integration/integration.zsh) (add to: `~/.zshrc`)
-* [Elvish Integration](../scripts/shell-integration/integration.elv) (add to: `~/.elvish/rc.elv`)
-* [Fish Integration](../scripts/shell-integration/integration.fish) (add to: `~/.config/fish/config.fish`)
-* [Nushell Integration](../scripts/shell-integration/integration.nu) (add to: `~/.config/nushell/config.nu`)
-* [PowerShell Integration](../scripts/shell-integration/integration.ps1) (add to: `$PROFILE`)
-
-## Explain Commands
-In addition to the Shell Assistant, Loki has a built-in role that explains shell commands to you to decipher their 
-language. So if Loki generates a command that you're unsure of what it does, simply pass it to the `explain-shell` role:
-
-![Explain Shell Role](./images/shell_integrations/explain-shell.png)
-
-## Code Generation
-Users can also directly generate code snippets from natural language prompts using the `-c,--code` flag.
-
-![Code Generation Demo](./images/shell_integrations/code-generation.gif)
-
-**Pro Tip:** Pipe the output of the code generation directly into `tee` to ensure the generated code is properly extracted
-from any generated Markdown (i.e. remove any triple backticks).

docs/THEMES.md

@@ -1,71 +0,0 @@
-# Theming Loki
-Loki supports customizing the theme via a `.tmTheme` file.
-
-## Setup
-To install a custom theme, download the `.tmTheme` file to the Loki configuration directory and name it `dark.tmTheme`
-or `light.tmTheme`. The location of the Loki configuration directory varies between systems, so you can use the 
-following command to locate it on your system:
-
-```shell
-loki --info | grep 'config_dir' | awk '{print $2}'
-```
-
-## Themes
-### 1337-Scheme
-https://raw.githubusercontent.com/MarkMichos/1337-Scheme/ca6a329cfda8307449d405b70f8fab34b8fd23b5/1337.tmTheme
-![1337-scheme](./images/themes/1337-scheme.png)
-
-### Coldark
-https://raw.githubusercontent.com/ArmandPhilippot/coldark-bat/e44750b2a9629dd12d8ed3ad9fd50c77232170b9/Coldark-Dark.tmTheme
-![coldark](./images/themes/coldark.png)
-
-### Dracula
-https://raw.githubusercontent.com/dracula/sublime/c2de0acf5af67042393cf70de68013153c043656/Dracula.tmTheme
-![dracula](./images/themes/dracula.png)
-
-### GitHub
-https://raw.githubusercontent.com/AlexanderEkdahl/github-sublime-theme/508740b2430c3c3a9e785fc93ee1d7c6f233af53/GitHub.tmTheme
-![github](./images/themes/github.png)
-
-### gruvbox
-#### Dark
-https://raw.githubusercontent.com/subnut/gruvbox-tmTheme/64c47250e54298b91e2cf8d401320009aba9f991/gruvbox-dark.tmTheme
-![gruvbox-dark](./images/themes/gruvbox-dark.png)
-
-#### Light
-https://raw.githubusercontent.com/subnut/gruvbox-tmTheme/64c47250e54298b91e2cf8d401320009aba9f991/gruvbox-light.tmTheme
-![gruvbox-light](./images/themes/gruvbox-light.png)
-
-### OneHalf
-#### Dark
-https://raw.githubusercontent.com/sonph/onehalf/141c775ace6b71992305f144a8ab68e9a8ca4a25/sublimetext/OneHalfDark.tmTheme
-![onehalf-dark](./images/themes/onehalf-dark.png)
-
-#### Light
-https://raw.githubusercontent.com/sonph/onehalf/141c775ace6b71992305f144a8ab68e9a8ca4a25/sublimetext/OneHalfLight.tmTheme
-![onehalf-light](./images/themes/onehalf-light.png)
-
-### Solarized
-#### Dark
-https://raw.githubusercontent.com/braver/Solarized/87e01090cggjf5fb821a234265b3138426ae84900e7/Solarized%20(dark).tmTheme
-![solarized-dark](./images/themes/solarized-dark.png)
-
-#### Light
-https://raw.githubusercontent.com/braver/Solarized/87e01090cf5fb821a234265b3138426ae84900e7/Solarized%20(light).tmTheme
-![solarized-light](./images/themes/solarized-light.png)
-
-### Sublime Snazzy
-https://raw.githubusercontent.com/greggb/sublime-snazzy/70343201f1d7539adbba3c79e2fe81c2559a0431/Sublime%20Snazzy.tmTheme
-![sublime-snazzy](./images/themes/sublime-snazzy.png)
-
-### TwoDark
-https://raw.githubusercontent.com/erremauro/TwoDark/8e0f6fa5b59d196658a22288f519fd8320de4c87/TwoDark.tmTheme
-![twodark](./images/themes/twodark.png)
-
-### Visual Studio Dark+
-https://raw.githubusercontent.com/vidann1/visual-studio-dark-plus/01ee1e8e0dc578f3b4e8c0dbb6aa0279b4a26a40/Visual%20Studio%20Dark%2B.tmTheme
-![visual-studio-dark-plus](./images/themes/visual-studio-dark-plus.png)
-
-### Zenburn
-https://raw.githubusercontent.com/colinta/zenburn/86d4ee7a1f884851a1d21d66249687f527fced32/zenburn.tmTheme
-![zenburn](./images/themes/zenburn.png)

docs/VAULT.md

@@ -1,161 +0,0 @@
-# The Loki Vault
-The Loki vault lets users store sensitive secrets and credentials securely so that there's no plaintext secrets
-anywhere in your configurations. 
-
-It's based on the [G-Man library](https://github.com/Dark-Alex-17/gman) (which also comes in a binary format) which
-functions as a universal secret management tool.
-
-![Vault Demo](./images/vault/vault-demo.gif)
-
-## Quick Links
-<!--toc:start-->
-- [Usage](#usage)
-  - [CLI Usage](#cli-usage)
-  - [REPL Usage](#repl-usage)
-- [Motivation](#motivation)
-- [How it works](#how-it-works)
-- [Supported Files](#supported-files)
-- [Environment Variable Secret Injection in Agents](#environment-variable-secret-injection-in-agents)
-<!--toc:end-->
-
----
-
-## Usage
-The Loki vault can be used in one of two ways: via the CLI or via the REPL for interactive usage.
-
-### CLI Usage
-The vault is utilized from the CLI with the following flags:
-
-```bash
---add-secret <SECRET_NAME>       Add a secret to the Loki vault
---get-secret <SECRET_NAME>       Decrypt a secret from the Loki vault and print the plaintext
---update-secret <SECRET_NAME>    Update an existing secret in the Loki vault
---delete-secret <SECRET_NAME>    Delete a secret from the Loki vault
---list-secrets                   List all secrets stored in the Loki vault
-```
-(The above is also documented in `loki --help`)
-
-Loki will guide you through manipulating your secrets to make usage easier.
-
-### REPL Usage
-The vault can be access from within the Loki REPL using the `.vault` commands:
-
-![Loki Vault REPL](./images/vault/vault-repl.png)
-![Loki Vault REPL Commands](./images/vault/vault-repl-commands.png)
-
-The manipulation of your vault is guided in the same way as the CLI usage, ensuring ease of use.
-
-## Motivation
-Loki is intended to be highly configurable and adaptable to many different use cases. This means that users of Loki
-should be able to share configurations for agents, tools, roles, etc. with other users or even entire teams.
-
-My objective is to encourage this, and to make it so that users can easily version their configurations using version
-control. Good VCS hygiene dictates that one *never* commits secrets or sensitive information to a repository.
-
-Since a number of files and configurations in Loki may contain sensitive information, the vault exists to solve this problem.
-
-Users can either share the vault password with a team, making it so a single configuration can be pulled from VCS and used
-by said team. Alternatively, each user can maintain their own vault password and expect other users to replace secret values
-with their user-specific secrets.
-
-## How it works
-When you first start Loki, if you don't already have a vault password file, it will prompt you to create one. This file
-houses the password that is used to encrypt and decrypt secrets within Loki. This file exists so that you are not prompted
-for a password every time Loki attempts to decrypt a secret.
-
-When you encrypt a secret, it uses the local provider for `gman` to securely store those secrets in the Loki vault file.
-This file is typically located at your Loki configuration directory under `vault.yml`. If you open this file, you'll see a
-bunch of gibberish. This is because all secrets are encrypted using the password you provided, meaning only you can decrypt them.
-
-Secrets are specified in Loki configurations using the same variable templating as the [Jinja templating engine](https://jinja.palletsprojects.com/en/stable/):
-
-```
-{{some_variable}}
-```
-
-So whenever you want Loki to use a secret from the vault, you simply specify the secret name in this format in the applicable
-file.
-
-**Example:**
-Suppose my vault has a secret called `GITHUB_TOKEN` in it, and I want to use that in the MCP configuration. Then, I simply replace
-the expected value in my `mcp.json` with the templated secret:
-
-```json
-{
-  "mcpServers": {
-    "atlassian": {
-      "command": "npx",
-      "args": ["-y", "mcp-remote", "https://mcp.atlassian.com/v1/sse"]
-    },
-    "github": {
-      "command": "docker",
-      "args": [
-        "run",
-        "-i",
-        "--rm",
-        "-e",
-        "GITHUB_PERSONAL_ACCESS_TOKEN",
-        "ghcr.io/github/github-mcp-server"
-      ],
-      "env": {
-        "GITHUB_PERSONAL_ACCESS_TOKEN": "{{GITHUB_TOKEN}}"
-      }
-    }
-  }
-}
-```
-
-At runtime, Loki will detect the templated secret and replace it with the decrypted value from the vault before executing.
-
-## Supported Files
-At the time of writing, the following files support Loki secret injection:
-
-| File Type               | Description                       | Limitations                                                                                                                               |
-|-------------------------|-----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|
-| `config.yaml`           | The main Loki configuration file  | Cannot use secret injection on the `vault_password_file` field                                                                            |
-| `functions/mcp.json`    | The MCP server configuration file |                                                                                                                                           |
-| `<agent>/tools.<py/sh>` | Tool files for agents             | Specific configuration and only supported for Agents, not all global tools ([see below](#environment-variable-secret-injection-in-agents) |
-
-
-Note that all paths are relative to the Loki configuration directory. The directory varies by system, so you can find yours by
-running
-
-```shell
-loki --info | grep config_dir | awk '{print $2}'
-```
-
-## Environment Variable Secret Injection in Agents
-Secrets from the Loki vault can be injected into agent `tools.sh/tools.py` as environment variables. This is done as 
-follows:
-
-1. Ensure a secret named `MY_USERNAME` is in your Loki vault.
-2. Set the name of the secret as the default value for a variable
-   `<agent>/config.yaml`
-   ```yaml
-   name: Username
-   description: An AI agent that demonstrates agent capabilities
-   instructions: |
-     You are a AI agent designed to demonstrate agent capabilities.
-   variables:
-     - name: username
-       description: Your user name
-       # Configure the secret you want to inject using the same templating mentioned above; i.e. wrap the 
-       # case-sensitive name in '{{}}'
-       default: '{{MY_USERNAME}}'
-   ```
-3. Reference the variable in your `<agent>/tools.<py/sh>` file using the familiar variable injection name; that is, 
-   since the name of the variable is `username`, the environment variable that will be provided to the tool call will
-   be named `LLM_AGENT_VAR_USERNAME`
-   `tools.sh`
-   ```bash
-   #!/usr/bin/env bash
-   # @env LLM_OUTPUT=/dev/stdout The output path
-   
-   # @cmd Get my username
-   get_my_username() {
-      echo "$LLM_AGENT_VAR_USERNAME" >> "$LLM_OUTPUT"        
-   }
-   ```
-
-For more information about variable usage within agents, refer to the [Variables section](./AGENTS.md#user-defined-variables) of the [Agents README](./AGENTS.md)
-

docs/clients/CLIENTS.md

@@ -1,92 +0,0 @@
-# Model Clients
-
-Loki supports a large number of model providers (referred to as `clients` since Loki is a client of these providers). In 
-order to use them, you must configure each one in the `clients` array in the global Loki configuration file.
-
-The location of the global Loki configuration file varies between systems, so you can use the following command to 
-locate your configuration file:
-
-```shell
-loki --info | grep 'config_file' | awk '{print $2}'
-```
-
-## Quick Links
-<!--toc:start-->
-- [Supported Clients](#supported-clients)
-- [Client Configuration](#client-configuration)
-- [Extra Settings](#extra-settings)
-<!--toc:end-->
-
----
-
-## Supported Clients
-Loki supports the following model client types:
-
-* Azure AI Foundry
-* AWS Bedrock
-* Anthropic Claude
-* Cohere
-* Google Gemini
-* OpenAI
-* OpenAI-Compatible
-* GCP Vertex AI
-
-In addition to the settings detailed below, each client may have additional settings specific to the provider. Check the
-[example global configuration file](../../config.example.yaml) to verify that your client has all the necessary fields
-defined.
-
-## Client Configuration
-Each client in Loki has the same configuration settings available to them, with only special authentication fields added
-for specific clients as necessary. They are each placed under the `clients` array in your global configuration file:
-
-```yaml
-clients:
-  - name: client1
-    # ... client configuration ...
-  - name: client2
-    # ... client configuration ...
-```
-
-### Metadata
-The client metadata uniquely identifies the client in Loki so you can reference it across your configurations. The 
-available settings are listed below:
-
-| Setting  | Description                                                                                   |
-|----------|-----------------------------------------------------------------------------------------------|
-| `name`   | The name of the client (e.g. `openai`, `gemini`, etc.)                                        |
-| `models` | See the [model settings](#model-settings) documentation below                                 |
-| `patch`  | See the [client patch configuration](./PATCHES.md#client-configuration-patches) documentation |
-| `extra`  | See the [extra settings](#extra-settings) documentation below                                 |
-
-Be sure to also check provider-specific configurations for any extra fields that are added for authentication purposes.
-
-### Model Settings
-The `models` array lists the available models from the model client. Each one has the following settings:
-
-| Setting                     | Required | Model Type  | Description                                                                                                                                                                                                                                   |
-|-----------------------------|----------|-------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `name`                      | *        | `all`       | The name of the model                                                                                                                                                                                                                         |
-| `real_name`                 |          | `all`       | You can define model aliases via the `name` field. However, Loki still needs to know the real name <br>of the model so it can query it. For example: If you have `name: gpt-alias`, then you must <br>also define `real_name: gpt-oss:latest` |
-| `type`                      | *        | `all`       | The type of model. Loki supports only 3 types of models: <ul><li>`chat`</li><li>`embedding`</li><li>`reranker`</li></ul>                                                                                                                      |
-| `input_price`               |          | `all`       | The cost in USD per 1M tokens for each input sequence; Loki will keep track of usage costs if this is defined                                                                                                                                 |
-| `output_price`              |          | `all`       | The cost in USD per 1M tokens of the model output; Loki will keep track of usage costs if this is defined                                                                                                                                     |
-| `patch`                     |          | `all`       | See the [model-specific patch configuration](./PATCHES.md#model-specific-patches) documentation                                                                                                                                               |
-| `max_input_tokens`          |          | `all`       | The maximum number of input tokens for the model                                                                                                                                                                                              |
-| `max_output_tokens`         |          | `chat`      | The maximum number of output tokens for the model                                                                                                                                                                                             |
-| `require_max_tokens`        |          | `chat`      | Whether to enforce the `max_output_tokens` constraint.                                                                                                                                                                                        |
-| `supports_vision`           |          | `chat`      | Indicates if the model supports multimodal queries that would require vision (i.e. image recognition)                                                                                                                                         |
-| `supports_function_calling` |          | `chat`      | Indicates if the model supports function calling                                                                                                                                                                                              |
-| `no_stream`                 |          | `chat`      | Enable or disable streaming API responses                                                                                                                                                                                                     |
-| `no_system_message`         |          | `chat`      | Controls whether the model supports system messages                                                                                                                                                                                           |
-| `system_prompt_prefix`      |          | `chat`      | An additional prefix prompt to add to all system prompts to ensure consistent behavior across all interactions                                                                                                                                |
-| `max_tokens_per_chunk`      |          | `embedding` | The maximum chunk size supported by the embedding model                                                                                                                                                                                       |
-| `default_chunk_size`        |          | `embedding` | The default chunk size to use with the given model                                                                                                                                                                                            |
-| `max_batch_size`            |          | `embedding` | The maximum batch size that the given embedding model supports                                                                                                                                                                                |
-
-## Extra Settings
-Loki also lets you customize some extra settings for interacting with APIs:
-
-| Setting           | Description                                           |
-|-------------------|-------------------------------------------------------|
-| `proxy`           | Set a proxy to use                                    |
-| `connect_timeout` | Set the timeout in seconds for connections to the API |

docs/clients/PATCHES.md

@@ -1,368 +0,0 @@
-# Request Patching in Loki
-Loki provides two mechanisms for modifying API requests sent to LLM providers: **Model-Specific Patches** and 
-**Client Configuration Patches**. These allow you to customize request parameters, headers, and URLs to work around 
-provider quirks or add custom behavior.
-
-## Quick Links
-- [Model-Specific Patches](#model-specific-patches)
-- [Client Configuration Patches](#client-configuration-patches)
-- [Comparison](#comparison)
-- [Common Use Cases](#common-use-cases)
-- [Environment Variable Patches](#environment-variable-patches)
-- [Tips](#tips)
-- [Debugging Patches](#debugging-patches)
-
----
-
-## Model-Specific Patches
-
-### Overview
-Model-specific patches are applied **unconditionally** to a single model. They are useful for handling model-specific 
-quirks or requirements.
-
-### When to Use
-- A specific model requires certain parameters to be set or removed
-- A model needs different default values than other models from the same provider
-- You need to add special configuration for one model only
-
-### Structure
-
-```yaml
-models:
-  - name: model-name
-    type: chat
-    # ... other model properties ...
-    patch:
-      url: "https://custom-endpoint.com"   # Optional: override the API endpoint
-      body:                                # Optional: modify request body
-        <parameter>: <value>               # Add or modify parameters
-        <parameter>: null                  # Remove parameters (set to null)
-      headers:                             # Optional: modify request headers
-        <header-name>: <value>             # Add or modify headers
-        <header-name>: null                # Remove headers (set to null)
-```
-
-### Examples
-
-#### Example 1: Removing Parameters
-OpenAI's o1 models don't support `temperature`, `top_p`, or `max_tokens` parameters. The `patch` removes them:
-
-```yaml
-- name: o4-mini
-  type: chat
-  max_input_tokens: 200000
-  max_output_tokens: 100000
-  supports_function_calling: true
-  patch:
-    body:
-      max_tokens: null      # Remove max_tokens from request
-      temperature: null     # Remove temperature from request
-      top_p: null           # Remove top_p from request
-```
-
-#### Example 2: Setting Required Parameters
-Some models require specific parameters to be set:
-
-```yaml
-- name: o4-mini-high
-  type: chat
-  patch:
-    body:
-      reasoning_effort: high  # Always set reasoning_effort to "high"
-      max_tokens: null
-      temperature: null
-```
-
-#### Example 3: Custom Endpoint
-If a model needs a different API endpoint:
-
-```yaml
-- name: custom-model
-  type: chat
-  patch:
-    url: "https://special-endpoint.example.com/v1/chat"
-```
-
-#### Example 4: Adding Headers
-Add authentication or custom headers:
-
-```yaml
-- name: special-model
-  type: chat
-  patch:
-    headers:
-      X-Custom-Header: "special-value"
-      X-API-Version: "2024-01"
-```
-
-### How It Works
-1. When you use a model, Loki loads its configuration
-2. If the model has a `patch` field, it's **always applied** to every request
-3. The patch modifies the request URL, body, or headers before sending to the API
-4. Parameters set to `null` are **removed** from the request
-
----
-
-## Client Configuration Patches
-
-### Overview
-Client configuration patches allow you to apply customizations to **multiple models** based on 
-**regex pattern matching**. They're defined in your `config.yaml` file and can target specific API types (`chat`, 
-`embeddings`, or `rerank`).
-
-### When to Use
-- You want to apply the same settings to multiple models from a provider
-- You need different configurations for different groups of models
-- You want to override the default client model settings
-- You need environment-specific customizations
-
-### Structure
-
-```yaml
-clients:
-  - type: <client>                      # e.g., gemini, openai, claude
-    # ... client configuration ...
-    patch:
-      chat_completions:                 # For chat models
-        '<regex-pattern>':              # Regex to match model names
-          url: "..."                    # Optional: override endpoint
-          body:                         # Optional: modify request body
-            <parameter>: <value>
-          headers:                      # Optional: modify headers
-            <header>: <value>
-      embeddings:                       # For embedding models
-        '<regex-pattern>':
-          # ... same structure ...
-      rerank:                           # For reranker models
-        '<regex-pattern>':
-          # ... same structure ...
-```
-
-### Pattern Matching
-- Patterns are **regular expressions** that match against the model name
-- Use `.*` to match all models
-- Use specific patterns like `gpt-4.*` to match model families
-- Use `model1|model2` to match multiple specific models
-
-### Examples
-
-#### Example 1: Disable Safety Filters for Gemini Models
-Apply to all Gemini chat models:
-
-```yaml
-clients:
-  - type: gemini
-    api_key: "{{GEMINI_API_KEY}}"
-    patch:
-      chat_completions:
-        '.*':  # Matches all Gemini models
-          body:
-            safetySettings:
-              - category: HARM_CATEGORY_HARASSMENT
-                threshold: BLOCK_NONE
-              - category: HARM_CATEGORY_HATE_SPEECH
-                threshold: BLOCK_NONE
-              - category: HARM_CATEGORY_SEXUALLY_EXPLICIT
-                threshold: BLOCK_NONE
-              - category: HARM_CATEGORY_DANGEROUS_CONTENT
-                threshold: BLOCK_NONE
-```
-
-#### Example 2: Apply Settings to Specific Model Family
-Only apply to GPT-4 models (not GPT-3.5):
-
-```yaml
-clients:
-  - type: openai
-    api_key: "{{OPENAI_API_KEY}}"
-    patch:
-      chat_completions:
-        'gpt-4.*':  # Matches gpt-4, gpt-4-turbo, gpt-4o, etc.
-          body:
-            frequency_penalty: 0.2
-            presence_penalty: 0.1
-```
-
-#### Example 3: Different Settings for Different Models
-Apply different patches based on model name:
-
-```yaml
-clients:
-  - type: openai
-    api_key: "{{OPENAI_API_KEY}}"
-    patch:
-      chat_completions:
-        'gpt-4o':  # Specific model
-          body:
-            temperature: 0.7
-        'gpt-3.5.*':  # Model family
-          body:
-            temperature: 0.9
-            max_tokens: 2000
-```
-
-#### Example 4: Modify Embedding Requests
-Apply to embedding models:
-
-```yaml
-clients:
-  - type: openai
-    api_key: "{{OPENAI_API_KEY}}"
-    patch:
-      embeddings:
-        'text-embedding-.*':  # All text-embedding models
-          body:
-            dimensions: 1536
-            encoding_format: "float"
-```
-
-#### Example 5: Custom Headers for Specific Models
-Add headers only for certain models:
-
-```yaml
-clients:
-  - type: openai-compatible
-    api_base: "https://api.example.com/v1"
-    patch:
-      chat_completions:
-        'custom-model-.*':
-          headers:
-            X-Custom-Auth: "bearer-token"
-            X-Model-Version: "latest"
-```
-
-#### Example 6: Override Endpoint for Specific Models
-Use different endpoints for different model groups:
-
-```yaml
-clients:
-  - type: openai-compatible
-    api_base: "https://default-endpoint.com/v1"
-    patch:
-      chat_completions:
-        'premium-.*':  # Premium models use different endpoint
-          url: "https://premium-endpoint.com/v1/chat/completions"
-```
-
-### How It Works
-1. When making a request, Loki checks if the client has a `patch` configuration
-2. It looks at the appropriate API type (`chat_completions`, `embeddings`, or `rerank`)
-3. For each pattern in that section, it checks if the regex matches the model name
-4. If a match is found, that patch is applied to the request
-5. Only the **first matching pattern** is applied (patterns are processed in order)
-
----
-
-## Comparison
-
-| Feature               | Model-Specific Patch  | Client Configuration Patch          |
-|-----------------------|-----------------------|-------------------------------------|
-| **Scope**             | Single model only     | Multiple models via regex           |
-| **Matching**          | Exact model name      | Regular expression pattern          |
-| **Application**       | Always applied        | Only if pattern matches             |
-| **API Type**          | All APIs              | Separate for chat/embeddings/rerank |
-| **Override**          | Cannot be overridden  | Can override model patch            |
-| **Use Case**          | Model-specific quirks | User preferences & customization    |
-| **Application Order** | Applied first         | Applied second (can override)       |
-
-### Patch Application Order
-When both patches are present, they're applied in this order:
-
-1. **Model-Specific Patch**
-2. **Client Configuration Patch**
-
-This means client configuration patches can override model-specific patches if they modify the same parameters.
-
-## Common Use Cases
-
-### Removing Unsupported Parameters
-Some models don't support standard parameters like `temperature` or `max_tokens`:
-
-**Model Patch**:
-```yaml
-patch:
-  body:
-    temperature: null
-    max_tokens: null
-```
-
-### Adding Provider-Specific Parameters
-Providers often have unique parameters:
-
-**Client Patch**:
-```yaml
-patch:
-  chat_completions:
-    '.*':
-      body:
-        safetySettings: [...]        # Gemini
-        thinking_budget: 10000       # DeepSeek
-        response_format:             # OpenAI
-          type: json_object
-```
-
-### Changing Endpoints
-Use custom or regional endpoints:
-
-**Client Patch**:
-```yaml
-patch:
-  chat_completions:
-    '.*':
-      url: "https://eu-endpoint.example.com/v1/chat"
-```
-
-### Setting Default Values
-Provide defaults for specific models or model families:
-
-**Client Patch**:
-```yaml
-patch:
-  chat_completions:
-    'claude-3-.*':
-      body:
-        max_tokens: 4096
-        temperature: 0.7
-```
-
-### Custom Authentication
-Add special authentication headers:
-
-**Client Patch**:
-```yaml
-patch:
-  chat_completions:
-    '.*':
-      headers:
-        Authorization: "Bearer {{custom_token}}"
-        X-Organization-ID: "org-123"
-```
-
-## Environment Variable Patches
-You can also apply patches via environment variables for temporary overrides:
-
-```bash
-export LLM_PATCH_OPENAI_CHAT_COMPLETIONS='{"gpt-4.*":{"body":{"temperature":0.5}}}'
-```
-
-This takes precedence over client configuration patches but not model-specific patches.
-
-## Tips
-1. **Use model patches** for permanent, model-specific requirements
-2. **Use client patches** for personal preferences or environment-specific settings
-3. **Test regex patterns** carefully
-4. **Set to `null`** to remove parameters, don't just omit them
-5. **Check each model provider's docs** for available parameters and their formats
-6. **Be specific** with patterns to avoid unintended matches
-7. **Remember order matters** - first matching pattern wins for client patches
-8. **Patches merge** - both types can be applied, with client patches overriding model patches
-
-## Debugging Patches
-To see what request is actually being sent, enable debug logging:
-
-```bash
-export RUST_LOG=loki=debug
-loki "your prompt here"
-```
-
-This will show the final request body after all patches are applied.

docs/function-calling/BASH-PROMPT-HELPERS.md

@@ -1,275 +0,0 @@
-# Bash Prompt Helpers
-
-When creating bash based tools, it's often helpful to prompt the user for input or confirmation.
-
-Loki comes pre-packaged with a handful of prompt helpers for your bash-based tools. These helpers
-can be used to prompt the user for various types of input, such as yes/no confirmations,
-text input, and selections from a list.
-
-The utility script is located at `functions/utils/prompt-utils.sh` within your Loki `functions` directory.
-
-The Loki `functions` directory varies between machines, so you can find its location on your system by running the following command in your terminal:
-
-```shell
-loki --info | grep functions_dir | awk '{print $2}'
-```
-
-## Quick Links
-<!--toc:start-->
-- [Import The Prompt Utils Into Your Tools Script](#import-the-prompt-utils-into-your-tools-script)
-- [Included Utility Functions](#included-utility-functions)
-  - [input](#input)
-  - [confirm](#confirm)
-  - [list](#list)
-  - [checkbox](#checkbox)
-  - [password](#password)
-  - [editor](#editor)
-  - [with_validate](#with_validate)
-  - [validate_present](#validate_present)
-  - [detect_os](#detect_os)
-  - [get_opener](#get_opener)
-  - [open_link](#open_link)
-  - [guard_operation](#guard_operation)
-  - [guard_path](#guard_path)
-  - [patch_file](#patch_file)
-  - [error](#error)
-  - [warn](#warn)
-  - [info](#info)
-  - [debug](#debug)
-  - [trace](#trace)
-  - [Colored Output](#colored-output)
-<!--toc:end-->
-
----
-
-## Import The Prompt Utils Into Your Tools Script
-In order to use the bash prompt helpers in your bash scripts, you need to source the provided `prompt-utils.sh` script.
-This script is pre-packaged with Loki and is located [here](../../assets/functions/utils/prompt-utils.sh).
-
-When sourcing the file in your bash script, you use the `LLM_PROMPT_UTILS_FILE` environment variable that automatically 
-populates the `functions/utils/prompt-utils.sh` path for you.
-
-Thus, to properly source and enable all the bash prompt helpers in your Bash tools, add the following prelude to your
-scripts:
-
-```bash
-source "$LLM_PROMPT_UTILS_FILE"
-```
-
-## Included Utility Functions
-Below are the built-in bash prompt helpers that can be used to enhance user interaction with your tool scripts.
-
-### input
-Prompt for text input
-
-![Prompt Utils Input](../images/tools/prompt-utils-input.png)
-
-**Example With Validation:**
-```bash
-text=$(with_validation 'input "Please enter something:"' validate_present)
-```
-
-**Example Without Validation:**
-```bash
-text=$(input "Please enter something:")
-```
-
-### confirm
-Show a confirm dialog with options for yes/no
-
-![Prompt Utils Confirm](../images/tools/prompt-utils-confirm.png)
-
-**Example:**
-```bash
-confirmed=$(confirm "Do the thing?")
-if [[ $confirmed == "0" ]]; then echo "No"; else echo "Yes"; fi
-```
-
-### list
-Renders a text based list of options that can be selected by the user using up, down, and enter
-keys that then returns the chosen option.
-
-![Prompt Utils List](../images/tools/prompt-utils-list.png)
-
-**Example:**
-```bash
-options=("one" "two" "three" "four")
-choice=$(list "Select an item" "${options[@]}")
-echo "Your choice: ${options[$choice]}"
-```
-
-### checkbox
-Render a text based list of options, where multiple options can be selected by the user using down, up,
-and enter keys that then returns the chosen options.
-
-![Prompt Utils Checkbox](../images/tools/prompt-utils-checkbox.png)
-
-**Example:**
-```bash
-options=("one" "two" "three" "four")
-checked=$(checkbox "Select one or more items" "${options[@]}")
-echo "Your choices: ${checked}"
-```
-
-### password
-Show a password prompt displaying stars for each character typed.
-
-![Prompt Utils Password](../images/tools/prompt-utils-password.png)
-
-**Example With Validation:**
-```bash
-validate_password() {
-  if [[ ${#1} -lt 10 ]]; then
-    echo "Password must be at least 10 characters"
-    exit 1
-  fi
-}
-pass=$(with_validate 'password "Enter your password"' validate_password)
-```
-
-**Example Without Validation:**
-```bash
-pass="$(password "Enter your password:")"
-```
-
-### editor
-Open the default editor (`$EDITOR`); if none is set, default back to `vi`
-
-**Example:**
-```bash
-text=$(editor "Please enter something in the editor")
-echo -e "You wrote:\n${text}"
-```
-
-### with_validate
-Evaluate the given prompt command with validation. This prompts the user for input until the
-validation functions returns 0.
-
-![Prompt Utils With-validate](../images/tools/prompt-utils-with-validate.png)
-
-**Example:**
-```bash
-# Using the built-in 'validate_present' validator
-text=$(with_validate 'input "Please enter something and confirm with enter"' validate_present)
-
-# Using a custom validator; e.g. for password
-validate_password() {
-  if [[ ${#1} -lt 10 ]]; then
-    echo "Password needs to be at least 10 characters"
-    exit 1
-  fi
-}
-pass=$(with_validate 'password "Enter random password"' validate_password)
-```
-
-### validate_present
-Validate that the prompt returned a value.
-
-![Prompt Utils Validate-Present](../images/tools/prompt-utils-validate-present.png)
-
-**Example:**
-```bash
-text=$(with_validate 'input "Please enter something and confirm with enter"' validate_present)
-```
-
-### detect_os
-Detect the current OS.
-
-Returns one of the following:
-
-* `solaris`
-* `macos`
-* `linux`
-* `bsd`
-* `windows`
-* `unknown`
-
-**Example:**
-```bash
-detect_os
-```
-
-### get_opener
-Determines the Os-specific file opening command (i.e. the command to open anything)
-
-**Example:**
-```bash
-# Returns 'xdg-open'
-get_opener
-```
-
-### open_link
-Opens the given link in the default browser
-
-**Example:**
-```bash
-open_link https://www.google.com
-```
-
-### guard_operation
-Prompt for permission to run an operation
-
-**Example:**
-```bash
-guard_operation "Execute SQL?"
-_run_sql
-```
-
-### guard_path
-Prompt for permission to perform path operations
-
-**Example:***
-```bash
-guard_path "$target_path" "Remove '$target_path'?"
-rm -rf "$target_path"
-```
-
-### patch_file
-Patch a file and show a diff using the default diff viewer. Uses git diff syntax.
-
-**Example:**
-```bash
-new_contents="$(patch_file "$path" file.patch)"
-```
-
-### error
-Log an error
-
-![Prompt Utils Error](../images/tools/prompt-utils-error.png)
-
-### warn
-Log a warning
-
-![Prompt Utils Warning](../images/tools/prompt-utils-warning.png)
-
-### info
-Log info
-
-![Prompt Utils Info](../images/tools/prompt-utils-info.png)
-
-### debug
-Log a debug message
-
-![Prompt Utils Debug](../images/tools/prompt-utils-debug.png)
-
-### trace
-Log a trace message
-
-![Prompt Utils Trace](../images/tools/prompt-utils-trace.png)
-
-### Colored Output
-The following commands allow users to output text in specific colors.
-
-* `red`
-* `green`
-* `gold`
-* `blue`
-* `magenta`
-* `cyan`
-* `white`
-
-**Example:**
-```bash
-red "This will be red"
-yellow "This will be yellow"
-```

docs/function-calling/CUSTOM-BASH-TOOLS.md

@@ -1,309 +0,0 @@
-# Custom Bash-Based Tools
-Loki supports tools written in Bash. However, they must be written in a special format with special annotations in order 
-for Loki to be able to properly parse and utilize them. This formatting ensures that each Bash script is 
-self-describing, and formatted in such a way that Loki can anticipate how to execute it and what parameters to pass to 
-it. This standardization also lets Loki compile the script into a JSON schema that can be used to inform the LLM about 
-how to use the tool.
-
-Each Bash-based tool must follow a specific structure in order for Loki to be able to properly compile and execute it:
-
-* The tool must be a Bash script with a `.sh` file extension.
-* The script must have the following comments:
-    * `# @describe ...` comment at the top that describes the tool.
-    * `# @env LLM_OUTPUT=/dev/stdout The output path` comment to describe the `LLM_OUTPUT` environment variable. This 
-      syntax in particular assigns `/dev/stdout` as the default value for `LLM_OUTPUT`, so that if it's not set by Loki, 
-      the script will still function properly.
-    * `# @option --option <value>  An example option` comments to define each option that the tool accepts.
-        * Use `--flag` syntax for boolean flags.
-        * Use `--option <value>` syntax for options that accept a value.
-        * Use `--option <value1,value2>` syntax for options that accept multiple values (i.e. arrays).
-* The script must have a `main` function
-* The `main` function must redirect the return value to the `>> "$LLM_OUTPUT"` environment variable.
-    * This is necessary because Loki relies on the `$LLM_OUTPUT` environment variable to capture the output of the tool.
-
-Essentially, you can think of the Bash-based tool script as just a normal Bash script that uses special comments to 
-define a CLI.
-* The `# @env LLM_OUTPUT=/dev/stdout` comment to define the `$LLM_OUTPUT` environment variable (good practice)
-* A `# @describe`
-* And a `main` function that writes to `$LLM_OUTPUT`
-
-The following section explains how you can add parameters to your bash functions and how to test out your scripts.
-
-## Quick Links:
-<!--toc:start-->
-- [Loki Bash Tools Syntax](#loki-bash-tools-syntax)
-  - [Metadata](#metadata)
-  - [Environment Variables](#environment-variables)
-  - [Arguments](#arguments)
-  - [Flags](#flags)
-  - [Options](#options)
-  - [Subcommands (Agents only)](#subcommands-agents-only)
-- [Execute and Test Your Bash Tools](#execute-and-test-your-bash-tools)
-  - [Example](#example)
-- [Prompt Helpers](#prompt-helpers)
-<!--toc:end-->
-
----
-
-## Loki Bash Tools Syntax
-Loki Bash tools work via `@___` annotations that describe specific functionality of a script. The following reference
-explains the general syntax of these annotations and how to use them to create a CLI that Loki can recognize.
-
-Refer to the [Execute and Test Your Bash Tools](#execute-and-test-your-bash-tools) section to learn how to test out your Bash tools
-without needing to go through Loki itself.
-
-It's important to note that any functions prefixed with `_` are not sent to the LLM, so they will be invisible to the 
-LLM at runtime.
-
-### Metadata:
-You can define different metadata about your script to help Loki understand its dependencies and purpose.
-
-```bash
-# Use the `@meta require-tools` annotation to specify any external tools that your script depends on.
-# @meta require-tools jq,yq
-
-# Use the `@describe` annotation to describe the purpose of the script.
-# @describe A tool to interact with things
-```
-
-### Environment Variables:
-```bash
-###########################
-## Environment Variables ##
-###########################
-
-# Use `@env` to define environment variables that the script uses.
-# @env LLM_OUTPUT=/dev/stdout                          The output path, with a default value of '/dev/stdout' if not set.
-# @env OPTIONAL                                        An optional environment variable
-# @env REQUIRED!                                       A required environment variable
-# @env DEFAULT_VALUE=default                           An environment variable with a default value if unset.
-# @env DEFAULT_FROM_FN=`_default_env_fn`               An environment variable with a default value calculated from a function if unset.
-# @env CHOICE[even|odd]                                An environment variable that, if set, must be set to either `even` or `odd`
-# @env CHOICE_WITH_DEFAULT[=even|odd]                  An environment variable that, if set, must be set to either `even` or `odd`, and defaults to `even` when unset
-# @env CHOICE_FROM_FN[`_choice_env_fn`]                An environment variable that, if set, must be set to one of the values returned by the `_choice_fn` function.
-
-# Example variable usage:
-export CHOICE=even
-# ./script.sh
-main() {
-  [[ $CHOICE == "even" ]] || { echo "The value of the 'CHOICE' env var is not 'even'" >> "$LLM_OUTPUT" && exit 1 }
-}
-
-# Loki does not pass functions prefixed with `_` to the LLM, so these are essentially `private` functions
-_default_env_fn() {
-  echo "calculated default env value"
-}
-
-# Loki does not pass functions prefixed with `_` to the LLM, so these are essentially `private` functions
-_choice_env_fn() {
-  echo even
-  echo odd
-}
-```
-
-### Arguments:
-When referencing an argument defined via the `@arg` annotation, you can access its value using the `argc_<argument_name>` variable that
-is created at runtime.
-
-```bash
-###############
-## Arguments ##
-###############
-
-# Use `@arg` To define positional arguments for your script.
-# To reference an argument within your script, use the `argc_<argument_name>` variable.
-# @arg optional                                             Optional argument
-# @arg required!                                            Required argument
-# @arg multi_value*                                         An argument that accepts multiple values (e.g. './script.sh one two three')
-# @arg multi_value_required+                                An argument that is required and accepts multiple values
-# @arg value_notated <VALUE>                                An argument that explicitly specifies the name for documentation (e.g. Usage: ./script.sh [VALUE])
-# @arg default=default                                      An argument with a default value if unset
-# @arg default_from_fn=`_default_arg_fn`                    An argument with a default value calculated from a function if unset
-# @arg choice[even|odd]                                     An argument that, if set, must be set to either `even` or `odd`
-# @arg required_choice+[even|odd]                           An required argument that must be set to either `even` or `odd`
-# @arg default_choice[=even|odd]                            An argument that if unset defaults to 'even', but if set must be either `even` or `odd`
-# @arg multi_value_choice*[even|odd]                        An argument that, if set, must be set to either `even` or `odd`, and accepts multiple values
-# @arg choice_fn[`_choice_arg_fn`]                          An argument that, if set, must be set to one of the values returned by the `_choice_arg_fn` function.
-# @arg choice_fn_no_valid[?`_choice_arg_fn`]                An argument that, if set, can be set to one of the values returned by the `_choice_arg_fn` function,
-#                                                           but does not validate the value.
-# @arg multi_choice_fn*[`_choice_arg_fn`]                   An argument that, if set, must be set to one of the values returned by the `_choice_arg_fn` function,
-#                                                           and accepts multiple values.
-# @arg multi_choice_comma_fn*,[`_choice_arg_fn`]            An argument that, if set, must be set to one of the values returned by the `_choice_arg_fn` function,
-#                                                           and accepts multiple values in the form of a comma-separated list
-# @arg capture_arg~                                         An argument that captures all remaining args passed to the script
-
-# Example usage 1: ./script.sh something_required
-main() {
-  [[ $argc_required == "something_required" ]] || { echo "The value of the 'required' arg is not 'something_required'" >> "$LLM_OUTPUT" && exit 1 }
-}
-
-# Example usage 2: ./script.sh this is a test
-main() {
-  [[ "${argc_multi_value[*]}" == "this is a test" ]] || { echo "The value of the 'multi_value' arg is not 'this is a test'" >> "$LLM_OUTPUT" && exit 1 }
-}
-
-
-# Loki does not pass functions prefixed with `_` to the LLM, so these are essentially `private` functions
-_default_arg_fn() {
-  echo "default arg value"
-}
-
-# Loki does not pass functions prefixed with `_` to the LLM, so these are essentially `private` functions
-_choice_arg_fn() {
-  echo even
-  echo odd
-}
-```
-
-### Flags:
-To access the value of a flag defined via the `@flag` annotation, you can check the value of the `argc_<flag_name>` variable.
-
-```bash
-###########
-## Flags ##
-###########
-
-# Use `@flag` to define boolean flags for your script
-# To reference a flag within your script, use the `argc_<argument_name>` variable.
-# @flag    --bool                              A boolean flag with only a long option
-# @flag -b --bool                              A boolean flag with a short and long option
-# @flag -b                                     A boolean flag with only a short option
-# @flag    --multi*                            A boolean flag that can be used multiple times (e.g. '--multi --multi' will return '2')
-
-# Example usage 1: ./script.sh --bool
-main() {
-  [[ $argc_bool == "1" ]] || { echo "The value of the 'bool' flag is not '1'" >> "$LLM_OUTPUT" && exit 1 }
-}
-
-# Example usage 2: ./script.sh --multi --multi
-main() {
-  [[ $argc_multi == "2" ]] || { echo "The value of the 'multi' flag is not 2" >> "$LLM_OUTPUT" && exit 1 }
-}
-```
-
-### Options:
-To access the value of an option defined via the `@option` annotation, you can check the value of the `argc_<option_name>` variable.
-
-```bash
-#############
-## Options ##
-#############
-
-# Use `@option` to define flags that accept values
-# To reference an option within your script, use the `argc_<argument_name>` variable.
-# @option    --option                                     An option that accepts a value with only a long flag
-# @option -o --option                                     An option that accepts a value with both a short and long flag
-# @option -o                                              An option that accepts a value with only a short flag
-# @option    --required                                   A required option that accepts a value
-# @option    --multi*                                     An option that accepts multiple values                                      
-# @option    --required-multi+                            An option that accepts multiple values and is required
-# @option    --multi-comma*,                              An option that accepts multiple values in the form of a comma-separated list
-# @option    --value <VALUE>                              An option that explicitly specifies the name for documentation (e.g. Usage: ./script.sh --value [VALUE])
-# @option    --two-args <SRC> <DEST>                      An option that accepts two arguments and explicitly names them for documentation
-#                                                         (e.g. Usage: ./script.sh --two-args [SRC] [DEST])
-# @option    --unlimited-args <SRC> <DEST+>               An option that accepts an unlimited number of arguments and explicitly names them for documentation
-#                                                         (e.g. Usage: ./script.sh --unlimited-args [SRC] [DEST ...])
-# @option    --default=default                            An option that has a default value if unset
-# @option    --default-from-fn=`_default_opt_fn`          An option that has a default value calculated from a function if unset
-# @option    --choice[even|odd]                           An option that, if set, must be set to either `even` or `odd`
-# @option    --choice-default[=even|odd]                  An option that, if unset, defaults to `even`, but if set must be either `even` or `odd`
-# @option    --choice-multi*[even|odd]                    An option that, if set, must be set to either `even` or `odd`, and can be specified multiple times
-#                                                         (e.g. ./script.sh --choice-multi even --choice-multi odd)
-# @option    --required-choice-multi+[even|odd]           A required option that, must be set to either `even` or `odd`, and can be specified multiple times
-# @option    --choice-fn[`_choice_opt_fn`]                An option that, if set, must be set to one of the values returned by the `_choice_opt_fn` function.`
-# @option    --choice-fn-no-valid[?`_choice_opt_fn`]      An option that, if set, can be set to one of the values returned by the `_choice_opt_fn` function, with no validation
-# @option    --choice-multi-fn*[`_choice_opt_fn`]         An option that, if set, must be set to one of the values returned by the `_choice_opt_fn` function,
-#                                                         and can be specified multiple times
-# @option    --choice-multi-comma*,[`_choice_opt_fn`]     An option that, if set, must be set to one of the values returned by the `_choice_opt_fn` function,
-#                                                         and is specified as a comma-separated list
-# @option    --capture~                                   An option that captures all remaining arguments passed to the script
-
-# Example usage 1: ./script.sh --option some_value
-main() {
-  [[ $argc_option == "some_value" ]] || { echo "The value of the 'option' option is not 'some_value'" >> "$LLM_OUTPUT" && exit 1 }
-}
-
-# Example usage 2: ./script.sh --multi value1 --multi value2
-main() {
-  [[ "${argc_multi[*]}" == "value1 value2" ]] || { echo "The value of the 'multi' option is not 'value1 value2'" >> "$LLM_OUTPUT" && exit 1 }
-}
-
-
-# Loki does not pass functions prefixed with `_` to the LLM, so these are essentially `private` functions
-_default_opt_fn() {
-  echo "calculated default option value"
-}
-
-# Loki does not pass functions prefixed with `_` to the LLM, so these are essentially `private` functions
-_choice_opt_fn() {
-  echo even
-  echo odd
-}
-```
-
-### Subcommands (Agents only):
-By default, if no `@cmd` annotations are defined, the script's `main` function is treated as the default command.
-However, for agents, there can be many functions defined in one file, and thus it is useful to create subcommands
-to organize your agent's tools.
-
-```bash
-#################
-## Subcommands ##
-#################
-
-# Use the `@cmd` annotation to define subcommands for your script.
-# @cmd List all files
-list() {
-  ls -la >> "$LLM_OUTPUT"
-}
-
-# @cmd Output the contents of the specified file
-# @arg file! The file to output
-cat() {
-  cat "$argc_file" >> "$LLM_OUTPUT"
-}
-
-# Example usage 1: ./script.sh cat myfile.txt
-```
-
-## Execute and Test Your Bash Tools
-Your bash tools are just normal bash scripts stored in the `functions/tools` directory. So you can execute and test them
-directly by first having Loki compile them so all this syntactic sugar means something.
-
-This is achieved via the `loki --build-tools` command.
-
-### Example
-Suppose we want to execute the `functions/tools/get_current_time.sh` script for testing.
-
-We'd first make sure the script is visible in all contexts by ensuring it's in the `visible_tools` array in your global 
-`config.yaml` file. This ensures Loki builds the tool so it's ready to use in any context.
-
-You can find the location of your global `config.yaml` file with the following command:
-
-```shell
-loki --info | grep 'config_file' | awk '{print $2}'
-```
-
-Then, we can instruct Loki to build the script so we can test it out:
-
-```shell
-loki --build-tools
-```
-
-This will add additional boilerplate to the top of the script so that it can be executed directly.
-
-Finally, we can now execute the script:
-
-```bash
-$ ./get_current_time.sh
-Fri Oct 24 05:55:04 PM MDT 2025
-```
-
-## Prompt Helpers
-It's often useful to create interactive prompts for our bash tools so that our tools can get input from
-users.
-
-To accommodate this, Loki provides a set of prompt helper functions that can be referenced and used within your Bash
-tools.
-
-For more information, refer to the [Bash Prompt Helpers documentation](BASH-PROMPT-HELPERS.md).

docs/function-calling/CUSTOM-TOOLS.md

@@ -1,119 +0,0 @@
-# Custom Tools
-Loki is designed to be as flexible and as customizable as possible. One of the key
-features that enables this flexibility is the ability to create and integrate custom tools
-into your Loki setup. This document provides a guide on how to create and use custom tools within Loki.
-
-## Quick Links
-<!--toc:start-->
-- [Supported Languages](#supported-languages)
-- [Creating a Custom Tool](#creating-a-custom-tool)
-  - [Environment Variables](#environment-variables)
-  - [Custom Bash-Based Tools](#custom-bash-based-tools)
-  - [Custom Python-Based Tools](#custom-python-based-tools)
-<!--toc:end-->
-
----
-
-## Supported Languages
-Loki supports custom tools written in the following programming languages:
-
-* Python
-* Bash
-
-## Creating a Custom Tool
-All tools are created as scripts in either Python or Bash. They should be placed in the `functions/tools` directory.
-The location of the `functions` directory varies between systems, so you can use the following command to locate
-your `functions` directory:
-
-```shell
-loki --info | grep functions_dir | awk '{print $2}'
-```
-
-Once you've created your custom tool, remember to add it to the `visible_tools` array in your global `config.yaml` file 
-to enable it globally. See the [Tools](TOOLS.md#enablingdisabling-global-tools) documentation for more information on how Loki utilizes the 
-`visible_tools` array.
-
-### Environment Variables
-All tools have access to the following environment variables that provide context about the current execution environment:
-
-| Variable             | Description                                                                                                                                |
-|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------|
-| `LLM_OUTPUT`         | Indicates where the output of the tool should go. <br>In certain situations, this may be set to a temporary file instead of `/dev/stdout`. |
-| `LLM_ROOT_DIR`       | The root `config_dir` directory for Loki <br>(i.e. `dirname $(loki --info \| grep config_file \| awk '{print $2}')`)                       |
-| `LLM_TOOL_NAME`      | The name of the tool being executed                                                                                                        |
-| `LLM_TOOL_CACHE_DIR` | A directory specific to the tool for storing cache or temporary files                                                                      |
-
-Loki also searches the tools directory on startup for a `.env` file. If found, all tools in `functions/tools/` will have
-the environment variables defined in the `.env` file available to them.
-
-### Custom Bash-Based Tools
-To create a Bash-based tool, refer to the [custom bash tools documentation](CUSTOM-BASH-TOOLS.md).
-
-### Custom Python-Based Tools
-Loki supports tools written in Python.
-
-Each Python-based tool must follow a specific structure in order for Loki to be able to properly compile and
-execute it:
-
-* The tool must be a Python script with a `.py` file extension.
-* The tool must have a `def run` function that serves as the entry point for the tool.
-* The `run` function must accept parameters that define the inputs for the tool.
-  * Always use type hints to specify the data type of each parameter.
-  * Use `Optional[...]` to indicate optional parameters
-* The `run` function must return a `str`.
-  * For Python, this is automatically written to the `LLM_OUTPUT` environment variable, so there's no need to explicitly
-    write to the environment variable within the function.
-* The function must also have a docstring that describes the tool and its parameters.
-  * Each parameter in the `run` function should be documented in the docstring using the `Args:` section. They should use the following format:
-    * `<parameter_name>: <description>` Where
-      * `<parameter_name>`: The name of the parameter
-      * `<description>`: The description of the parameter
-  * These are *very* important because these descriptions are what's passed to the LLM as the description of the tool,
-    letting the LLM know what the tool does and how to use it.
-
-It's important to note that any functions prefixed with `_` are not sent to the LLM, so they will be invisible to the LLM
-at runtime.
-
-Below is the [`demo_py.py`](../../assets/functions/tools/demo_py.py) tool definition that comes pre-packaged with
-Loki and demonstrates how to create a Python-based tool:
-
-```python
-import os
-from typing import List, Literal, Optional
-
-def run(
-    string: str,
-    string_enum: Literal["foo", "bar"],
-    boolean: bool,
-    integer: int,
-    number: float,
-    array: List[str],
-    string_optional: Optional[str] = None,
-    array_optional: Optional[List[str]] = None,
-):
-    """Demonstrates how to create a tool using Python and how to use comments.
-    Args:
-        string: Define a required string property
-        string_enum: Define a required string property with enum
-        boolean: Define a required boolean property
-        integer: Define a required integer property
-        number: Define a required number property
-        array: Define a required string array property
-        string_optional: Define an optional string property
-        array_optional: Define an optional string array property
-    """
-    output = f"""string: {string}
-string_enum: {string_enum}
-string_optional: {string_optional}
-boolean: {boolean}
-integer: {integer}
-number: {number}
-array: {array}
-array_optional: {array_optional}"""
-
-    for key, value in os.environ.items():
-        if key.startswith("LLM_"):
-            output = f"{output}\n{key}: {value}"
-
-    return output
-```

docs/function-calling/MCP-SERVERS.md

@@ -1,121 +0,0 @@
-# MCP Servers
-[MCP servers](https://modelcontextprotocol.io/docs/getting-started/intro) are essentially APIs designed specifically for LLMs that work like a remote repository of
-tools for the model to access and extend its capabilities.
-
-So think of it like this: Instead of having to write all your own custom tools to interact with different
-services, those services can expose their functionality through an MCP server.
-
-Loki has first-class support for MCP servers.
-
-As mentioned in the [Loki Vault documentation](../VAULT.md), Loki can inject sensitive
-configuration data into your MCP configuration file to ensure that secrets are not hard-coded.
-
-## Quick Links
-<!--toc:start-->
-- [Important Note](#important-note)
-- [MCP Server Configuration](#mcp-server-configuration)
-  - [Secret Injection](#secret-injection)
-- [Default MCP Servers](#default-mcp-servers)
-- [Loki Configuration](#loki-configuration)
-  - [Global Configuration](#global-configuration)
-  - [Role Configuration](#role-configuration)
-  - [Agent Configuration](#agent-configuration)
-<!--toc:end-->
-
----
-
-## Important Note
-Be careful how many MCP servers you enable at one time, regardless of the context. When there is a significant
-number of configured MCP servers, enabling too many MCP servers may overwhelm the context length of a model,
-and quickly exceed token limits.
-
-## MCP Server Configuration
-Loki stores the MCP server configuration file, `functions/mcp.json`, in the `functions` directory. You can find
-this directory using the following command:
-
-```shell
-loki --info | grep functions_dir | awk '{print $2}'
-```
-
-The syntax for the `functions/mcp.json` file is identical to the syntax for MCP server configurations for Claude Desktop.
-So any time you're looking to add a new server, look at the docs for it and find the configuration example for
-Claude desktop. You should be able to use the exact same configuration in your `functions/mcp.json` file.
-
-### Secret Injection
-As mentioned in the [Loki Vault documentation](../VAULT.md), you can use Loki Vault to inject secrets into your MCP configuration file.
-
-In fact, this is why you need to set up your vault before using Loki at all: the built-in MCP configuration
-requires you set up some secrets to use it.
-
-For more information about how to set up your vault and inject secrets, please refer to the [Loki Vault documentation](../VAULT.md).
-
-## Default MCP Servers
-Loki ships with a `functions/mcp.json` file that includes some useful MCP servers:
-
-* [github](https://github.com/github/github-mcp-server) - Interact with GitHub repositories, issues, pull requests, and more.
-* [docker](https://github.com/ckreiling/mcp-server-docker) - Manage your local Docker containers with natural language
-* [slack](https://github.com/korotovsky/slack-mcp-server) - Interact with Slack
-
-## Loki Configuration
-MCP servers, like tools, can be used in a handful of contexts:
-* Inside a session
-* Inside a role
-* Inside an agent
-* Globally (i.e. outside a session, role, or agent)
-
-Each of these has a different configuration and interaction with the global configuration.
-
-***Note:** The names of each MCP server referenced in the below configuration properties directly corresponds
-to the names given in the `functions/mcp.json` configuration file. So if you change the name of an MCP server
-from `slack` to `lucem-slack`, then you need to also update your Loki configuration accordingly.
-
-### Global Configuration
-The global configuration is essentially what settings you want to have on by default when
-you just invoke `loki`. (Don't worry about agents, roles, or sessions yet. We'll get to them in a bit).
-
-The following settings are available in the global configuration for MCP servers:
-
-```yaml
-mcp_server_support: true         # Enables or disables MCP server support (globally).
-mapping_mcp_servers:             # Alias for an MCP server or set of servers
-  git: github,gitmcp
-enabled_mcp_servers: null        # Which MCP servers to enable by default (e.g. 'github,slack')
-```
-
-A special note about `enabled_mcp_servers`: a user can set this to `all` to enable all configured MCP servers in the 
-`functions/mcp.json` configuration. However, **this should be used with caution**. When there is a significant number 
-of configured MCP servers, enabling all MCP servers may overwhelm the context length of a model, and quickly exceed 
-token limits.
-
-(See the [Configuration Example](../../config.example.yaml) file for an example global configuration with all options.)
-
-When running in REPL-mode, the `mcp_server_support` and `enabled_mcp_servers` settings can be overridden using the 
-`.set` command:
-
-![REPL set MCP servers](../images/mcp/global-settings-overrides-repl.png)
-
-### Role Configuration
-When you create a role, you have the following MCP-related configuration options available to you:
-
-```yaml
-enabled_mcp_servers: github    # Which MCP servers the role uses.
-```
-
-The values for `mapping_mcp_servers` are inherited from the `[global configuration](#global-configuration)`.
-
-For more information about roles, refer to the [Roles](../ROLES.md) documentation.
-
-### Agent Configuration
-When you create an agent, you have the following MCP-related configuration options available to you:
-
-```yaml
-mcp_servers:                 # Which MCP servers the agent uses
-  - github
-  - docker
-```
-
-The values for `mapping_mcp_servers` are inherited from the [global configuration](#global-configuration).
-
-For more information about agents, refer to the [Agents](../AGENTS.md) documentation.
-
-For a full example configuration for an agent, see the [Agent Configuration Example](../../config.agent.example.yaml) file.

docs/function-calling/TOOLS.md

@@ -1,139 +0,0 @@
-# Tools
-Loki supports function calling with various tools built-in to enhance LLM capabilities. All built-in tools for Loki
-are located in the [`functions/tools`](../../assets/functions/tools) directory. These tools are also stored in your Loki `functions`
-directory, which is also where you'd go to add more tools.
-
-**Pro Tip:** The Loki functions directory can be found by running the following command:
-```bash
-loki --info | grep functions_dir | awk '{print $2}'
-```
-
-# Quick Links
-<!--toc:start-->
-- [Built-In Tools](#built-in-tools)
-- [Configuration](#configuration)
-  - [Global Configuration](#global-configuration)
-  - [Enabling/Disabling Global Tools](#enablingdisabling-global-tools)
-  - [Role Configuration](#role-configuration)
-  - [Agent Configuration](#agent-configuration)
-<!--toc:end-->
-
----
-
-## Built-In Tools
-The following tools are built-in to Loki by default, and their default enabled/disabled status is indicated. More about how tools can
-be enabled/disabled can be found in the [Configuration](#configuration) section below.
-
-| Tool                                                                                | Description                                                                                                                                                                                                                          | Enabled/Disabled |
-|-------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------|
-| [`demo_py.py`](../../assets/functions/tools/demo_py.py)                             | Demonstrates how to create a tool using Python and how to use comments.                                                                                                                                                              | 🔴               |
-| [`demo_sh.sh`](../../assets/functions/tools/demo_sh.sh)                             | Demonstrate how to create a tool using Bash and how to use comment tags.                                                                                                                                                             | 🔴               |
-| [`execute_command.sh`](../../assets/functions/tools/execute_command.sh)             | Execute the shell command.                                                                                                                                                                                                           | 🟢               |
-| [`execute_py_code.py`](../../assets/functions/tools/execute_py_code.py)             | Execute the given Python code.                                                                                                                                                                                                       | 🔴               |
-| [`execute_sql_code.sh`](../../assets/functions/tools/execute_sql_code.sh)           | Execute SQL code.                                                                                                                                                                                                                    | 🔴               |
-| [`fetch_url_via_curl.sh`](../../assets/functions/tools/fetch_url_via_curl.sh)       | Extract the content from a given URL using cURL.                                                                                                                                                                                     | 🔴               |
-| [`fetch_url_via_jina.sh`](../../assets/functions/tools/fetch_url_via_jina.sh)       | Extract the content from a given URL using Jina.                                                                                                                                                                                     | 🔴               |
-| [`fs_cat.sh`](../../assets/functions/tools/fs_cat.sh)                               | Read the contents of a file at the specified path.                                                                                                                                                                                   | 🟢               |
-| [`fs_ls.sh`](../../assets/functions/tools/fs_ls.sh)                                 | List all files and directories at the specified path.                                                                                                                                                                                | 🟢               |
-| [`fs_mkdir.sh`](../../assets/functions/tools/fs_mkdir.sh)                           | Create a new directory at the specified path.                                                                                                                                                                                        | 🔴               |
-| [`fs_patch.sh`](../../assets/functions/tools/fs_patch.sh)                           | Apply a patch to a file at the specified path. <br>This can be used to edit a file without having to rewrite the whole file.                                                                                                         | 🔴               |
-| [`fs_rm.sh`](../../assets/functions/tools/fs_rm.sh)                                 | Remove a file or directory at the specified path.                                                                                                                                                                                    | 🔴               |
-| [`fs_write.sh`](../../assets/functions/tools/fs_write.sh)                           | Write the full file contents to a file at the specified path.                                                                                                                                                                        | 🟢               |
-| [`get_current_time.sh`](../../assets/functions/tools/get_current_time.sh)           | Get the current time.                                                                                                                                                                                                                | 🟢               |
-| [`get_current_weather.py`](../../assets/functions/tools/get_current_weather.py)     | Get the current weather in a given location (Python implementation)                                                                                                                                                                  | 🔴               |
-| [`get_current_weather.sh`](../../assets/functions/tools/get_current_weather.sh)     | Get the current weather in a given location.                                                                                                                                                                                         | 🟢               |
-| [`query_jira_issues.sh`](../../assets/functions/tools/query_jira_issues.sh)         | Query for jira issues using a Jira Query Language (JQL) query.                                                                                                                                                                       | 🟢               |
-| [`search_arxiv.sh`](../../assets/functions/tools/search_arxiv.sh)                   | Search arXiv using the given search query and return the top papers.                                                                                                                                                                 | 🔴               |
-| [`search_wikipedia.sh`](../../assets/functions/tools/search_wikipedia.sh)           | Search Wikipedia using the given search query. <br>Use it to get detailed information about a public figure, interpretation of a <br>complex scientific concept or in-depth connectivity of a significant historical <br>event, etc. | 🔴               |
-| [`search_wolframalpha.sh`](../../assets/functions/tools/search_wolframalpha.sh)     | Get an answer to a question using Wolfram Alpha. The input query should be <br>in English. Use it to answer user questions that require computation, detailed <br>facts, data analysis, or complex queries.                          | 🔴               |
-| [`send_mail.sh`](../../assets/functions/tools/send_mail.sh)                         | Send an email.                                                                                                                                                                                                                       | 🔴               |
-| [`send_twilio.sh`](../../assets/functions/tools/send_twilio.sh)                     | Send SMS or Twilio Messaging Channels messages using the Twilio API.                                                                                                                                                                 | 🔴               |
-| [`web_search_loki.sh`](../../assets/functions/tools/web_search_loki.sh)             | Perform a web search to get up-to-date information or additional context. <br>Use this when you need current information or feel a search could provide <br>a better answer.                                                         | 🔴               |
-| [`web_search_perplexity.sh`](../../assets/functions/tools/web_search_perplexity.sh) | Perform a web search using the Perplexity API to get up-to-date <br>information or additional context. Use this when you need current <br>information or feel a search could provide a better answer.                                | 🔴               |
-| [`web_search_tavily.sh`](../../assets/functions/tools/web_search_tavily.sh)         | Perform a web search using the Tavily API to get up-to-date <br>information or additional context. Use this when you need current <br>information or feel a search could provide a better answer.                                    | 🔴               |
-
-Details on what configuration, if any, is necessary for each tool can be found inside the tool file definition itself.
-
-## Configuration
-Tools can be used in a handful of contexts:
-* Inside a session
-* Inside a role
-* Inside an agent
-* Globally (i.e. outside a session, role, or agent)
-
-Each of these has a different configuration and interaction with the global configuration.
-
-**Note:** For each configuration property listed below, the functions that are mentioned *only*
-correspond to the tool scripts located in your Loki `functions/tools` directory.
-
-### Global Configuration
-The global configuration is essentially what settings you want to have on by default when
-you just invoke `loki`. (Don't worry about agents, roles, or sessions yet. We'll get to them in a bit).
-
-The following settings are available in the global configuration for tools:
-
-```yaml
-function_calling_support: true   # Enables or disables function calling in any context
-mapping_tools:                   # Alias for a tool or toolset
-  fs: 'fs_cat,fs_ls,fs_mkdir,fs_rm,fs_write'
-enabled_tools: null              # Which tools to use by default. (e.g. 'fs,web_search_loki')
-visible_tools:                   # Which tools are visible to be compiled (and are thus able to be defined in 'enabled_tools')
-  #  - demo_py.py
-  - execute_command.sh
-```
-
-A special not about `enabled_tools`: a user can set this to `all` to enable all available tools listed in the 
-`visible_tools` section of your Loki `config.yaml` file.
-See the [Enabling/Disabling Global Tools](#enablingdisabling-global-tools) section below for more information on how tools
-are globally enabled/disabled globally.
-
-(See the [Configuration Example](../../config.example.yaml) file for an example global configuration with all options.)
-
-When running in REPL-mode, the `function_calling_support` and `enabled_tools` settings can be overridden using the 
-`.set` command:
-
-![REPL set function calling](../images/tools/global-settings-overrides-repl.png)
-
-You'll notice that mentioned above, some tools are disabled while others are enabled. How is that determined?
-
-### Enabling/Disabling Global Tools
-The configured tools are enabled/disabled by looking at the values in the `visible_tools` array in your `config.yaml` 
-file. This file is located in the root of the Loki `config` directory. The location of the Loki config varies by system,
-so your config file can be found using the following command:
-
-```bash
-loki --info | grep 'config_file' | awk '{print $2}'
-```
-
-Each line in the `visible_tools` array lists a tool.
-
-If that line is commented out, then that tool is not included in the global tool set, and cannot be used in any context;
-This means it will not be built, and even if enabled under `enabled_tools`, it still will not be available in any 
-context.
-
-### Role Configuration
-When you create a role, you have the following global tool-related configuration options available to you:
-
-```yaml
-enabled_tools: query_jira_issues    # Which tools the role uses.
-```
-
-The values for `mapping_tools` are inherited from the [global configuration](#global-configuration).
-
-For more information about roles, refer to the [Roles](../ROLES.md) documentation.
-
-### Agent Configuration
-When you create an agent, you have the following global tool-related configuration options available to you:
-
-```yaml
-global_tools:                 # Which global tools the agent uses
-  - query_jira_issues.sh
-  - fs_cat.sh
-  - fs_ls.sh
-```
-
-The values for `mapping_tools` are inherited from the [global configuration](#global-configuration).
-
-For more information about agents, refer to the [Agents](../AGENTS.md) documentation.
-
-For a full example configuration for an agent, see the [Agent Configuration Example](../../config.agent.example.yaml) file.