Template
t
144 lines
5.4 KiB
Markdown
144 lines
5.4 KiB
Markdown
# loki-config-template
|
|
|
|
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/<you>/loki-config-template
|
|
```
|
|
|
|
…or from within the Loki REPL:
|
|
|
|
```
|
|
.install remote https://github.com/<you>/loki-config-template
|
|
```
|
|
|
|
Pin to a specific branch, tag, or commit by suffixing `#<ref>`:
|
|
|
|
```sh
|
|
loki --install-from https://github.com/<you>/loki-config-template#v1.0.0
|
|
loki --install-from https://github.com/<you>/loki-config-template#main
|
|
loki --install-from https://github.com/<you>/loki-config-template#abc1234
|
|
```
|
|
|
|
Restrict the install to a single asset category with `--filter`:
|
|
|
|
```sh
|
|
loki --install-from https://github.com/<you>/loki-config-template --filter agents
|
|
loki --install-from https://github.com/<you>/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/<you>/loki-config-template --install-force
|
|
```
|
|
|
|
## Layout
|
|
|
|
Loki only reads these top-level directories. Anything else in the repo is
|
|
ignored.
|
|
|
|
```
|
|
loki-config-template/
|
|
├── agents/
|
|
│ └── <agent-name>/
|
|
│ ├── 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/
|
|
│ └── <role-name>.md # Role with frontmatter + prompt body
|
|
├── macros/
|
|
│ └── <macro-name>.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/<name>.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/<name>.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 <NAME>` /
|
|
`.vault add <NAME>` 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
|
|
`#<tag>` for reproducibility.
|
|
- Keep agent-local logic in `agents/<name>/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`).
|