Skip to content
Back to search

shim

Tiny local-first AI harness: any model, MCP and Agent Skills, natural-language CLI. Zero dependencies. MIT.

Safety scan

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

Checked today

Check it deeper on your machine

It has changed since its scan on 12 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Balanov/shim with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Balanov/shim'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/balanov--shim/badge.svg)](/listings/balanov--shim)

HTML

<a href="/listings/balanov--shim"><img src="/api/listings/balanov--shim/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.

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:

shim setup
shim

On PowerShell, use `.\shim.exe` when running the binary from the current directory.

With Go

Go 1.25+:

go install github.com/Balanov/shim/cmd/shim@v0.1.0
shim setup

From source

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`.

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 · 257 lines
  1. <div align="center">
  2. <img src="docs/readme/hero.png" alt="SHIM — any model, any tool, just type. One small adapter between the terminal, models, MCP, Skills and tools." width="100%">
  3. <p><strong>A tiny, local-first AI harness for people who prefer a terminal.</strong></p>
  4. <p>One static binary. Zero dependencies. No TUI. No telemetry. MIT.</p>
  5. <p>
  6. <a href="#install">Install</a> ·
  7. <a href="#two-ways-to-use-it">Two ways to use it</a> ·
  8. <a href="docs/ARCHITECTURE.md">Architecture</a> ·
  9. <a href="#permissions-and-safety">Permissions</a> ·
  10. <a href="https://balanov.pro/shim/">Website</a> ·
  11. <a href="README_RU.md">Русский</a>
  12. </p>
  13. <p>
  14. <a href="https://github.com/Balanov/shim/actions/workflows/ci.yml"><img src="https://github.com/Balanov/shim/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  15. <a href="https://github.com/Balanov/shim/releases/latest"><img src="https://img.shields.io/github/v/release/Balanov/shim" alt="Latest release"></a>
  16. <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"></a>
  17. <a href="go.mod"><img src="https://img.shields.io/badge/Go-1.25%2B-00ADD8?logo=go&logoColor=white" alt="Go 1.25+"></a>
  18. </p>
  19. </div>
  20. <div align="center">
  21. <img src="docs/readme/demo.gif" alt="SHIM documented CLI example: a Russian request becomes an allowlisted discovery command, followed by confirmation and a tools command" width="100%">
  22. <p><sub>The documented CLI flow from <a href="#two-ways-to-use-it">“Two ways to use it”</a>. Natural language becomes an allowlisted command; mutating commands require confirmation.</sub></p>
  23. </div>
  24. ## Why Shim?
  25. 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.
  26. **Shim is the small adapter between you and all of that.**
  27. - **Talk or type commands.** A full scriptable CLI for experts; ordinary language for everyone else.
  28. - **Use a local mini-model as the command router.** It translates management requests into an allowlisted command. Mutating commands require confirmation.
  29. - **Bring any model API.** Native OpenAI-compatible and Anthropic adapters, plus presets for popular hosted and local providers.
  30. - **Bring any MCP server or Agent Skill.** MCP over stdio and Streamable HTTP; lazy `SKILL.md` loading from common directories.
  31. - **Stay light.** No Electron, Node, Python, Docker, database, background daemon, or UI framework.
  32. - **Own your state.** Plain JSON config and JSONL sessions. API keys come from environment variables and are never written to Shim's config.
  33. 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.
  34. <div align="center">
  35. <img src="docs/readme/architecture.png" alt="SHIM request flow from terminal through router and allowlist to the agent, with a separate permission gate for consequential actions" width="100%">
  36. <p><sub>Router output is data, not authority. Every consequential tool crosses the same permission gate. <a href="docs/ARCHITECTURE.md">Full architecture and invariants</a>.</sub></p>
  37. </div>
  38. ## Install
  39. ### Download
  40. Get a static binary for Windows, macOS, or Linux from [Releases](https://github.com/Balanov/shim/releases), put it on your `PATH`, then run:
  41. ```sh
  42. shim setup
  43. shim
  44. ```
  45. On PowerShell, use `.\shim.exe` when running the binary from the current directory.
  46. ### With Go
  47. Go 1.25+:
  48. ```sh
  49. go install github.com/Balanov/shim/cmd/shim@v0.1.0
  50. shim setup
  51. ```
  52. ### From source
  53. ```sh
  54. git clone https://github.com/Balanov/shim.git
  55. cd shim
  56. go test ./...
  57. go build -trimpath -ldflags="-s -w" -o shim ./cmd/shim
  58. ./shim setup
  59. ```
  60. Windows also has `scripts/build.ps1`; Unix has `scripts/build.sh`.
  61. ## Two ways to use it
  62. ### Just talk
  63. ```text
  64. you › найди локальные модели
  65. ↳ /discover --add
  66. Run this command? [y/N] y
  67. you › show my tools
  68. ↳ /tools
  69. you › fix the failing tests in this repository
  70. ```
  71. Shim has deterministic offline phrases for common English and Russian management commands. For other languages, assign a local model as the router:
  72. ```sh
  73. shim router use ollama/qwen3:4b
  74. ```
  75. 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.
  76. ### Use the complete CLI
  77. ```sh
  78. # Local models: discover and configure all running servers
  79. shim model discover --add
  80. # Hosted models
  81. shim model add openrouter anthropic/claude-sonnet-4.5 --name claude --use
  82. shim model add openai gpt-5 --name gpt --use
  83. shim model add huggingface org/model --name hf --use
  84. # Any OpenAI-compatible endpoint
  85. shim model add custom my-model --name mine \
  86. --base-url http://127.0.0.1:8000/v1 --use
  87. # One-shot agent run
  88. shim run --read-only "explain this repository"
  89. shim run --yes --verbose "fix the tests and verify the result"
  90. # Interactive terminal
  91. shim
  92. ```
  93. Run `shim help` for the full command surface.
  94. ## Model providers
  95. | Preset | Adapter | Credential environment variable |
  96. |---|---|---|
  97. | `ollama` | OpenAI-compatible | None |
  98. | `lmstudio` | OpenAI-compatible | None |
  99. | `llamacpp` | OpenAI-compatible | None |
  100. | `openai` | OpenAI-compatible | `OPENAI_API_KEY` |
  101. | `openrouter` | OpenAI-compatible | `OPENROUTER_API_KEY` |
  102. | `anthropic` | Anthropic Messages | `ANTHROPIC_API_KEY` |
  103. | `gemini` | Gemini OpenAI-compatible endpoint | `GEMINI_API_KEY` |
  104. | `github` | GitHub Models | `GITHUB_TOKEN` |
  105. | `huggingface` | Hugging Face router | `HF_TOKEN` |
  106. | `custom` | OpenAI-compatible or Anthropic | Optional, configurable |
  107. “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.
  108. PowerShell example:
  109. ```powershell
  110. $env:OPENROUTER_API_KEY = "..."
  111. shim model add openrouter your/model --name main --use
  112. shim model test main
  113. ```
  114. For persistent environment variables, use your OS or shell's standard secret/configuration mechanism. Do not put keys in the project config.
  115. ## Skills
  116. Shim discovers `SKILL.md` in:
  117. - the global `skills/` directory next to Shim's config;
  118. - `.shim/skills/`;
  119. - `.agents/skills/`;
  120. - `.claude/skills/`.
  121. Only names and descriptions enter the system prompt. Full instructions load on demand through `load_skill`.
  122. ```sh
  123. shim skill add owner/repository
  124. shim skill add https://github.com/owner/repository
  125. shim skill add ./local/skill-or-collection
  126. shim skill list
  127. shim skill show name
  128. shim skill remove name
  129. ```
  130. Skills are untrusted instructions. Review them before use, especially when they request shell or network access.
  131. ## MCP
  132. ```sh
  133. # Stdio server
  134. shim mcp add filesystem npx -y @modelcontextprotocol/server-filesystem .
  135. shim mcp tools filesystem
  136. shim mcp call filesystem list_allowed_directories '{}'
  137. # Streamable HTTP server
  138. shim mcp add internal https://mcp.example.com/mcp
  139. shim mcp list
  140. shim mcp remove filesystem
  141. ```
  142. MCP tools are namespaced as `mcp_<server>_<tool>` 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.
  143. ## Permissions and safety
  144. Default mode is `ask`:
  145. - reading, listing, and searching workspace files: allowed;
  146. - writing/editing files, shell commands, and MCP calls: confirmation required;
  147. - file tools reject lexical traversal and symlink escapes from the workspace.
  148. ```sh
  149. shim permissions read-only # no writes, shell, or MCP
  150. shim permissions ask # confirm consequential actions
  151. shim permissions auto # allow the agent to act without prompts
  152. ```
  153. For one run, prefer `--read-only` or `--yes` over changing the global default.
  154. **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.
  155. ## Sessions and configuration
  156. ```sh
  157. shim session list
  158. shim session new
  159. shim run --resume SESSION_ID "continue"
  160. shim status
  161. shim doctor
  162. shim config path
  163. shim config show
  164. ```
  165. 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.
  166. ## What Shim deliberately is not
  167. | Project | Strength | Shim's different bet |
  168. |---|---|---|
  169. | OpenCode | Full-featured provider-agnostic terminal workspace | No TUI/server surface; conversational setup and a tiny static binary |
  170. | Pi | Minimal, extensible coding-agent toolkit | Zero runtime dependencies and an allowlisted natural-language control layer |
  171. | Goose | Broad MCP-powered automation ecosystem | A smaller local-first control plane with no daemon or desktop app |
  172. | Aider | Git-native pair programming | General agent harness with MCP, lazy skills, and conversational management |
  173. 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.
  174. ## Development
  175. ```sh
  176. go test ./...
  177. go vet ./...
  178. go fmt ./...
  179. ```
  180. 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).
  181. ## Roadmap
  182. - streaming token output and cancellation polish;
  183. - OS-level sandbox profiles;
  184. - OAuth helpers for remote MCP;
  185. - context compaction and richer session export;
  186. - additional deterministic language packs and provider conformance tests.
  187. ## License
  188. [MIT](LICENSE). Fork it, modify it, embed it, ship it.

Ratings and comments

Sign in to rate this skill.

Sign in

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