localexec

Getting started

Install the server, create the model it expects, prepare one project and register localexec with Claude Code.

Requirements

  • Python 3.11 or newer, and uv.
  • git. Every project you use localexec in must be a git repository.
  • Ollama, running on the same machine, with a code model.
  • Claude Code, or any MCP client that can start a stdio server.
  • Node.js, only if you want to try the MCP Inspector.

Install the server

Clone or download the repository and run these commands in its folder. Keep the folder where it is: Claude Code starts the server from there.

uv sync
uv run pytest -q

The tests use a mocked Ollama, so they pass without a GPU.

Create the model

The defaults expect an Ollama model named qwen-coder-16k with a 16,384-token context window. It was developed with qwen2.5-coder:14b on a 12 GB GPU. Save this as Modelfile:

FROM qwen2.5-coder:14b
PARAMETER num_ctx 16384
ollama create qwen-coder-16k -f Modelfile
ollama list

To use a different model, set ollama_model and num_ctx in your project config. See Configuration.

Test it without Claude

This starts the server over real MCP stdio and runs one task against a fake Ollama endpoint. It lists the eight tools, applies an edit, reverts it and prints each result.

uv run python scripts/smoke_client.py

Prepare a project

In the project where Claude will work, copy the example config and edit its checks to the commands that should pass after every change. Replace <install-dir> with the folder from the first step.

# macOS and Linux
cp <install-dir>/.localexec.example.json .localexec.json

# Windows PowerShell
Copy-Item <install-dir>\.localexec.example.json .localexec.json

Commit or ignore the config. implement_task refuses to run while tracked files outside files_to_edit have uncommitted changes. Commit .localexec.json, or add it to .gitignore.

Then give Claude the workflow. The repository includes a snippet for your project's CLAUDE.md:

# macOS and Linux
cat <install-dir>/CLAUDE.snippet.md >> CLAUDE.md

# Windows PowerShell
Get-Content <install-dir>\CLAUDE.snippet.md | Add-Content CLAUDE.md

Register with Claude Code

claude mcp add --scope user localexec -- uv run --project <install-dir> localexec-mcp
claude mcp list

claude mcp list should show localexec as connected. Inside Claude Code, /mcp lists its eight tools. Options go first, then the name, then --, then the server command. --scope user makes it available in every project. Remove it with claude mcp remove localexec.

Use --project, not --directory. --directory changes the working directory, and the server finds your project from the directory Claude Code launches it in.

If project detection ever picks the wrong folder, register per project and name the root explicitly:

claude mcp add localexec -e LOCALEXEC_ROOT=<project-dir> -- uv run --project <install-dir> localexec-mcp

Run a first task

Open Claude Code in your project and ask it to run the status tool. A healthy result looks like this:

{"status":"ok","project":"my-project","model":"qwen-coder-16k","checks":["pytest"],"model_installed":true,"model_loaded":false,"tasks":0}

model_loaded is false until the first task, because Ollama loads the model on demand. Then ask Claude to plan a small change and delegate each step with implement_task. Using it with Claude explains what a good task looks like.

Slow check suites

Claude Code allows very long tool calls (MCP_TOOL_TIMEOUT), but a call in the main conversation can be moved to a background task after about two minutes (CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS; set it to 0 to disable). A full test suite can trigger that. Pick fast checks per task with the checks parameter, and use scoped checks that run only on changed files.