alc

algocline

Research-grade reasoning for your LLM — as Pure Lua you can read, edit, and ship.

UCB1 exploration, self-reflection, multi-agent debate, chain-of-verification — each strategy is a single Lua file. Install with cargo install, customize anything, no framework lock-in.

What it does

LLMs are single-shot by default. Ask a question, get one answer, hope it's right. Research papers describe techniques that do better — iterating, scoring, selecting — but using them today means Python, framework lock-in, and API key management.

algocline makes these techniques immediately usable. Each algorithm is a Pure Lua file (100-350 lines) that runs inside your existing MCP host. No infrastructure. No setup beyond alc init.

Human ──→ LLM (MCP host) ──→ algocline ──→ Algorithm (Lua) ──→ alc.llm() ──→ back to LLM
                                                                    ↑              │
                                                                    └──────────────┘
                                                                   (loop until done)

Use existing algorithms with one call. Build your own by writing Lua. Share them via Git.

When to use

What you want to do	What happens	Strategy
Catch what your code review missed	Draft → self-critique → revise. Found that std::fs::write is non-atomic (crash = data loss) after the first draft said "no issues"	reflect
Make design decisions structurally, not by gut	Advocate, critic, and pragmatist debate. Resolved "do we need log rotation?" → "no, but add a display limit" in 4 rounds	panel
Fact-check LLM claims before trusting them	Auto-generates verification questions → checks each one. Escalated a path traversal from medium to high severity after confirming PathBuf::join() does zero validation	cove
Break down a complex problem step by step	Builds reasoning chain incrementally. Structured Vec vs HashMap trade-offs into cache locality → memory overhead → API ergonomics	cot
Pick the best option from multiple candidates	Scores each candidate on your criteria, pairwise comparison	rank
Get a reliable answer, not a lucky one	Generates N answers → majority vote picks the most consistent one	sc

Why algocline

Approach	Limitation
Prompt engineering	Single-shot. No iteration, no scoring, no selection
DSPy / LangGraph	Python infra. Pip install. API keys. Framework lock-in
algocline	Zero infra. Pure Lua. Runs inside your existing MCP host. Use research-grade algorithms today, or write your own

Quick start

1. Install

cargo install algocline

2. Initialize packages

alc init

This downloads the bundled package collection (UCB1, chain-of-thought, self-consistency, etc.) into ~/.algocline/packages/. Run alc init --force to overwrite existing packages.

It also distributes alc.d.lua — LuaCats type definitions for all alc.* StdLib functions — to ~/.algocline/types/alc.d.lua. This enables editor completion in any editor backed by lua-language-server. If .luarc.json is not present in the current directory, a setup tip is printed.

Note: If you skip this step, packages are auto-installed on first alc_advice call via MCP. But running alc init upfront is recommended for faster first use and offline availability.

3. Add to your MCP config

By default, alc runs as an MCP stdio server — it is designed to be launched by an MCP client such as Claude Code, not invoked directly from a shell. For one-shot maintenance tasks, use the alc init and alc update subcommands. For ad-hoc shell access to algocline MCP tools, set up an agent-block harness that starts alc as a child process and calls the MCP server directly; running plain alc from a terminal will start the server in the foreground waiting for an MCP client connection. Run alc --help for a summary of available subcommands.

Add algocline as an MCP server in your host's configuration (e.g. Claude Code's ~/.claude.json, Cursor's MCP settings, etc.):

{
  "mcpServers": {
    "algocline": {
      "command": "alc"
    }
  }
}

Add an env object only when you need to set one of the environment variables documented below.

After adding the config, restart your MCP host session so it picks up the new server.

Environment variables