LocoOperator-4B is a 4B-parameter code exploration agent distilled from Qwen3-Coder-Next. Designed as a local sub agent for Claude Code-style agent loops — fast codebase navigation at zero API cost.

• 📰 News & Updates
• 📝 Introduction
• ✨ Key Features
• 🏗️ Architecture
• 📈 Performance
• 🚀 Quick Start
• 🔧 Analysis Pipeline
• 📁 Project Structure
• ⚠️ Known Limitations
• 📄 License
• 🙏 Acknowledgments

• [2026-02-24] 🚀 LocoOperator-4B-GGUF released for local deployment.
• [2026-02-23] 🎉 LocoOperator-4B model card and evaluation analysis released.

LocoOperator-4B is a tool-calling agent model trained via knowledge distillation from Qwen3-Coder-Next inference traces. It specializes in multi-turn codebase exploration — reading files, searching code, and navigating project structures within a Claude Code-style agent loop.

• 🔧 Tool-Calling Agent: Generates structured <tool_call> JSON for Read, Grep, Glob, Bash, Write, Edit, and Task (subagent delegation)
• 🎯 100% JSON Validity: Every tool call is valid JSON with all required arguments — outperforming the teacher model (87.6%)
• 🏠 Local Deployment: GGUF quantized, runs on Mac Studio via llama.cpp at zero API cost
• ⚡ Lightweight Explorer: 4B parameters, optimized for fast codebase search and navigation
• 🔄 Multi-Turn: Handles conversation depths of 3–33 messages with consistent tool-calling behavior

LocoOperator-4B operates as a sub agent (explorer) within a two-tier agent system:

The main agent handles decision-making and code generation while delegating codebase exploration to LocoOperator-4B — keeping API costs low and latency minimal.

Evaluated on 65 multi-turn conversation samples from diverse open-source projects (scipy, fastapi, arrow, attrs, gevent, gunicorn, etc.), with labels generated by Qwen3-Coder-Next.

The model perfectly learned when to use tools vs. when to respond with text (100% presence alignment). Tool type mismatches are between semantically similar tools (e.g. Grep vs Read) — different but often valid strategies.

LocoOperator-4B achieves perfect structured output. The teacher model has 11 tool calls with missing required arguments (empty arguments: {}).

• Claude Code — npm install -g @anthropic-ai/claude-code
• llama.cpp — build from source or brew install llama.cpp
• uv — curl -LsSf https://astral.sh/uv/install.sh | sh
• OpenRouter API key — https://openrouter.ai/keys

# Download the GGUF model
# (replace with actual model path)

# Start the server
./llama-server \
    -m LocoOperator-4B.gguf \
    --ctx-size 51200 \
    --host 0.0.0.0 \
    --port 8080

This repo includes a hybrid analysis pipeline that combines LocoOperator-4B (local) with a cloud LLM via OpenRouter, orchestrated through claude -p.

claude -p (sonnet) ──→ proxy (9091) ──→ OpenRouter Qwen3-Coder-Next
  └─ subagent (haiku) ─→ proxy (9091) ──→ local llama-server (8080)

The main agent runs as sonnet (cloud), and when it spawns subagents (Task tool) they default to haiku, which the proxy routes to the local 4B model. If the local model hits context limits or exceeds 10 turns, the proxy automatically falls back to OpenRouter.

The proxy (scripts/proxy.py) handles:

• Anthropic Messages API ↔ OpenAI Chat Completions format conversion for the local model
• Parsing <tool_call> text output from the local model back into Anthropic tool_use blocks
• Automatic fallback to OpenRouter on context overflow

# Clone the repository
git clone https://github.com/LocoreMind/LocoOperator.git
cd LocoOperator

# Install Python dependencies
uv sync

# Configure your OpenRouter API key
cp .env.example .env
# Edit .env and set OPENROUTER_API_KEY

.claude/settings.local.json is auto-generated on first run from your .env key. No need to create it manually.

Place your GGUF model at models/LocoOperator-4B-GGUF/LocoOperator-4B.gguf.

Place target projects under data/repos/.

./scripts/test_single.sh tqdm "How does tqdm detect if running in a Jupyter notebook?"

./scripts/analyze.sh tqdm

This reads queries from data/queries/tqdm-queries.txt and saves results to data/outputs/tqdm/.

1. Clone a project into data/repos/:

   git clone --depth 1 https://github.com/user/repo data/repos/repo
   rm -rf data/repos/repo/.git

2. Create a queries file at data/queries/repo-queries.txt (tab-separated id\tquery)
3. Run: ./scripts/analyze.sh repo

LocoOperator/
├── .env.example                         # OpenRouter key template
├── pyproject.toml
├── models/LocoOperator-4B-GGUF/
│   └── LocoOperator-4B.gguf
├── examples/                            # model inference examples
│   ├── quick_start.py
│   └── codebase_analysis_example.py
├── data/
│   ├── repos/                           # target projects to analyze
│   ├── queries/tqdm-queries.txt         # analysis queries (tab-separated: id\tquery)
│   └── outputs/                         # analysis results
├── prompts/
│   └── analyze_query.txt                # prompt template
└── scripts/
    ├── proxy.py                         # hybrid routing proxy
    ├── setup.sh                         # auto-generates .claude/settings.local.json
    ├── start_services.sh                # auto-starts llama-server + proxy
    ├── analyze.sh                       # batch analysis runner
    └── test_single.sh                   # single query test

• First-tool-type match is 65.6% — the model sometimes picks a different (but not necessarily wrong) tool than the teacher
• Tends to under-generate parallel tool calls compared to the teacher (76 vs 89 total calls across 65 samples)
• Preference for Bash over Read may indicate the model defaults to shell commands where file reads would be more appropriate
• Evaluated on 65 samples only; larger-scale evaluation needed

This project is licensed under the MIT License - see the LICENSE file for details.

• 🤖 Qwen Team for the Qwen3-4B-Instruct-2507 base model
• 🛠️ MS-SWIFT for the training framework
• 🦙 llama.cpp for efficient local inference
• 🤖 Anthropic for the Claude Code agent loop design that inspired this work