How to Set Up Shim for Local-First AI Coding Agents

What Is Shim?

Shim is a small, local-first AI agent harness designed for terminal users. It provides a common interface for connecting supported model APIs, Agent Skills, and Model Context Protocol servers without requiring a desktop application, background daemon, database, Docker, Node.js, or Python.

Shim is distributed as a static binary and uses plain JSON for configuration and append-only JSONL files for sessions. API keys are read from environment variables rather than written to Shim’s configuration.

Shim is a harness, not an inference engine. Local model weights must run through an inference server such as Ollama, LM Studio, llama.cpp, or another compatible service. Hosted models must be exposed through a supported HTTP API.

Key Features

• Conversational and explicit control: Type ordinary-language management requests or use the complete scriptable CLI.
• Local command routing: An optional local mini-model can translate management requests into allowlisted Shim commands.
• Multiple model providers: Shim supports OpenAI-compatible APIs, Anthropic Messages, local provider presets, and custom endpoints.
• Agent Skills: It discovers SKILL.md files and loads their full instructions only when needed.
• MCP integration: Connect stdio or Streamable HTTP MCP servers and expose their tools to the agent.
• Permission controls: Choose read-only, confirmation-based, or automatic execution.
• Portable state: Configuration and sessions use ordinary JSON and JSONL files.
• No telemetry: Network activity is limited to explicit model calls, skill downloads, local discovery, and configured MCP servers.

Install Shim

Option 1: Download a Release

Download the static binary for Windows, macOS, or Linux from the Shim releases page. Put the executable on your system PATH, and then initialize Shim:

shim setup
shim

When running the downloaded executable directly from the current directory in PowerShell, use .\shim.exe.

Option 2: Install with Go

If Go 1.25 or newer is available, install Shim with:

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

Option 3: Build from Source

Clone the repository, run its tests, and build the binary:

git clone https://github.com/Balanov/shim.git
cd shim
go test ./...
go build -trimpath -ldflags="-s -w" -o shim ./cmd/shim
./shim setup

The repository also includes scripts/build.ps1 for Windows and scripts/build.sh for Unix systems.

Connect a Model

Discover Local Model Servers

If Ollama, LM Studio, llama.cpp, or another compatible local server is already running, ask Shim to discover and configure available models:

shim model discover --add

No model weights are bundled with Shim or downloaded silently. The model server remains responsible for running the local model.

Add a Hosted Provider

Shim includes presets for OpenAI, OpenRouter, Anthropic, Gemini, GitHub Models, Hugging Face, and several local providers. Set the provider’s credential in your environment before adding a model.

For example, PowerShell users can configure OpenRouter like this:

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

Other credential variables include OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, GITHUB_TOKEN, and HF_TOKEN. Use your operating system or shell’s standard secret-management mechanism for persistent credentials. Do not place API keys in Shim’s project configuration.

Examples for adding hosted models include:

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

Add a Custom Endpoint

For any supported OpenAI-compatible endpoint, supply its base URL and model identifier:

shim model add custom my-model --name mine \
  --base-url http://127.0.0.1:8000/v1 --use

The custom provider can use an OpenAI-compatible or Anthropic adapter. Credentials are optional and configurable for custom services.

Run Your First Agent Task

Use a One-Shot Run

The safest way to inspect a repository is a read-only run:

shim run --read-only "explain this repository"

For a task that needs to edit files and execute verification commands, use --yes to approve actions for that run and --verbose for additional output:

shim run --yes --verbose "fix the tests and verify the result"

Use --yes only when you trust the workspace, model, and requested task.

Start the Interactive Terminal

Run Shim without a subcommand to start an interactive session:

shim

You can then enter an agent request such as:

fix the failing tests in this repository

Run shim help to inspect the full command surface.

Control Shim with Ordinary Language

Shim recognizes deterministic offline phrases for common English and Russian management operations. For other languages or more flexible interpretation, configure a model as the command router:

shim router use ollama/qwen3:4b

The router receives non-command chat text and determines whether it represents a configuration request or an ordinary agent task. When it proposes a mutating command, Shim requests confirmation before running it.

