# Local LLM Delegator

Local LLM Delegator is an installable Codex and Claude Code plugin that shifts
small coding implementations to a cheaper model while the primary agent keeps
architecture, scoping, review, and final acceptance.

The bundle contains:

- A dependency-free Python MCP server with `propose_patch` and `apply_patch`.
- A delegation skill that triggers before the primary model reads broad source
  context.
- Templates for Hugging Face GPT-OSS, llama.cpp, and OpenRouter.
- Exact-patch SHA-256 approval, path limits, stale-source checks, validation,
  partial-failure restoration, and one bounded repair.

## Requirements

- Python 3.11+
- POSIX `sh` and the `patch` utility
- Codex with plugin support or Claude Code
- An OpenAI-compatible model endpoint

No Python package installation is required.

## Install in Codex

Clone this repository, add it as a local marketplace, and install the plugin:

```sh
git clone https://github.com/tushrv/local-llm-delegator.git
codex plugin marketplace add ./local-llm-delegator
codex plugin add local-llm-delegator@local-llm-delegator
```

Restart Codex and begin a new thread so the skill and MCP tools are discovered.

## Install in Claude Code

Add the cloned repository as a marketplace and install the plugin:

```text
/plugin marketplace add /absolute/path/to/local-llm-delegator
/plugin install local-llm-delegator@local-llm-delegator
```

Restart Claude Code after installation.

## Configure a project

From the target repository, create a policy:

```sh
python3 /absolute/path/to/local-llm-delegator/plugins/local-llm-delegator/scripts/init_project.py \
  --provider huggingface
```

Supported provider values are `huggingface`, `llamacpp`, and `openrouter`.
Review the generated `local-llm-worker.toml`; narrow `allowed_paths` and replace
the example validation command with the project's actual checks.

For Hugging Face, export the credential before launching Codex or Claude:

```sh
export HF_INFERENCE_TOKEN=your-token
```

For OpenRouter, export `OPENROUTER_API_KEY`. llama.cpp needs no token by default.
The plugin inherits these variables but never stores or returns them.

The skill passes the target repository as `workspace_root` on each proposal, so
one installed MCP server can work across projects without re-registration.
`LOCAL_LLM_CONFIG` may optionally force a policy file outside each project.

## Use it

In Codex, ask:

```text
Use $delegate-local-worker to implement this focused bug fix.
```

In Claude Code, invoke:

```text
/local-llm-delegator:delegate-local-worker
```

The skill is explicit-invocation-only on both hosts. Codex sets
`allow_implicit_invocation: false`. Claude uses a separate mirrored skill with
`disable-model-invocation: true`, which also keeps its description out of
Claude's context until manual invocation.

The full `SKILL.md` is therefore not loaded on every prompt. While the plugin is
enabled, the host may still advertise or discover the two MCP tool schemas; that
small, host-dependent overhead exists even when the skill is idle. Invoke the
skill only when the source context and implementation work being offloaded is
larger than that overhead.

The primary model scopes the task and calls `propose_patch`. The worker reads
only allowed files, asks the cheaper model for a diff, validates it without
mutating the project, and returns the patch plus its digest. After full review,
the primary model calls `apply_patch`, which applies those exact bytes and runs
configured checks.

The MCP reduces primary-model context only when delegation happens before the
primary model reads and solves the implementation itself. Returned patches and
validation results still consume review context. The plugin does not persist
Codex or Claude conversation memory.

## Security

- Never place tokens in TOML, plugin JSON, prompts, or supporting context.
- Treat project validation commands as trusted code.
- Review the complete patch before approving its digest.
- Hosted models receive the source files inside the delegated scope.
- Proposal state is process-memory-only and expires after 15 minutes by default.
- The worker does not commit, push, or execute commands proposed by the model.

## Development

```sh
cd plugins/local-llm-delegator/mcp
PYTHONPATH=src python3 -m unittest discover -s tests -v
ruff check .
mypy src
```

Validate the skill and plugin with the validation scripts from Codex's built-in
`skill-creator` and `plugin-creator` skills.