# shim (Balanov/shim) > A tiny, local-first AI harness for people who prefer a terminal. It ships as one static binary with zero dependencies, has no TUI and no telemetry, and lets you wire any model, MCP servers and Agent Skills together through a natural-language CLI. - GitHub: https://github.com/Balanov/shim - GitHub.Locker page: https://github.locker/Balanov/shim - Stars: 431 - Language: Go - License: MIT - Last push: 2026-11-02 ## Questions and answers Written by GitHub.Locker from the README and the repository; check the README below for details. **Is it a model, or something that connects to models?** It's a harness, not a model or an inference engine. It connects to any model exposed through a supported HTTP API, while GGUF weights run through Ollama, LM Studio, llama.cpp or another compatible server. **What's the quickest way to install it?** Download the static binary for Windows, macOS or Linux from Releases and put it on your PATH, or build it from source with Go 1.25+ or the provided scripts. Then run shim help for the full command list. **Is it safe to let it run shell commands and MCP servers?** Not by itself. Shell commands and MCP servers run with your user's permissions, so use a container or VM for untrusted workloads. The default ask mode requires confirmation for writes, shell commands and MCP calls. **Does it phone home or send my sessions anywhere?** No telemetry. Network traffic happens only for the model calls, skill downloads, local discovery and MCP servers you set up, and sessions stay on disk as JSONL next to the config. **Can I fork it and ship it in my own product?** Yes. It's free and MIT-licensed, so you can fork it, modify it, embed it and ship it. **How do skills get loaded into a session?** Only names and descriptions go into the system prompt. Full SKILL.md instructions load on demand through loadskill from .shim/skills, .agents/skills, .claude/skills or a global skills folder. **How is it different from OpenCode, Goose or Aider?** Unlike OpenCode it has no TUI or server. Unlike Goose it has no daemon or desktop app. Unlike Aider it adds MCP, lazy skills and conversational management. **What is still on the roadmap?** Streaming token output and cancellation, OS-level sandbox profiles, OAuth helpers for remote MCP, context compaction, richer session export, and more language packs and provider tests. --- ## README (checked against GitHub 2026-11-04) Source: https://github.com/Balanov/shim/blob/main/README.md

Shim — Any model. Any tool. Just type.

A tiny, local-first AI harness for people who prefer a terminal.
One static binary. Zero dependencies. No TUI. No telemetry. MIT.

CI MIT license Platforms

