Skip to content
Back to search

KoLibri

Kingdom of Loathing toolkit in .NET: CLI, MCP server with OAuth-approved limits for AI assistants, desktop app and a library. KoLmafia data, mall pricing, daily routines, own-shop CRM.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/grassmann-it--kolibri/badge.svg)](/listings/grassmann-it--kolibri)

HTML

<a href="/listings/grassmann-it--kolibri"><img src="/api/listings/grassmann-it--kolibri/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

The library:

<!-- NuGet publishing is planned for 0.5; until then reference the project from a source checkout -->
<ProjectReference Include="path/to/KoLibri/src/LibKolibri/src/LibKolibri/LibKolibri.csproj" />
using KoLibri.Core.Basis;
using LibKolibri;

using var kol = await KolibriClient.OpenAsync(AccountRole.Main);
var status = await kol.GetStatusAsync();
Console.WriteLine($"{status.PlayerName}: {status.Meat} meat");

Build from source (NuGet packages for the library, CLI and MCP server are planned for 0.5; until then use the release archives or a source build):

dotnet build KoLibri.slnx
dotnet run --project tools/KolLibri.Cli -- --help

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 283 lines
  1. <p align="center"><img src="assets/kolibri-icon.svg" width="96" alt="KoLibri"></p>
  2. # KoLibri
  3. **KoLmafia's automation, minus the clicking.**
  4. KoLibri is a .NET 8 toolset for [Kingdom of Loathing](https://www.kingdomofloathing.com/).
  5. It covers the same ground as [KoLmafia](https://github.com/kolmafia/kolmafia) —
  6. the complete data snapshot, account reads, mall pricing, crafting,
  7. adventures and the daily routines — but it leans on automation instead of
  8. manual clicks: you tell it *what* should happen, it works out the *how*,
  9. shows you the plan and asks for approval before it touches anything.
  10. ```
  11. dotnet run --project tools/KolLibri.Cli -- daily breakfast --role all --execute --approval-token $TOK
  12. ```
  13. That single command reads both accounts, works out the day's numbers
  14. from the live data, plans the routine and runs it.
  15. > KoLibri is an unofficial project, not affiliated with the Kingdom of Loathing team. See [NOTICE.md](NOTICE.md).
  16. > Where this is going: [ROADMAP.md](ROADMAP.md).
  17. > New here? Start with [docs/quickstart.md](docs/quickstart.md); [docs/usage.md](docs/usage.md) shows CLI (`kolibri` / `kolicli`), desktop, MCP and library side by side.
  18. ## What is in here
  19. | Project | Role | Package |
  20. |---|---|---|
  21. | `src/KoLibri.Core` | The domain: KoL connector, data catalog, daily planners, mall arbitrage, bounded runner, audit ledger | `KoLibri.Core` |
  22. | `src/LibKolibri` | The public API façade over the core | `KoLibri.LibKolibri` |
  23. | `tools/KolLibri.Cli` | Command line front-end | — |
  24. | `tools/KolLibri.Mcp` | MCP / JSON-RPC server for agent hosts | — |
  25. | `KoLibri.Desktop` | Avalonia desktop client | — |
  26. | `external/kolmafia-data` | The KoLmafia data dump as JSON Lines | — |
  27. The split follows one question: *what gets reused?* Everything that
  28. several tools would need — the connector, the planners, the arbitators —
  29. lives in the core. The façade is deliberately thin. The apps are the
  30. operator-facing part.
  31. ## Features
  32. ### Daily routines
  33. | Routine | What it does |
  34. |---|---|
  35. | **Campfire** | Burns one inflammable leaf to advance the day, or crafts a Day Shortener (222 leaves) when the reserve runs thin. |
  36. | **Hermit** | Trades worthless items for permits (`autopermit=on`), then opens 11-leaf clovers — as many as the daily stock allows, capped at three. |
  37. | **Internet shop** | Claims the daily free pulls, skipping whatever was already taken. |
  38. | **Foreign bribes** | Buys bribe bags on the mall when the spread justifies it. |
  39. | **Bacon arbitrage** | Buys the Infinite BACON machine once and then BACON while the spread against the resale median is positive. |
  40. | **Clover restock** | Buys cheap 11-leaf clovers so the main account stays stocked for the hermit trade. |
  41. Every routine is split in two: a **planner** that is a pure function over
  42. a snapshot, and an **executor** that submits. The planner never touches
  43. the network, so the operator can see exactly what would happen before
  44. anything is sent.
  45. ### Adventures
  46. - A **manual adventure browser**: locations → encounter → monster →
  47. skill/item, with a token-gated live path.
  48. - A **bounded runner** that submits only allowlisted actions, stops after
  49. a bounded number of choices and never replays a request.
  50. - An **auto-combat adapter** that turns a strategy into typed step specs,
  51. so a manual run and an automated one share the same contract.
  52. ### Mall and pricing
  53. - Mall search, own-store reads, pricegun history.
  54. - A price provider that plugs into the pricing engine.
  55. - An executor that buys from another player's store: it reads the store
  56. password hash out of the store page and submits the purchase with the
  57. exact listing price, because KoL rejects a purchase whose price moved.
  58. ### Multi-account
  59. Main and Mallbot are first-class roles with their own sessions, their
  60. own meat pools and their own daily shop limits. `daily go --role all`
  61. runs both, in parallel, with one hash-chained audit trail across the
  62. whole run.
  63. ### Data
  64. The complete KoLmafia data dump, bundled and typed:
  65. | Records | Count |
  66. |---|---|
  67. | Items | 12 103 |
  68. | Modifiers | 13 375 |
  69. | Effects | 3 015 |
  70. | Concoctions | 2 238 |
  71. | Monster parts | 2 214 |
  72. | Monsters | 2 366 |
  73. | Skills | 1 657 |
  74. | Restores | 164 |
  75. | Adventures | 601 |
  76. | Zones | 148 |
  77. ```bash
  78. python3 scripts/import-kolmafia-data.py # refresh from a KoLmafia checkout
  79. ```
  80. ## Install
  81. The library:
  82. ```xml
  83. <!-- NuGet publishing is planned for 0.5; until then reference the project from a source checkout -->
  84. <ProjectReference Include="path/to/KoLibri/src/LibKolibri/src/LibKolibri/LibKolibri.csproj" />
  85. ```
  86. ```csharp
  87. using KoLibri.Core.Basis;
  88. using LibKolibri;
  89. using var kol = await KolibriClient.OpenAsync(AccountRole.Main);
  90. var status = await kol.GetStatusAsync();
  91. Console.WriteLine($"{status.PlayerName}: {status.Meat} meat");
  92. ```
  93. Build from source (NuGet packages for the library, CLI and MCP server are planned for 0.5; until then use the release archives or a source build):
  94. ```bash
  95. dotnet build KoLibri.slnx
  96. dotnet run --project tools/KolLibri.Cli -- --help
  97. ```
  98. ## Desktop
  99. The desktop client is the operator's console: it reads both accounts
  100. live, shows the inventory with the KoLmafia catalog, the daily briefing,
  101. the market scan with the buy rules, the mall and the combat panel.
  102. ```bash
  103. dotnet run --project KoLibri.Desktop
  104. ```
  105. It needs a session for each account — the panels stay empty without one:
  106. ```bash
  107. kolibri login refresh --role main
  108. kolibri login refresh --role mallbot
  109. ```
  110. `kolibri login status` tells whether a session still works. It asks KoL,
  111. not just the stored cookie: a session that KoL dropped says
  112. `rejectedByServer: true`, and `usable: false`. The stored expiry only
  113. covers the cookie's lifetime — KoL ends a session earlier when the
  114. password changes or the account is signed out somewhere else.
  115. The panels:
  116. | Panel | What it shows |
  117. |---|---|
  118. | **Guts** | Meat, adventures, items and level of both accounts |
  119. | **Inventory** | The live inventory with the catalog's flags, uses and images |
  120. | **Daily** | The day's briefing from the live accounts |
  121. | **Arbitrage** | Mall listings against the pricegun median, plus the buy rules |
  122. | **Mall** | Own store and the market |
  123. | **Adventures** | Locations, encounters and the bounded runner |
  124. | **Combat** | The auto-combat policy and the fight log |
  125. Everything that spends meat is behind the approval token:
  126. ```bash
  127. kolibri token mint
  128. ```
  129. ## CLI
  130. ```bash
  131. # Account sessions
  132. kolibri login status
  133. kolibri login refresh --role main # interactive, password not echoed
  134. kolibri login clear --role all
  135. # Approval token
  136. kolibri token mint
  137. # Live reads
  138. kolibri status --role main --refresh
  139. kolibri inventory --role main --refresh
  140. kolibri shop --role mallbot --refresh
  141. kolibri pricegun --item 10881 --refresh
  142. # Daily routine — the morning run
  143. kolibri daily breakfast --role all # preview
  144. kolibri daily breakfast --role all \
  145. --execute --approval-token "$TOK" # live
  146. # Individual routines
  147. kolibri daily campfire --leaves 37191 --meat 128310
  148. kolibri daily hermit --permits 2 --clovers 3 --clover-sale 30000
  149. kolibri daily internet-shop
  150. kolibri daily meme-shop-read
  151. # Audit trail
  152. kolibri daily-audit --tail 20
  153. kolibri daily-audit --verify
  154. ```
  155. ## MCP
  156. `kolibri-mcp` serves MCP over HTTP on `127.0.0.1:8765` (local only). An AI client
  157. connects, the browser opens a consent page, and **you** choose accounts, rights and
  158. daily limits. The client only receives what you approved; see
  159. [docs/mcp-access.md](docs/mcp-access.md).
  160. ```bash
  161. kolibri-mcp # http://127.0.0.1:8765/mcp, consent code printed here
  162. kolibri-mcp grants list # approved clients with today's usage
  163. kolibri-mcp grants revoke ID # stop one client at once
  164. kolibri-mcp --stdio # read-only tools over stdio, no approval needed
  165. ```
  166. | Tool | What it does |
  167. |---|---|
  168. | `kol_status` / `kol_inventory` | Account reads |
  169. | `kol_price_summary` / `kol_price_recommendation` / `kol_underprice_preview` | Market reads |
  170. | `kol_run_daily_bridge` / `kol_daily_*` | Plans the daily routine without executing |
  171. | `kol_preview_purchase` / `kol_preview_transfer` | Validates a proposal without acting |
  172. | `kol_mall_buy` / `kol_meme_shop` | Buy under a price ceiling / run the meme shop |
  173. | `kol_shop_sales` / `kol_shop_buyers` / `kol_shop_price_suggestions` / `kol_reward_buyer` | Own-store sales, customers (loyalty ledger), price suggestions, reward a customer |
  174. | `kol_transfer` / `kol_send_message` / `kol_use_item` / `kol_reprice_shop` | Send to the other account / KMail / use items / change shop prices |
  175. | `kol_adventure_run_execute` / `kol_choice_chain_execute` | Bounded live adventures (right `adventure`) |
  176. Every write is two steps: preview returns a `planId`, the same call with that id executes once.
  177. Login management tools are not available to AI clients.
  178. ## Safety model
  179. This tool acts on a game account that holds real value, so the guardrails
  180. are structural rather than advisory.
  181. 1. **Reads are free, writes are gated.** An AI client needs a token you
  182. approved in the browser, with rights and per-day limits. The CLI and Desktop
  183. are yours and need none; under an AI harness the CLI asks for a
  184. confirmation at the real terminal before it writes (`kolibri agent-mode`).
  185. 2. **Credentials never appear in code.** Sessions live encrypted in the
  186. user's local app-data folder. The library reads them at runtime and
  187. keeps them inside the authenticated HTTP clients.
  188. 3. **Every write is auditable.** Actions land in an append-only journal
  189. where each row carries the SHA-256 hash of the row before it.
  190. `kolibri daily-audit --verify` reports the first tampered row.
  191. 4. **Bounded runs.** The runner stops after a configured number of
  192. choices or a configured duration, and never replays a request.
  193. 5. **Price discipline.** A purchase is submitted with the price the
  194. listing showed. If the price moved, KoL rejects it — KoLibri does not
  195. silently raise the bid.
  196. ## Limitations
  197. Honest about what does not work yet:
  198. - **Leaves cannot be bought.** The inflammable leaf only comes from the
  199. campfire, so a leaf shortage cannot be fixed by shopping.
  200. - **Free pulls need a clan store.** The Lucky Surprise Egg and the
  201. Infinite BACON machine are claimed from the storage, which requires the
  202. clan store password.
  203. - **The transfer path is separate.** Restocking the main account from
  204. the mallbot goes through its own preview/approval/commit flow rather
  205. than through the daily routine.
  206. - **The combat preview is an estimate.** Until the effect and modifier
  207. tracker is complete, the auto-combat preview does not account for every
  208. conditional buff.
  209. - **The daily shop limit is per account.** Running both accounts buys
  210. twice as much, but KoL's limit applies to each account separately.
  211. ## Development
  212. ```bash
  213. dotnet build KoLibri.slnx
  214. dotnet test tests/KoLibri.Core.Tests/KoLibri.Core.Tests.csproj
  215. dotnet pack src/KoLibri.Core/KoLibri.Core.csproj -c Release
  216. ```
  217. Repository: [grassmann-it/KoLibri](https://github.com/grassmann-it/KoLibri).
  218. ## License
  219. MIT — see [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.