Use a loopback model endpoint if routing must remain on your machine. The router only manages command interpretation; the selected primary model handles ordinary conversation in the languages it supports.

Add Agent Skills

Shim discovers SKILL.md files in the global skills/ directory beside its configuration and in the workspace directories .shim/skills/, .agents/skills/, and .claude/skills/.

Only skill names and descriptions are initially added to the system prompt. Full instructions are loaded on demand through load_skill, reducing unnecessary prompt content.

Add skills from a repository reference, GitHub URL, or local path:

shim skill add owner/repository
shim skill add https://github.com/owner/repository
shim skill add ./local/skill-or-collection

Inspect and manage installed skills with:

shim skill list
shim skill show name
shim skill remove name

Skills are untrusted instructions. Review them before use, particularly when they request shell execution or network access.

Connect MCP Servers

Add a Stdio Server

The following example registers the MCP filesystem server for the current directory, lists its tools, and calls one tool directly:

shim mcp add filesystem npx -y @modelcontextprotocol/server-filesystem .
shim mcp tools filesystem
shim mcp call filesystem list_allowed_directories '{}'

Add a Streamable HTTP Server

Register a remote Streamable HTTP endpoint by giving it a name and URL:

shim mcp add internal https://mcp.example.com/mcp

List or remove configured servers with:

shim mcp list
shim mcp remove filesystem

MCP tools are exposed under names such as mcp_filesystem_list_allowed_directories. In the default permission mode, MCP calls require confirmation.

HTTP headers and stdio environment variables can be added through Shim’s JSON configuration. Values support ${ENV_VAR} expansion, allowing secrets to remain in the environment instead of configuration files.

Choose a Permission Mode

Shim defaults to ask mode. Reading, listing, and searching workspace files are allowed, while file writes, edits, shell commands, and MCP calls require confirmation.

Select a global permission policy with:

shim permissions read-only
shim permissions ask
shim permissions auto

• read-only: Disables writes, shell commands, and MCP calls.
• ask: Requests confirmation for consequential operations.
• auto: Allows the agent to act without confirmation prompts.

For temporary changes, prefer shim run --read-only or shim run --yes instead of modifying the global default.

Shim is not an operating-system sandbox. Shell commands and MCP servers run with your user account’s permissions. Use a container, virtual machine, or OS sandbox for untrusted workloads.

Shim’s file tools reject lexical path traversal and symlink escapes from the workspace, but these checks cannot contain a malicious process. Treat model output, repository content, skills, and MCP responses as untrusted data.

Manage Sessions and Configuration

Inspect sessions, start a clean session, or continue an earlier one:

shim session list
shim session new
shim run --resume SESSION_ID "continue"

Use the diagnostic and configuration commands when troubleshooting:

shim status
shim doctor
shim config path
shim config show

The main configuration file is shim/config.json under the operating system’s user-config location. Override the path with the SHIM_CONFIG environment variable or the --config option. Session records are stored as append-only JSONL files beside the configuration.

Advanced Tips

1. Start in read-only mode. Use --read-only for repository analysis before allowing edits or command execution.
2. Test model configurations. After adding a provider, run shim model test NAME to verify connectivity and credentials.
3. Keep routing local. Assign a loopback model as the router when natural-language command classification must remain on your computer.
4. Use environment expansion for MCP secrets. Reference ${ENV_VAR} in configuration rather than storing secret values directly.
5. Prefer per-run permissions. Use --read-only and --yes for individual tasks instead of leaving the global policy in auto.
6. Review third-party instructions. Inspect downloaded skills and consider MCP server behavior before granting shell, filesystem, or network access.
7. Run diagnostics first. Commands such as shim status and shim doctor can help identify configuration problems before an agent run.

Conclusion

Shim provides a compact terminal layer for connecting supported model APIs, Agent Skills, and MCP servers. Its static binary, plain-file configuration, environment-based credentials, and explicit permission modes make it suitable for users who want a lightweight and inspectable AI agent workflow. Begin with a read-only task, verify each provider or tool, and grant broader permissions only when necessary.