## Why Shim? Model-agnostic coding agents are everywhere. Setting them up is still too hard: provider IDs, API endpoints, MCP JSON, skills directories, and a new interface for every tool. **Shim is the small adapter between you and all of that.** - **Talk or type commands.** A full scriptable CLI for experts; ordinary language for everyone else. - **Use a local mini-model as the command router.** It translates management requests into an allowlisted command. Mutating commands require confirmation. - **Bring any model API.** Native OpenAI-compatible and Anthropic adapters, plus presets for popular hosted and local providers. - **Bring any MCP server or Agent Skill.** MCP over stdio and Streamable HTTP; lazy `SKILL.md` loading from common directories. - **Stay light.** No Electron, Node, Python, Docker, database, background daemon, or UI framework. - **Own your state.** Plain JSON config and JSONL sessions. API keys come from environment variables and are never written to Shim's config. Measured on the maintainer's Windows machine for v0.1.0: **7.29 MiB** stripped binary and **9.96 ms median** process startup for `shim --version` over 30 runs. This is a local measurement, not a cross-platform performance guarantee. ## Install ### Download Get a static binary for Windows, macOS, or Linux from [Releases](https://github.com/Balanov/shim/releases), put it on your `PATH`, then run: ```sh shim setup shim ``` On PowerShell, use `.\shim.exe` when running the binary from the current directory. ### With Go Go 1.25+: ```sh go install github.com/Balanov/shim/cmd/shim@v0.1.0 shim setup ``` ### From source ```sh git clone https://github.com/Balanov/shim.git cd shim go test ./... go build -trimpath -ldflags="-s -w" -o shim ./cmd/shim ./shim setup ``` Windows also has `scripts/build.ps1`; Unix has `scripts/build.sh`. ## Two ways to use it ### Just talk ```text you › найди локальные модели ↳ /discover --add Run this command? [y/N] y you › show my tools ↳ /tools you › fix the failing tests in this repository ``` Shim has deterministic offline phrases for common English and Russian management commands. For other languages, assign a local model as the router: ```sh shim router use ollama/qwen3:4b ``` The router sees non-command chat text so it can distinguish configuration requests from agent tasks. Use a loopback model if you want that step to stay on your machine. **No model weights are bundled or silently downloaded**; that would defeat the tiny-binary goal. Your primary model handles ordinary conversation in whatever language it supports. ### Use the complete CLI ```sh # Local models: discover and configure all running servers shim model discover --add # Hosted models shim model add openrouter anthropic/claude-sonnet-4.5 --name claude --use shim model add openai gpt-5 --name gpt --use shim model add huggingface org/model --name hf --use # Any OpenAI-compatible endpoint shim model add custom my-model --name mine \ --base-url http://127.0.0.1:8000/v1 --use # One-shot agent run shim run --read-only "explain this repository" shim run --yes --verbose "fix the tests and verify the result" # Interactive terminal shim ``` Run `shim help` for the full command surface. ## Model providers | Preset | Adapter | Credential environment variable | |---|---|---| | `ollama` | OpenAI-compatible | None | | `lmstudio` | OpenAI-compatible | None | | `llamacpp` | OpenAI-compatible | None | | `openai` | OpenAI-compatible | `OPENAI_API_KEY` | | `openrouter` | OpenAI-compatible | `OPENROUTER_API_KEY` | | `anthropic` | Anthropic Messages | `ANTHROPIC_API_KEY` | | `gemini` | Gemini OpenAI-compatible endpoint | `GEMINI_API_KEY` | | `github` | GitHub Models | `GITHUB_TOKEN` | | `huggingface` | Hugging Face router | `HF_TOKEN` | | `custom` | OpenAI-compatible or Anthropic | Optional, configurable | “Any model” means any model exposed through a supported HTTP API. GGUF and other local weights run through Ollama, LM Studio, llama.cpp, or another compatible inference server; Shim is the harness, not an inference engine. PowerShell example: ```powershell $env:OPENROUTER_API_KEY = "..." shim model add openrouter your/model --name main --use shim model test main ``` For persistent environment variables, use your OS or shell's standard secret/configuration mechanism. Do not put keys in the project config. ## Skills Shim discovers `SKILL.md` in: - the global `skills/` directory next to Shim's config; - `.shim/skills/`; - `.agents/skills/`; - `.claude/skills/`. Only names and descriptions enter the system prompt. Full instructions load on demand through `load_skill`. ```sh shim skill add owner/repository shim skill add https://github.com/owner/repository shim skill add ./local/skill-or-collection shim skill list shim skill show name shim skill remove name ``` Skills are untrusted instructions. Review them before use, especially when they request shell or network access. ## MCP ```sh # Stdio server shim mcp add filesystem npx -y @modelcontextprotocol/server-filesystem . shim mcp tools filesystem shim mcp call filesystem list_allowed_directories '{}' # Streamable HTTP server shim mcp add internal https://mcp.example.com/mcp shim mcp list shim mcp remove filesystem ``` MCP tools are namespaced as `mcp__` and require confirmation in the default `ask` mode. HTTP headers and stdio environment variables can be added to the JSON config. Values support `${ENV_VAR}` expansion, so secrets can stay in the environment rather than in files. ## Permissions and safety Default mode is `ask`: - reading, listing, and searching workspace files: allowed; - writing/editing files, shell commands, and MCP calls: confirmation required; - file tools reject lexical traversal and symlink escapes from the workspace. ```sh shim permissions read-only # no writes, shell, or MCP shim permissions ask # confirm consequential actions shim permissions auto # allow the agent to act without prompts ``` For one run, prefer `--read-only` or `--yes` over changing the global default. **Shim is not an OS sandbox.** Shell commands and MCP servers run with your user's permissions. Workspace path checks do not contain a malicious process. Use a container, VM, or OS sandbox for untrusted workloads. Treat model output, repository text, skills, and MCP responses as untrusted data. ## Sessions and configuration ```sh shim session list shim session new shim run --resume SESSION_ID "continue" shim status shim doctor shim config path shim config show ``` Config is at the OS user-config location in `shim/config.json`; override it with `SHIM_CONFIG` or `--config`. Sessions are append-only JSONL next to it. Network traffic occurs only for explicit model calls, skill downloads, local discovery, and the MCP servers you configure. ## What Shim deliberately is not | Project | Strength | Shim's different bet | |---|---|---| | OpenCode | Full-featured provider-agnostic terminal workspace | No TUI/server surface; conversational setup and a tiny static binary | | Pi | Minimal, extensible coding-agent toolkit | Zero runtime dependencies and an allowlisted natural-language control layer | | Goose | Broad MCP-powered automation ecosystem | A smaller local-first control plane with no daemon or desktop app | | Aider | Git-native pair programming | General agent harness with MCP, lazy skills, and conversational management | Shim does not try to beat foundation-model vendors at their own agent UI. It makes heterogeneous models and tools easy to wire together and easy to fork. ## Development ```sh go test ./... go vet ./... go fmt ./... ``` The codebase uses only the Go standard library. See [Architecture](docs/ARCHITECTURE.md), [Contributing](CONTRIBUTING.md), and [Security](SECURITY.md). Русское введение: [README_RU.md](README_RU.md). ## Roadmap - streaming token output and cancellation polish; - OS-level sandbox profiles; - OAuth helpers for remote MCP; - context compaction and richer session export; - additional deterministic language packs and provider conformance tests. ## License [MIT](LICENSE). Fork it, modify it, embed it, ship it.