From 2eaa2098e506a6716990a37b5e1bc43135940c1a Mon Sep 17 00:00:00 2001 From: t Date: Fri, 22 May 2026 17:07:12 -0600 Subject: [PATCH] Populate template assets --- README.md | 143 ++++++++++++++++++++++++++++++++- agents/hello-agent/README.md | 15 ++++ agents/hello-agent/config.yaml | 17 ++++ functions/mcp.json | 16 ++++ functions/tools/greet.sh | 12 +++ macros/greet.yaml | 9 +++ roles/explainer.md | 16 ++++ 7 files changed, 227 insertions(+), 1 deletion(-) create mode 100644 agents/hello-agent/README.md create mode 100644 agents/hello-agent/config.yaml create mode 100644 functions/mcp.json create mode 100644 functions/tools/greet.sh create mode 100644 macros/greet.yaml create mode 100644 roles/explainer.md diff --git a/README.md b/README.md index 58c7c8d..cdc1bbe 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,143 @@ # loki-config-template -Starter template for Loki configurations. Fork it, customize the agents/roles/macros/tools/MCP servers, then `loki --install-from <your-fork>` + +A starter template for sharing [Loki](https://github.com/Dark-Alex-17/loki) +configurations — agents, roles, macros, tools, and MCP servers — via any +git repository. + +Fork this repo, customize the assets to your taste, then install your fork +into Loki with a single command. + +## Quick start + +Install everything in this template into your local Loki config: + +```sh +loki --install-from https://github.com//loki-config-template +``` + +…or from within the Loki REPL: + +``` +.install remote https://github.com//loki-config-template +``` + +Pin to a specific branch, tag, or commit by suffixing `#`: + +```sh +loki --install-from https://github.com//loki-config-template#v1.0.0 +loki --install-from https://github.com//loki-config-template#main +loki --install-from https://github.com//loki-config-template#abc1234 +``` + +Restrict the install to a single asset category with `--filter`: + +```sh +loki --install-from https://github.com//loki-config-template --filter agents +loki --install-from https://github.com//loki-config-template --filter mcp_config +``` + +Valid filter values: `agents`, `roles`, `macros`, `functions`, `mcp_config`. + +Skip per-file conflict prompts with `--install-force`: + +```sh +loki --install-from https://github.com//loki-config-template --install-force +``` + +## Layout + +Loki only reads these top-level directories. Anything else in the repo is +ignored. + +``` +loki-config-template/ +├── agents/ +│ └── / +│ ├── config.yaml # LLM-loop agent +│ │ └── (or graph.yaml) # Graph agent +│ ├── README.md # Optional +│ ├── tools.sh # Optional agent-local tools +│ └── scripts/ # Optional graph-node scripts +├── roles/ +│ └── .md # Role with frontmatter + prompt body +├── macros/ +│ └── .yaml # Positional/rest-args + REPL command steps +└── functions/ + ├── tools/ + │ └── *.sh / *.py / *.ts # Global tools (auto chmod +x on install) + └── mcp.json # MCP server config (merged with local) +``` + +The `functions/mcp.json` file is **merged** into your existing local file +on install (not overwritten). For conflicting server names, you'll be +prompted to keep yours, take the remote's, or rename the remote entry. + +## What's in this template + +| Asset | File | What it is | +|---|---|---| +| Agent | `agents/hello-agent/config.yaml` | Tiny LLM-loop agent that greets the user. | +| Role | `roles/explainer.md` | Role that explains technical concepts simply. | +| Macro | `macros/greet.yaml` | Macro showing positional and rest-arg variables. | +| Tool | `functions/tools/greet.sh` | Bash tool using Loki's argc-style annotations. | +| MCP | `functions/mcp.json` | One vanilla server + one with a vault secret reference. | + +Each sample is intentionally minimal. Replace it with your own work, or +delete what you don't need. + +## Customizing + +### Agents +Each agent lives in its own subdirectory under `agents/`. For LLM-loop +agents, put a `config.yaml` (full schema: +[Agents wiki](https://github.com/Dark-Alex-17/loki/wiki/Agents)). For +declarative graph agents, put a `graph.yaml` instead +([Graph Agents wiki](https://github.com/Dark-Alex-17/loki/wiki/Graph-Agents)). + +### Roles +Each `roles/.md` is a YAML frontmatter block followed by the role +instructions ([Roles wiki](https://github.com/Dark-Alex-17/loki/wiki/Roles)). + +### Macros +Each `macros/.yaml` is a list of REPL commands to execute, with +optional positional/rest variables +([Macros wiki](https://github.com/Dark-Alex-17/loki/wiki/Macros)). + +### Tools +Tools in `functions/tools/` follow Loki's argc-style schema +([Custom Tools wiki](https://github.com/Dark-Alex-17/loki/wiki/Custom-Tools)). +Bash, Python, and TypeScript scripts are auto-detected and given the +executable bit on install. + +### MCP servers +Add or modify entries in `functions/mcp.json` +([MCP Servers wiki](https://github.com/Dark-Alex-17/loki/wiki/MCP-Servers)). +Use `{{SECRET_NAME}}` placeholders for values you don't want to commit; +Loki will detect missing secrets after the merge and prompt you to add +them to the vault (or list them for you to add via `loki --add-secret`). + +## Secrets workflow + +Anywhere you reference a secret in `mcp.json` (or in any installed file), +use the `{{NAME}}` placeholder syntax. After `--install-from` completes: + +- **Interactive mode**: Loki prompts you per-secret to add the value to + the vault. On the first "Yes," it creates the vault password file if + needed. +- **Non-interactive mode** (CI, piped): Loki prints a final reminder + listing every missing secret with the `loki --add-secret ` / + `.vault add ` commands you can run to fill them in. + +See the [Vault wiki](https://github.com/Dark-Alex-17/loki/wiki/Vault) for +the full secrets workflow. + +## Tips for forks + +- Pin your fork to tagged releases so consumers can install with + `#` for reproducibility. +- Keep agent-local logic in `agents//scripts/` and tools.sh — global + tools (in `functions/tools/`) are shared across every agent. +- The `mcp.json` merge is *additive*. If you remove a server from your + fork, existing installs of that server are NOT pruned. That's by design. +- Use `--filter` to ship just one category if your repo is mixed (e.g., a + repo of just MCP servers can be consumed with `--filter mcp_config`). diff --git a/agents/hello-agent/README.md b/agents/hello-agent/README.md new file mode 100644 index 0000000..519d0c2 --- /dev/null +++ b/agents/hello-agent/README.md @@ -0,0 +1,15 @@ +# hello-agent + +A minimal sample agent shipped with `loki-config-template`. Use it as a +starting point or delete this directory. + +Activate it in the Loki REPL: + +``` +.agent hello-agent +``` + +Customize `config.yaml` for the model, temperature, system prompt, and +optional features (tool access, sub-agent spawning, todo system, etc.). +See the [Loki Agents wiki](https://github.com/Dark-Alex-17/loki/wiki/Agents) +for the full configuration reference. diff --git a/agents/hello-agent/config.yaml b/agents/hello-agent/config.yaml new file mode 100644 index 0000000..279c935 --- /dev/null +++ b/agents/hello-agent/config.yaml @@ -0,0 +1,17 @@ +name: hello-agent +description: A tiny example agent that greets the user. +version: 1 +model: openai:gpt-4o-mini +temperature: 0.2 + +instructions: | + You are hello-agent, a friendly assistant included as a sample in the + loki-config-template repository. + + When the user greets you, greet them warmly by name if they provide one. + Keep responses brief — one or two sentences — and offer to help with + whatever they're working on. + + This agent is meant as a starting point. Replace these instructions and + the model choice with whatever suits your use case, or delete the + `agents/hello-agent/` directory entirely if you don't need it. diff --git a/functions/mcp.json b/functions/mcp.json new file mode 100644 index 0000000..815d1cf --- /dev/null +++ b/functions/mcp.json @@ -0,0 +1,16 @@ +{ + "mcpServers": { + "fetch": { + "type": "stdio", + "command": "uvx", + "args": ["mcp-server-fetch"] + }, + "github": { + "type": "http", + "url": "https://api.githubcopilot.com/mcp/", + "headers": { + "Authorization": "Bearer {{GITHUB_PAT}}" + } + } + } +} diff --git a/functions/tools/greet.sh b/functions/tools/greet.sh new file mode 100644 index 0000000..7070678 --- /dev/null +++ b/functions/tools/greet.sh @@ -0,0 +1,12 @@ +#!/usr/bin/env bash +set -e + +# @describe Greet a person by name. Example bash tool shipped with loki-config-template. +# @option --name! Name of the person to greet. + +# @env LLM_OUTPUT=/dev/stdout The output path + +# shellcheck disable=SC2154 +main() { + printf 'Hello, %s!\n' "${argc_name}" >> "$LLM_OUTPUT" +} diff --git a/macros/greet.yaml b/macros/greet.yaml new file mode 100644 index 0000000..e35e176 --- /dev/null +++ b/macros/greet.yaml @@ -0,0 +1,9 @@ +variables: + - name: name + default: friend + rest: false + - name: extras + rest: true + +steps: + - Hello {{name}}! {{extras}} diff --git a/roles/explainer.md b/roles/explainer.md new file mode 100644 index 0000000..bebc709 --- /dev/null +++ b/roles/explainer.md @@ -0,0 +1,16 @@ +--- +name: explainer +temperature: 0.3 +--- +You are explainer, a role that translates technical concepts into clear, +plain-language explanations. + +When the user asks about a topic: + +- Identify the core idea in one sentence. +- Build up from familiar concepts the user is likely to know. +- Avoid jargon. When a term is unavoidable, define it briefly inline. +- End with a concrete example or analogy that grounds the abstract part. + +Keep responses focused. If the user wants more depth on a sub-topic, let +them ask — don't volunteer every related concept upfront.