# Klyrune Klyrune is an agentic terminal CLI for controlled software work. It can inspect a project, edit files, run commands, verify changes, recover from failures, and keep the conversation tied to the real state of your workspace. It ships with **Gateway Polyvor Labs** support out of the box and also works with OpenAI, Anthropic, DeepSeek, 9Router, and custom OpenAI-compatible or Anthropic-compatible providers. Built by **Polyvor Labs**. ## Highlights - **Project-aware agent loop**: inspect, patch, verify, repair, and summarize. - **Safe file tools**: read, write, edit, append, delete, apply patches, grep, glob, and list directories. - **Shell execution**: run build, test, git, package-manager, and diagnostic commands from the workspace. - **MCP support**: connect stdio or Streamable HTTP MCP servers and expose their tools, resources, and prompts. - **Multi-provider AI**: Gateway Polyvor Labs, OpenAI, Anthropic, DeepSeek, 9Router, and custom providers. - **Plan and build modes**: plan mode is read-only; build mode can modify files and run tools. - **Persistent sessions**: resume, archive, delete, and switch project conversations. - **Memory and skills**: project memory plus `SKILLS.md` or `.klyrune/skills/*/SKILL.md` instructions. - **Permissions**: approve tool calls once, always, or reject them. - **Checkpoints**: automatic pre-edit snapshots with diff and rollback commands. - **Web tools**: web search and fetch through Gateway Polyvor Labs or a configured web provider. ## Install ```bash npm install -g klyrune@latest ``` Requirements: - Node.js `>=20.3` - Linux, macOS, or Windows - Git Bash recommended on Windows Check your install: ```bash klyrune --version klyrune doctor ``` ## Quick Start Start Klyrune in a project: ```bash cd your-project klyrune ``` Run a one-shot task: ```bash klyrune "add tests for the parser" klyrune -y "install dependencies and run the build" ``` Useful first commands inside the REPL: ```text /auth /model /provider /init /plan /build ``` ## Built-In Provider Klyrune includes Gateway Polyvor Labs as the default provider. - Register at `https://gateway.polyvorlabs.com` - Create an API key - Add it in Klyrune with `/auth ` Environment setup is also supported: ```bash export KLYRUNE_PROVIDER=gateway export KLYRUNE_GATEWAY_URL=https://gateway.polyvorlabs.com export KLYRUNE_API_KEY=gw_sk_your_key export KLYRUNE_MODEL=ds/deepseek-v4-flash ``` ## Providers Switch providers from the REPL: ```text /provider gateway /provider openai /provider anthropic /provider deepseek /provider 9router /provider add ``` Supported provider formats: - **OpenAI chat completions**: `POST {base}/v1/chat/completions` - **OpenAI responses API** - **Anthropic messages**: `POST {base}/v1/messages` - **Custom path** for compatible gateways and routers Custom providers keep their own base URL, format, optional path, and API key. ## MCP Servers Klyrune can connect to Model Context Protocol servers and expose their capabilities to the agent. Add a stdio MCP server: ```text /mcp add fs --stdio npx -y @modelcontextprotocol/server-filesystem . ``` Add an HTTP MCP server: ```text /mcp add docs --http https://example.com/mcp --header Authorization=Bearer_$MCP_TOKEN ``` Inspect MCP status and capabilities: ```text /mcp list /mcp doctor /mcp tools /mcp resources /mcp prompts ``` Manage configured MCP servers: ```text /mcp off fs /mcp on fs /mcp rm fs ``` MCP notes: - MCP tool names are exposed as safe function names like `mcp__`. - Read-only MCP helpers are allowed automatically. - Dynamic MCP tools ask for permission unless you add an allow rule. - Secrets in MCP env/header config are redacted in `/mcp list`. - Environment references such as `$TOKEN` and `${TOKEN}` are expanded at runtime. Example allow rule: ```text /allow mcp_fs_*:true ``` ## Permissions Klyrune asks before running tools that can affect your system, such as shell commands and dynamic MCP tools. Permission options: - **allow once**: approve only the current call. - **allow always**: save a persistent rule. - **reject**: block the call. Examples: ```text /allow bash:npm* /allow bash:true /allow deny:bash:rm* /allow mcp_fs_*:true ``` ## Checkpoints Before file-changing tools run, Klyrune saves a local checkpoint under `.klyrune/checkpoints/`. ```bash klyrune checkpoints klyrune diff klyrune rollback ``` Rollback creates its own undo checkpoint first, so rollback changes can also be reviewed. ## Sessions, Memory, And Skills Klyrune stores project-local conversation state in `.klyrune/`. ```text /sessions /resume /archive /delete /new ``` Project memory: ```text /memory /memory consolidate ``` Project instructions: - `AGENTS.md` is loaded automatically. - `SKILLS.md` is loaded automatically. - `.klyrune/skills//SKILL.md` adds project skills. ## Subagents Subagents live in `.klyrune/agents/.md`. ```markdown --- name: Reviewer description: Reviews code for bugs tools: read_file, grep, glob --- Review diffs carefully. Never edit files. ``` Use them from the REPL: ```text /agent /agent create /agent default ``` When a subagent declares tools, Klyrune restricts it to that tool list. ## Web Search And Fetch Klyrune includes `web_search` and `web_fetch` tools. They work with any chat provider when a web endpoint/key is configured. Resolution order: 1. `KLYRUNE_WEB_URL` / `KLYRUNE_WEB_KEY` 2. `NINEROUTER_URL` / `NINEROUTER_KEY` 3. `/webkey ` 4. Chat API key that looks like a Gateway key (`gw_sk_...`) 5. Gateway or 9Router chat provider ## Configuration Config file: ```text ~/.config/klyrune/config.json ``` Environment variables: ```bash KLYRUNE_PROVIDER=gateway KLYRUNE_GATEWAY_URL=https://gateway.polyvorlabs.com KLYRUNE_API_KEY=gw_sk_your_key KLYRUNE_MODEL=ds/deepseek-v4-flash KLYRUNE_WEB_URL= KLYRUNE_WEB_KEY= NINEROUTER_URL= NINEROUTER_KEY= ``` Klyrune also loads `.env` from the current directory. Existing environment variables take priority. ## REPL Commands | Command | Description | | --- | --- | | `/help` | Show command help | | `/model ` | Switch model | | `/models` | Pick a model from the provider list | | `/provider [add\|rm]` | Pick or manage providers | | `/mcp [list\|add\|rm\|on\|off\|doctor\|tools\|resources\|prompts]` | Manage MCP servers | | `/agent [create\|rm\|default]` | Pick or manage subagents | | `/add ` | Pin files or directories into context | | `/drop ` | Remove a pinned context file | | `/context` | List pinned context files | | `/skills` | List project skills | | `/memory` | Show project memory | | `/allow ` | Add a permission rule | | `/stop` | Stop background shell processes started by tools | | `/plan` | Switch to read-only planning mode | | `/build` | Switch to full build mode | | `/usage` | Show usage and rate-limit data | | `/auth [key]` | Show or set API key | | `/webkey [key]` | Show or set web key | | `/url [base]` | Show or set provider base URL | | `/new` | Clear current conversation | | `/archive` | Archive current session and exit | | `/delete` | Delete current session and exit | | `/exit` | Quit | Typing `/` opens command suggestions. Tab cycles major UI panes. ## Advanced ### Bash Timeouts The `bash` tool has a 10 minute default timeout. ```bash export KLYRUNE_BASH_TIMEOUT_SECONDS=900 export KLYRUNE_BASH_INACTIVITY_TIMEOUT_SECONDS=300 ``` ### Benchmark Mode Klyrune includes a headless benchmark profile: ```bash klyrune bench "fix the task" ``` Benchmark mode is intentionally sterile, bundled persona/plugin behavior is disabled, tool usage is concise, and the loop prioritizes fast inspection, targeted edits, verifier-driven repair, and finalization before timeout. Useful environment overrides: ```bash KLYRUNE_BENCH_DEADLINE_SECONDS=570 KLYRUNE_BENCH_FINALIZATION_SECONDS=90 KLYRUNE_BENCH_MAX_ITERATIONS=40 KLYRUNE_TRAJECTORY=/tmp/klyrune-trajectory.jsonl ``` ## License MIT