Balanov/shim

What it is

Shim is a single-binary, dependency-free AI agent harness for the terminal. It connects to models through supported HTTP APIs (OpenAI-compatible and Anthropic, with presets for Ollama, LM Studio, llama.cpp, OpenAI, OpenRouter, Gemini, GitHub Models, Hugging Face, and custom endpoints), loads MCP servers and Agent Skills, and exposes both a scriptable CLI and natural-language management commands.

The natural-language layer is an allowlisted command router: ordinary English and Russian management phrases are handled offline, or a local model can be assigned as router for other languages. Mutating commands require confirmation. Shim is not an inference engine, so GGUF and other local weights need an inference server such as Ollama or llama.cpp behind it.

Quick start

Download a static binary for Windows, macOS, or Linux from Releases, place it on PATH, then run the setup wizard and start the interactive terminal:

shim setup
shim

With Go 1.25+, install a pinned version instead:

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

To build 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

After setup, add a provider. API keys are read from environment variables, never stored in the config:

$env:OPENROUTER_API_KEY = "..."
shim model add openrouter your/model --name main --use
shim model test main

Local servers can be discovered automatically with shim model discover --add. Then either type into the interactive session or use one-shot runs such as shim run --read-only "explain this repository". Run shim help for the full command surface (command examples, provider table).

Permissions and safety

The default ask mode allows reading, listing, and searching workspace files, while file writes, shell commands, and MCP calls require confirmation. shim permissions read-only, ask, and auto change the global default; --read-only and --yes scope it to a single run. File tools reject lexical traversal and symlink escapes from the workspace.

Shim is not an OS sandbox: shell commands and MCP servers run with the user's permissions, and path checks do not contain a malicious process. Untrusted workloads should run in a container, VM, or OS sandbox, and model output, repository text, skills, and MCP responses should be treated as untrusted data (permissions). Skills themselves are untrusted instructions and should be reviewed before use, especially when they request shell or network access.

Configuration and sessions

Config lives at the OS user-config location in shim/config.json, overridable with SHIM_CONFIG or --config; sessions are append-only JSONL files next to it. shim session list, shim session new, and shim run --resume SESSION_ID manage them, while shim status, shim doctor, and shim config show inspect state. Network traffic only occurs for explicit model calls, skill downloads, local discovery, and configured MCP servers.

MCP servers can be registered over stdio or Streamable HTTP, and their tools are namespaced as mcp_<server>_<tool>; HTTP headers and stdio environment variables support ${ENV_VAR} expansion. Skills are discovered in the global skills/ directory, .shim/skills/, .agents/skills/, and .claude/skills/, with only names and descriptions entering the prompt and full instructions loaded on demand.

Constraints

Shim is written in Go using only the standard library, and the README reports a local measurement of a 7.29 MiB stripped v0.1.0 binary and 9.96 ms median startup for shim --version over 30 runs on the maintainer's Windows machine; this is not a cross-platform performance guarantee. Streaming token output and cancellation are still listed as roadmap items, along with OS-level sandbox profiles and OAuth helpers for remote MCP. The project is MIT licensed.

HotRepo's take

Shim entered HotRepo's new-project snapshot on 2026-11-02 with 117 stars gained in a roughly four-hour window and no forks; no GitHub daily-rank record is available. That is a small, early signal from a single observation, so it says little about adoption. The more concrete distinction in the README is the design bet: a tiny static binary with no TUI, daemon, or runtime dependencies, an allowlisted natural-language control layer on top of a scriptable CLI, and provider/MCP/skill adapters rather than a full terminal workspace.