LocalAgentBridge v0.4.1

A small local MCP offloading layer for Codex. Codex remains the primary agent; Ollama models can handle repository discovery, context compression, summaries, test-log analysis and first-pass review. Important decisions and final verification stay with Codex.

LocalAgentBridge explores whether useful local analysis can reduce unnecessary cloud context. It is not a Codex replacement, autonomous coding agent, guaranteed cloud-usage reduction, or security boundary for untrusted code. Local output still requires verification. No cloud LLM API, model shell access, embeddings or vector store is included.

How it fits

Codex → stdio MCP → LocalAgentBridge → role/cap/quality gates → local Ollama
                         │
                         └─ metadata ──→ SQLite ← separate usage collector
                                           │        ↑ local Codex telemetry
                                           └─ Windows tray / dashboard

See architecture, delegation policy, dashboard guide and reference benchmarks. Upgrade notes are in MIGRATION-v0.4.1.md; installation and test evidence is in VERIFICATION-v0.4.1.md.

Related MCP server: mcp-ollama

Windows setup

Requirements: Windows, Git, Python 3.11+ with Tcl/Tk and pip, Ollama, and local Codex. GPU acceleration is optional. Model fit depends on weights, context length, GPU/RAM and other applications; measure before enabling heavy escalation. Model downloads need internet, but inference and telemetry stay local.

Install Git for Windows, Python for Windows (include pip, the Python launcher and Tcl/Tk), Ollama, and Codex. Complete Codex sign-in. Start Ollama and confirm ollama --version and ollama list work in PowerShell. Then install the public starter:

git clone --branch v0.4.1 https://github.com/nishdel/LocalAgentBridge.git
cd LocalAgentBridge
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[tray]" -c requirements.lock.txt
Copy-Item config.example.toml config.toml
ollama pull qwen3:4b
.\.venv\Scripts\python.exe -m localagentbridge doctor

For development, install .[tray,dev,benchmark] with the same constraints. Activate the venv if you prefer the short localagentbridge doctor command. No PowerShell activation is required above.

config.toml in the current directory is selected automatically. Elsewhere, pass --config <config-path> before the command or set LAB_CONFIG. Relative paths in a config are resolved against that file. Set source_root to the repository that Codex is authorized to analyze. data_dir contains a fresh SQLite database and metadata log; neither is distributed. Keep personal config/history out of Git.

The default example uses one Qwen3 4B model, about 2.33 GiB of weights. It makes no large-model downloads or automatic promotions. Optional Balanced and Quality profiles add stronger models only when deliberately selected. Fixed consensus requires distinct models, so it is unavailable in the starter. To substitute models, edit config only: tag, roles, display name, architecture, total/active parameters, quantization, weight size, minimum tier, enabled flag and capability strength. Models are never silently substituted or automatically downloaded by MCP tools.

Start the MCP server and dashboard

Codex launches the stdio server when registered. For a manual foreground server:

.\.venv\Scripts\python.exe -m localagentbridge --config config.toml server

It waits for MCP messages on stdin; it is not an interactive chat prompt. Run the native tray monitor separately (one collector per data directory):

.\.venv\Scripts\python.exe -m localagentbridge --config config.toml dashboard

For a hidden terminal-free launcher from the checkout:

$labPython = (Resolve-Path .\.venv\Scripts\pythonw.exe).Path
$labConfig = (Resolve-Path .\config.toml).Path
Start-Process -WindowStyle Hidden -FilePath $labPython -ArgumentList ('-m localagentbridge --config "{0}" dashboard' -f $labConfig)

The tray menu opens the widget, changes the compute cap, or quits. Settings include start in tray, keep open, always on top, optional activity/escalation/failure popups, and auto-hide delay. Defaults avoid intrusive popups. widget remains an alias. For collection without a GUI, run collector; collector --once performs one scan.

Connect Codex

Generate the exact TOML for this installation:

.\.venv\Scripts\python.exe -m localagentbridge --config config.toml codex-config

Merge that output into the local Codex user config (normally $HOME/.codex/config.toml). Do not create a duplicate mcp_servers.localagentbridge table. It contains the absolute interpreter/config paths from your installation and a sufficient tool timeout for bounded escalation/consensus. The helper does not edit Codex settings. Restart Codex to load the tools. codex mcp list checks registration; /mcp in the CLI shows active servers. A running desktop task may need a new session before its tool catalog changes. Cloud-hosted Codex cannot directly launch this PC's process.

Alternatively, register through the CLI, then set the generated timeout in its config:

$labPython = (Resolve-Path .\.venv\Scripts\python.exe).Path
$labConfig = (Resolve-Path .\config.toml).Path
codex mcp add localagentbridge -- $labPython -m localagentbridge --config $labConfig server

See official MCP configuration. doctor reports configuration/installation issues; it does not prove that a Codex turn has invoked a tool. The project policy is an opt-in instruction, not enforcement inside Codex. Copy the relevant guidance from CODEX_POLICY.md.

Verify real local calls

.\.venv\Scripts\python.exe -m localagentbridge verify-models
.\.venv\Scripts\python.exe -m localagentbridge smoke --all
.\.venv\Scripts\python.exe -m localagentbridge stats
Get-Content .\data\bridge.log -Tail 20
ollama ps

verify-models calls each exact role default, subject to the cap. smoke is a real independent stdio MCP client exercising the seven handlers and optional consensus. A routed handoff is valid protocol output: inspect _routing.attempts to distinguish local inference from a gate returning work to Codex. Neither command certifies answer correctness. Heavier registered models are tested with the opt-in paired benchmark, not silently included in ordinary smoke runs. With a profile containing two distinct consensus role defaults, add --consensus. For the Balanced example use consensus_roles = ["general", "coding"]; the Quality example already uses GPT-OSS and Qwen3 14B as its distinct participants.

To verify Codex itself is using Ollama, ask it explicitly to invoke a bridge tool, look for the actual MCP invocation, then match the returned request ID/model with a new local log/SQLite record. Successful records include Ollama's final prompt/output counters and timing. Merely seeing a model loaded in ollama ps or a summary in Codex's prose is insufficient evidence. Live output counts/speed are estimates; completed Ollama counters replace them.

Seven tool examples

These are MCP argument objects, not PowerShell commands. Outputs are compact JSON text, capped at 3,000 UTF-8 bytes by default. Input is at most 10,000 characters, generation 600 tokens, context 8,192 tokens. Source files are explicitly confined to source_root. Discovery scans bounded file/byte/time limits and returns grounded paths/symbols/line evidence; use_model:false returns lexical evidence without inference.

Six analysis tools accept optional routing hints: complexity, stronger, previous_request_id, a supported failure reason, and auto_escalate. Use explicit feedback via triage_task to report accepted/corrected/rejected results. Feedback is not inferred from confidence. See the live MCP schema for exact enum values.

Local Compute tiers and measurements

The starter registers Qwen3 4B only, even if you raise its compute cap. The following selection rules apply after opting into the Quality profile:

Large is the Quality profile default. Maximum uses the same optional models; it changes selection thresholds. Role, memory, quality and compute-cap gates still apply. Codex retains implementation, architecture, security and final-verification responsibility in every tier.

Allow about 2.33 GiB of weight storage for the starter, 10.97 GiB for Balanced, or 23.81 GiB for Quality. These are storage sizes, not total runtime RAM/VRAM. The example allocation budgets are 6, 12 and 16 GiB respectively, including a 2 GiB reserve per selected model. Context/cache and other applications need additional headroom. Quality is tight on a 16 GiB system; 6 GiB VRAM does not hold either larger model fully, and CPU offload can be slow. Check the resource guidance before enabling Large/Maximum.

The dashboard lists actual eligible names below Light / Medium / Large / Maximum. The Models tab explains installed, registered, enabled, cap/resource eligibility and per-tool quality exclusions separately. Optional quality preferences select a configured stronger worker for substantive tasks; Maximum lowers the threshold for stronger summarization while preserving tiny operations on the light model. Configurations without these preferences retain smallest-first routing. Heavy/experimental profiles remain blocked unless explicitly enabled and within the current cap/resources.

Local compression compares supplied context bytes with returned bytes. Input excludes the objective, instructions and JSON schema overhead. Final logical payloads are counted once; legacy/fixed/consensus participant outputs are shown separately. Negative compression means expansion. Potential avoided context is max(0, input - returned) bytes: not measured Codex token savings. This project has no controlled with/without-delegation experiment proving a cloud token reduction. Actual token counters measure model usage, not bytes saved. A local call is not proof that a cloud call was avoided. Handoff envelopes also consume context; a short handoff or incorrect answer does not establish useful savings. Codex tool definitions and orchestration overhead are not included in this byte comparison.

Codex usage collection

The independent collector accepts local OTLP/HTTP completion log events (JSON or protobuf), then uses incremental local rollout telemetry as a fallback. It does not accept /v1/metrics or scrape the Codex graphical UI. It stores allowlisted counters, timestamps/model and local correlation IDs; prompt bodies and source are discarded. Optional user-level Codex config, merged into any existing [otel] table:

[otel]
environment = "local"
log_user_prompt = false
exporter = { otlp-http = { endpoint = "http://127.0.0.1:4318/v1/logs", protocol = "binary" } }

Start the widget/collector and restart Codex. Set monitor.otel_port=0 to disable this listener; fallback rollout collection remains available. No external telemetry service is used by LocalAgentBridge. Codex's own product settings are separate. See official telemetry guidance.

Codex totals mean recorded input plus output, including repeated context on later requests. Cached input is part of input; reasoning is part of output. Rollout cumulative totals are differenced, and overlapping OTel/rollout streams are reconciled per session/model rather than added twice. Missing counters stay unavailable. Observed Codex activity time is not GPU inference time. Collection begins with today's rollouts; collector --backfill includes retained older files explicitly.

Troubleshooting

Current limitations include confident factual errors, invented filenames, missed requirements, incomplete snippets, and hardware-dependent latency. Delegated output needs supervision even when confidence is high or models agree. Report ordinary bugs and feature requests through GitHub Issues. Use private vulnerability reporting for sensitive security issues; see SECURITY.md.

Development, privacy and release

Contributing includes tests and lint. Security describes local-only operation and private reporting. Release checklist records the clean-install, privacy and license audit. Personal histories and raw benchmarks stay in ignored local folders; anonymized reference aggregates belong in docs/benchmarks/. Public benchmark fixtures contain only this project's own historical source and synthetic test exercises.

The project uses the MIT license. Ollama and downloaded models have separate licenses; users must check the licenses for the exact models they install. No model weights or dependency binaries are included. See dependency review. See the v0.4.1 release.