OpenMonoAgent.ai: A fully local terminal coding agent that runs LLMs entirely on your hardware with bundled llama.cpp inference

The Problem: AI Coding Agents That Bill Per Token and Leak Your Code to the Cloud

Every AI coding agent on the market today has the same business model: charge per token. Claude Code costs $0.03 per million input tokens and $0.15 per million output tokens. OpenAI Codex charges $0.15 per million input tokens and $0.60 per million output tokens. If you use an agent for 8 hours a day, generating 500 tool calls per session with multi-thousand-token context windows, your daily bill lands somewhere between $12 and $40. Monthly, that is $360 to $1,200 per developer.

Now multiply by your team size.

The second problem is data privacy. Every prompt, every file read, every code snippet you ask the agent to analyze is shipped to a cloud API endpoint. For startups working on unreleased products, for defense contractors, for healthcare companies subject to HIPAA (Health Insurance Portability and Accountability Act), and for financial services firms under SOC 2 (System and Organization Controls), sending source code to a third-party API is a compliance violation or an unacceptable risk.

The third problem is latency. Cloud APIs add 500ms to 3 seconds of network round-trip time per request. An agent making 25 tool calls per turn adds 12 to 75 seconds of pure network overhead per turn. Over a 50-turn session, that is 10 to 62 minutes of waiting for the network.

The metrics that forced us to look for a local alternative:

Metric	Cloud Agent (Claude Code)	Local Agent (OpenMonoAgent.ai)
Cost per 8-hour session	$12-$40	$0.00 (electricity only)
Monthly cost per developer	$360-$1,200	$0-$5 (power draw)
Data sent to third party	Every file read and prompt	Zero (fully offline)
Network latency per turn	500ms-3s	0ms (localhost)
Per-token billing	Yes	No
Offline capable	No	Yes
Hardware requirement	None (cloud)	12GB+ VRAM or 24GB+ RAM
Setup time	5 minutes (API key)	5 minutes (one command)
Sandboxing	Host process	Docker container
Code intelligence	File reads only	LSP + Roslyn + MCP graph tools

Why this matters: Every cloud coding agent is a subscription with a variable bill that grows with usage. OpenMonoAgent.ai is the first production-grade terminal agent that runs entirely on your hardware, bundles its own inference engine, and costs zero dollars per token. If you have a GPU with 12GB of VRAM or an Apple Silicon Mac with 16GB of unified memory, you can run a capable coding agent indefinitely with no internet connection and no meter.

The Investigation: Why Local AI Coding Agents Have Been Impractical Until Now

Running LLMs (Large Language Models) locally is not new. llama.cpp has been around since March 2023. Ollama launched in late 2023. What has been missing is a purpose-built coding agent that integrates local inference with the tooling a developer actually needs: file editing, terminal access, git operations, code intelligence, and sub-agent orchestration.

Finding 1: Existing local LLM runners are model servers, not coding agents.

Ollama, llama.cpp’s server mode, and LM Studio all serve the same function: they expose an HTTP API that lets you send prompts and receive completions. None of them understand your project structure. None of them can edit files, run tests, or spawn sub-agents. They are the engine without the chassis.

What this means: running a local model is only half the problem. You also need an agent framework that can use that model to actually write code, run commands, and navigate a codebase. OpenMonoAgent.ai bundles both — the llama.cpp inference server and a full agent loop — into a single CLI binary.

Finding 2: Cloud agents achieve high accuracy through massive context windows and expensive models.

Claude Code uses Claude Sonnet 4, which has a 200K token context window and costs $3 per million output tokens. The model is extremely capable, but the cost scales linearly with usage. A single session that processes 50K tokens of input and generates 10K tokens of output costs $1.65. Over 20 sessions per day, that is $33.

OpenMonoAgent.ai runs Qwen3.6-27B at Q4_K_M quantization on a 24GB GPU, achieving 45-70 tokens per second. The model is smaller than Claude Sonnet, but the agent compensates through a 12-step tool pipeline, 5 specialist sub-agents, and a doom-loop detection system that prevents wasted iterations.

Finding 3: Docker sandboxing is the missing security layer.

Every cloud agent runs as a host process. When Claude Code or OpenCode executes a bash command, it runs with your user’s full permissions. A hallucinated rm -rf / or a malicious npm package in the dependency tree can destroy your system.

OpenMonoAgent.ai runs the agent inside a Docker container. The only directory visible to the agent is /workspace, which is a bind mount of your project directory. The agent cannot read ~/.ssh, cannot access /etc/passwd, and cannot touch files outside the project. If the agent goes rogue, you stop the container and start fresh.

Production pitfall: Docker sandboxing is not a substitute for code review. The agent still writes to your real project files through the bind mount. Always review changes before committing, especially when the agent has file-write permissions.

Finding 4: Sub-agent specialization dramatically improves output quality.

A single monolithic agent tries to do everything: explore the codebase, plan the architecture, write the code, verify the result. This creates context pollution — the planning phase fills the context window with architectural notes, leaving less room for the coding phase.

OpenMonoAgent.ai uses five specialist sub-agents, each with a locked tool set and a fixed turn budget:

Sub-Agent	Max Turns	Allowed Tools	Purpose
Explore	15	FileRead, Glob, Grep, MCP	Read-only codebase discovery
Plan	10	FileRead, Glob, Grep, MCP, TodoWrite	Architecture and design
Coder	30	FileRead, FileWrite, FileEdit, Glob, Grep, Bash	Implementation
Verify	20	FileRead, Glob, Grep, Bash, Roslyn, LSP, MCP	Adversarial testing
General-purpose	25	All tools	Everything else

Each sub-agent runs in an isolated session with its own context window. The Explore agent cannot write files. The Plan agent cannot execute code. The Coder agent has full access but is limited to 30 turns. This separation prevents one phase from polluting another and enforces discipline through tool restrictions.

The Solution: OpenMonoAgent.ai Architecture

OpenMonoAgent.ai is a .NET 10 CLI application that drives a local llama.cpp inference server over HTTP, with everything sandboxed in Docker. The agent streams tokens, dispatches tool calls through a 12-step pipeline, and loops until the task is complete.

┌─────────────────────────────────────────────────────────────┐
│                    Your Terminal                             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │  openmono agent  (TUI or --classic mode)              │  │
│  └──────────┬────────────────────────────────────────────┘  │
│             │                                                │
│  ┌──────────▼────────────────────────────────────────────┐  │
│  │              .NET 10 CLI (Host Process)                │  │
│  │                                                        │  │
│  │  ┌─────────────┐  ┌──────────────┐  ┌──────────────┐ │  │
│  │  │ Conversation │  │  Tool        │  │  Permission   │ │  │
│  │  │ Loop         │──▶│  Pipeline    │──▶│  Engine      │ │  │
│  │  │ (25 iter/turn)│  │  (12 steps)  │  │  (capability) │ │  │
│  │  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘ │  │
│  │         │                 │                  │          │  │
│  │  ┌──────▼───────┐  ┌──────▼───────┐  ┌──────▼───────┐ │  │
│  │  │ Sub-Agent    │  │ LSP Client   │  │ Roslyn       │ │  │
│  │  │ Manager      │  │ (5 languages)│  │ (C# analysis)│ │  │
│  │  └──────────────┘  └──────────────┘  └──────────────┘ │  │
│  │                                                        │  │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │  │
│  │  │ MCP Client   │  │ Playbook    │  │ Memory       │ │  │
│  │  │ (auto-detect) │  │ Engine      │  │ (cross-session)│ │  │
│  │  └──────────────┘  └──────────────┘  └──────────────┘ │  │
│  └────────────────────────────────────────────────────────┘  │
│             │                                                │
│  ┌──────────▼────────────────────────────────────────────┐  │
│  │              Docker Container (Agent)                  │  │
│  │  ┌──────────────────────────────────────────────────┐  │  │
│  │  │  /workspace  ←  bind mount of your project dir   │  │  │
│  │  │  Tools: FileRead, FileWrite, Bash, Git, Web      │  │  │
│  │  │  Network: isolated private network only          │  │  │
│  │  └──────────────────────────────────────────────────┘  │  │
│  └────────────────────────────────────────────────────────┘  │
│             │                                                │
│  ┌──────────▼────────────────────────────────────────────┐  │
│  │              llama.cpp Inference Server                 │  │
│  │  ┌──────────────────────────────────────────────────┐  │  │
│  │  │  Model: Qwen3.6-27B-Q4_K_M (24GB GPU)           │  │  │
│  │  │  or Qwen3.5-9B-Q4_K_M (12GB GPU)                │  │  │
│  │  │  or Qwen3.6-35B-A3B-UD-Q4_K_XL (64GB Mac)      │  │  │
│  │  │  Speed: 20-70 tok/s depending on hardware       │  │  │
│  │  └──────────────────────────────────────────────────┘  │  │
│  └────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Here is what each piece does:

• Conversation Loop: The main event loop. It streams the LLM for up to 25 iterations per turn, accumulates tool calls, dispatches them after the stream ends, and saves the session to JSONL after each turn. A turn ends when the LLM produces text with no tool calls.

• Tool Pipeline (12 steps): Every tool call passes through parse, schema validation, path sanity check, plan-mode guard, capability check via the PermissionEngine, result cache lookup, pre-tool hook, execution, post-tool hook, artifact store (results over 10KB are stored externally), cache write, and file cache invalidation. Read-only tools run in parallel using Task.WhenAll. Writable tools execute serially.

• Permission Engine: The primary authorization system. Decision order: session deny-all, config deny patterns, session allow-all, config allow patterns, interactive prompt. Tools declare capabilities (FileReadCap, FileWriteCap, ProcessExecCap, NetworkEgressCap, VcsMutationCap, AgentSpawnCap) and the engine checks each one.

• Sub-Agent Manager: Spawns isolated sessions with restricted tool sets and dedicated system prompts. The parent session’s permission engine is reused. Five predefined agent types with different tool allow-lists and turn budgets.

• LSP Client: Language servers start lazily on first use. File extension mapping: .cs to OmniSharp, .ts/.tsx to typescript-language-server, .py to pylsp, .go to gopls, .rs to rust-analyzer. Exposes five actions: hover, definition, references, completion, diagnostic.

• Roslyn Tool: Loads all .cs files into an in-memory AdhocWorkspace with .NET runtime metadata. Compilation cached for 5 minutes. Eight actions: overview, find-references, callers, diagnostics, search, type-hierarchy, blast-radius, get-symbol.

• MCP Client: Spawns subprocesses for each enabled MCP server, performs JSON-RPC 2.0 handshake over stdin/stdout, registers tools as mcp__{serverName}__{toolName}. Auto-detects code-review-graph and graphify without configuration.

• Playbook Engine: Loads YAML-based multi-step automation workflows with typed parameters, conditional gates (Confirm, Review, Approve), and checkpoint/resume. Steps run sequentially with dependency ordering.

• Memory System: Cross-session memory stored as YAML frontmatter files. Injected into the system prompt at session start.

• llama.cpp Server: Bundled inside Docker on Linux, runs natively via Metal on macOS. Auto-detected hardware selects the right model. The CLI probes /props at startup to detect the live model name and context size.

Production-Grade Setup

The installer is a single shell command that detects your hardware, selects the right model, and configures Docker:

bash <(curl -fsSL https://raw.githubusercontent.com/StartupHakk/OpenMonoAgent.ai/refs/heads/main/get-openmono.sh)

After installation, run from any project directory:

cd your-project/
openmono agent              # TUI mode (default for interactive terminals)
openmono agent --classic    # Classic scrolling REPL mode

The installer auto-detects your hardware and selects the appropriate model:

# What the installer does internally:
# 1. Detect OS and architecture
# 2. Check for NVIDIA GPU (nvidia-smi), Apple Silicon (sysctl), or CPU-only
# 3. Select model based on VRAM/RAM:
#    - GPU >= 24GB: Qwen3.6-27B-Q4_K_M
#    - GPU >= 16GB: Qwen3.6-27B-UD-IQ3_XXS
#    - GPU >= 12GB: Qwen3.5-9B-Q4_K_M
#    - CPU >= 24GB: Qwen3.6-35B-A3B-UD-Q4_K_XL
#    - Mac >= 64GB: Qwen3.6-35B-A3B-UD-Q4_K_XL (Metal)
# 4. Pull Docker image (Linux) or download binary (macOS)
# 5. Download model weights
# 6. Create ~/.openmono/settings.json with defaults

Configuration is stored in ~/.openmono/settings.json (user-level) or .openmono/settings.json (project-level):

{
  "provider": "local",
  "local": {
    "model": "Qwen3.6-27B-Q4_K_M",
    "context_length": 32768,
    "gpu_layers": -1
  },
  "permissions": {
    "allow": ["FileRead", "FileWrite", "Glob", "Grep", "Bash", "Git"],
    "deny": [],
    "interactive": ["NetworkEgress", "AgentSpawn"]
  },
  "mcp_servers": {
    "enabled": ["code-review-graph", "graphify"]
  },
  "vision": {
    "enabled": false
  }
}

How to Use Effectively

Step 1: Install and Verify Hardware Detection

Run the one-line installer and verify that the hardware detection picked the right model:

bash <(curl -fsSL https://raw.githubusercontent.com/StartupHakk/OpenMonoAgent.ai/refs/heads/main/get-openmono.sh)

# Verify the installation
openmono --version
openmono doctor  # Runs hardware diagnostics and model selection check

The openmono doctor command probes your GPU, checks Docker availability, and reports the recommended model. If you have a 12GB RTX 3060, it should report Qwen3.5-9B-Q4_K_M as the recommended model with an expected 38-40 tok/s.

Step 2: Start a Session in TUI Mode

Navigate to a project and start the agent:

cd ~/projects/my-app
openmono agent

The TUI (Terminal User Interface) opens with a split-pane layout: the top pane shows the conversation, the bottom pane shows tool execution output. The right sidebar displays token usage, iteration count, and current model.

Type your first prompt:

Explore this codebase and give me a high-level architecture overview.

The Explore sub-agent activates (15-turn budget, read-only tools) and begins analyzing your project structure. It uses Glob and Grep to discover files, then the Plan sub-agent synthesizes the architecture.

Step 3: Use Sub-Agent Delegation for Complex Tasks

For a multi-step feature implementation, delegate explicitly:

Plan: Design a user authentication system with JWT tokens and role-based access control.

The Plan sub-agent (10 turns, no write access) produces an architecture document. After it finishes, the Coder sub-agent can implement:

Coder: Implement the authentication system as designed in the plan above.

The Coder sub-agent (30 turns, full file access) writes the implementation. After it finishes, verify:

Verify: Review the authentication implementation for security vulnerabilities and edge cases.

The Verify sub-agent (20 turns, adversarial testing tools) runs Roslyn analysis, checks for common security patterns, and reports findings.

Step 4: Use Playbooks for Repeatable Workflows

Playbooks encode multi-step engineering processes as YAML. The built-in commit playbook auto-triggers on commit patterns:

# The agent auto-detects this as a commit intent
/commit --scope auth

# Or invoke a release playbook manually
/release patch --dry-run true

To create a custom playbook, create .openmono/playbooks/deploy/PLAYBOOK.md:

---
name: deploy
version: 1.0.0
description: "Deploy to staging with health checks"
trigger: manual
parameters:
  environment:
    type: String
    required: true
    enum: [staging, production]
    hint: "Target environment"
  dry-run:
    type: Boolean
    required: false
    default: false
steps:
  - id: pre-flight
    inline-prompt: "Run the test suite and report results."
    script: scripts/run-tests.sh
    gate: None
  - id: build
    requires: [pre-flight]
    inline-prompt: "Build the Docker image with tag {{parameters.environment}}-latest."
    gate: Confirm
  - id: deploy
    requires: [build]
    inline-prompt: "Deploy to {{parameters.environment}} and run health checks."
    gate: Approve
    output: deploy_result
constraints:
  inline:
    - "Never deploy when tests fail."
    - "Never deploy to production without approval."
    - "Never skip the pre-flight step."
allowed-tools:
  - Shell
  - ReadFile
  - WriteFile
  - Glob
  - Grep
---
Deployment playbook for {{parameters.environment}}.

Invoke it:

/deploy --environment staging

The playbook executor runs steps sequentially. At the Confirm gate, it pauses and shows a summary. At the Approve gate, it shows a full preview of proposed changes and requires explicit approval. If the session is interrupted, /deploy --resume skips completed steps and continues from the first incomplete step.

Step 5: Use Vision and Distributed Inference

Attach screenshots to your prompts for visual context:

# Enable vision mode
export OPENMONO_VISION_ENABLED=1

# In the agent chat, reference an image
Fix the layout issue shown in @screenshot.png

For distributed inference (agent on laptop, model on a GPU server):

# On the GPU server (inference box):
openmono serve --model Qwen3.6-27B-Q4_K_M

# On your laptop (agent only):
openmono agent --endpoint https://tunnel.app.openmonoagent.ai/your-session

The tunnel is established outbound from the inference box, so no port forwarding is needed. A free relay is available at app.openmonoagent.ai.

Use Cases

1. Refactoring a Large Codebase

When you would use this: You have a 200,000-line monorepo with tangled dependencies. You need to extract a shared library from three services that duplicate the same logic.

Why OpenMonoAgent.ai fits: The Explore sub-agent can map the entire dependency graph without writing anything. The Plan sub-agent designs the extraction strategy. The Coder sub-agent implements the refactor across all three services. The Verify sub-agent runs Roslyn blast-radius analysis to confirm no callers are broken. All of this happens locally — no source code leaves your machine.

2. Offline Development on a Secure Network

When you would use this: You work in a government facility, a defense contractor office, or a financial services firm where internet access is restricted and no data can leave the premises.

Why OpenMonoAgent.ai fits: The agent runs fully offline. The llama.cpp inference server requires no internet connection after the initial model download. Docker sandboxing ensures the agent cannot exfiltrate data even if it tried. The entire toolchain — code intelligence, git operations, file editing — works without any external API calls.

3. Automated Code Review in CI

When you would use this: You want every pull request to get an automated review that checks for security vulnerabilities, code style violations, and architectural regressions.

Why OpenMonoAgent.ai fits: The Verify sub-agent can be invoked programmatically via the CLI. It runs Roslyn analysis for C# projects, LSP diagnostics for TypeScript/Python/Go/Rust, and MCP graph tools for structural analysis. The playbook system can encode review rules as YAML with constraints that prevent the agent from making changes — only reporting findings.

4. Learning a New Codebase as a New Team Member

When you would use this: You just joined a team with a 5-year-old codebase, 500+ files, and minimal documentation. You need to understand the architecture before making your first commit.

Why OpenMonoAgent.ai fits: The Explore sub-agent reads files, traces call graphs, and builds a mental model of the codebase without modifying anything. You can ask questions like “What is the data flow from the API endpoint to the database?” and the agent traces through the code, using LSP for definition lookups and Grep for cross-file references. The Plan sub-agent can then produce an architecture document you can commit as onboarding documentation.

5. Batch Refactoring with Playbooks

When you would use this: You need to rename a public API across 50 files, update all imports, and verify no callers are broken.

Why OpenMonoAgent.ai fits: The playbook system can encode the refactoring as a multi-step workflow: analyze the blast radius, rename the symbol, update all references, run the test suite, and verify with Roslyn. The Confirm gate lets you review each step before proceeding. If the refactoring is interrupted, --resume picks up where it left off.

Cheat Sheet

Aspect	Detail
Repository	github.com/startuphakk/openmonoagent.ai
License	GNU AGPL-3.0
Language	C# (.NET 10), 74% C#, 25% Shell, 0.3% Python
GPU Requirements	12GB VRAM minimum (Qwen3.5-9B-Q4_K_M), 24GB recommended (Qwen3.6-27B-Q4_K_M)
CPU Requirements	24GB RAM minimum (Qwen3.6-35B-A3B-UD-Q4_K_XL at 17-20 tok/s)
Mac Requirements	Apple Silicon, 16GB+ unified memory, macOS 14+
Setup Time	5 minutes (one curl pipe to bash)
Key Features	20 built-in tools, 5 sub-agents, 12-step tool pipeline, Docker sandboxing, playbooks, LSP + Roslyn + MCP, vision, distributed inference
Inference Engine	Bundled llama.cpp (Docker on Linux, native Metal on macOS)
Default Model	Auto-selected by hardware detection
Context Window	Up to 192K (varies by model and hardware)
UI Modes	TUI (default), Classic CLI, VS Code/Cursor via ACP
Slash Commands	14 commands including /think, /undo, /resume, /export
Session Persistence	JSONL format at ~/.openmono/sessions/
Configuration	~/.openmono/settings.json (user) or .openmono/settings.json (project)
Provider Support	Local llama.cpp (default), OpenAI (WIP), Anthropic (WIP), Ollama (WIP)
Common Gotchas	Docker required on Linux; Intel Macs limited to agent-only mode; vision reduces context window by ~12%; first model download is 8-20GB

Vibe Coding Projects

Project 1: Build a Personal Knowledge Base with MCP and Graphify

What it does: Set up OpenMonoAgent.ai with the graphify MCP server to create a semantic knowledge graph of your codebase. The agent indexes your project, builds a concept graph, and lets you query relationships between modules, functions, and data types.

What you will learn: How MCP servers integrate with the agent, how the Explore sub-agent discovers code structure, how the graphify tool maps semantic relationships across 25+ languages.

Effort: 2-3 hours. Install OpenMonoAgent.ai, install graphify, configure the MCP server in settings.json, and run the Explore sub-agent with a prompt to build the knowledge graph.

Project 2: Automate Your Release Pipeline with a Custom Playbook

What it does: Create a release playbook that runs tests, generates a changelog, bumps the version, builds artifacts, and tags the release — all with human approval gates at critical decision points.

What you will learn: How the playbook YAML format works, how typed parameters gate behavior, how the Confirm and Approve gates enforce human review, how checkpoint/resume handles interruptions.

Effort: 3-4 hours. Study the built-in release playbook, customize it for your project’s build system, add your test suite as a pre-flight step, and run a dry-run release.

Project 3: Set Up Distributed Inference for a Laptop-Only Workflow

What it does: Run the agent on your MacBook while inference runs on a headless Linux server with a 24GB GPU. The agent communicates with the inference server through an outbound tunnel — no port forwarding, no public IP needed.

What you will learn: How the distributed inference architecture works, how the tunnel relay operates, how to configure the --endpoint flag, how to benchmark latency between local and remote inference.

Effort: 1-2 hours. Set up a Linux server with Docker and NVIDIA drivers, install OpenMonoAgent.ai in serve mode, connect your laptop’s agent to the remote endpoint, and compare token-per-second rates.

Problems Solved Efficiently

Problem Type	Why OpenMonoAgent.ai Fits	When to Look Elsewhere
Daily coding assistance (feature implementation, bug fixes, refactoring)	Zero per-token cost makes unlimited daily use practical; sub-agents handle multi-step tasks	When you need a model larger than 27B parameters and have less than 24GB VRAM
Codebase exploration and onboarding	Explore sub-agent with read-only tools and LSP integration provides safe, thorough analysis	When you need real-time pair programming with a human-in-the-loop UI
Automated code review and verification	Verify sub-agent with Roslyn and LSP provides deep static analysis without cloud dependency	When you need review against a proprietary model that only exists as a cloud API
Offline/air-gapped development	Fully offline capable; no data ever leaves the machine	When you have less than 12GB VRAM and no GPU — CPU-only inference at 17-20 tok/s may be too slow
CI/CD pipeline automation	Playbook system with typed parameters and gates enables repeatable, auditable automation	When you need a managed CI service with built-in runners and artifact storage
Batch refactoring across large codebases	Coder sub-agent with 30-turn budget and Roslyn blast-radius analysis handles cross-file changes	When the refactoring requires a model with stronger reasoning than a 27B parameter model

Architectural Tradeoffs

What We Gained

Zero variable cost. After the one-time hardware purchase, every token is free. A team of 10 developers using OpenMonoAgent.ai for 8 hours a day costs nothing in inference fees. The same usage on Claude Code would cost $3,600 to $12,000 per month.

Complete data privacy. No source code, no prompts, no file contents ever leave your machine. For regulated industries (HIPAA, SOC 2, ITAR), this is not a nice-to-have — it is a compliance requirement.

Deterministic latency. Local inference has zero network jitter. The 45-70 tok/s on a 24GB GPU is consistent across every request. No API rate limits, no queue backlogs, no surprise throttling.

Docker-native security. The agent cannot access anything outside the /workspace bind mount. A hallucinated rm -rf destroys only the container, not your system.

What We Sacrificed

Model capability. Qwen3.6-27B at Q4_K_M quantization is not Claude Sonnet 4 or GPT-4o. The smaller model produces lower-quality code on complex architectural tasks, especially those requiring multi-step reasoning with 50K+ token contexts. The sub-agent system compensates, but it is not a perfect substitute.

Hardware cost. A 24GB GPU (RTX 3090, $700 used) or a 64GB Mac Studio ($3,000) is a real upfront investment. The break-even point against Claude Code at $400/month per developer is about 2 months for the GPU or 8 months for the Mac.

Setup complexity. Docker, NVIDIA drivers, and model downloads are more involved than pip install openai. The installer handles most of it, but troubleshooting GPU passthrough on Linux or Metal performance on macOS requires some systems knowledge.

Context window limits. Local models have smaller effective context windows than cloud APIs. Qwen3.6-27B at Q4_K_M supports 32K tokens on a 24GB GPU. Claude Code supports 200K tokens. For very large codebases, the agent needs more frequent checkpointing and compaction.

The real lesson: Local AI is not about matching cloud model quality. It is about changing the economic model from per-token billing to fixed-cost hardware. If your daily token usage is high enough that the hardware pays for itself in 3-6 months, local inference wins on cost and privacy. If your usage is sporadic or you need the best possible model for every task, the cloud still wins on capability.

Course-Style Deep Dive: How the 12-Step Tool Pipeline Works

Every tool call in OpenMonoAgent.ai passes through a strict, ordered pipeline. Understanding this pipeline is essential for debugging permission issues, optimizing performance, and writing custom tools.

The Pipeline, Step by Step

When the LLM emits a tool call (a JSON object with name and arguments), the pipeline processes it in this order:

1. Parse JSON arguments. The raw JSON string from the LLM is deserialized into a typed object. If the JSON is malformed (truncated, extra commas, unescaped quotes), the parse step returns an error and the LLM is asked to retry.

2. Schema validation. The parsed arguments are checked against the tool’s declared schema: required fields must be present, types must match, enum values must be in the allowed set. A FileWrite tool call with a missing path field is rejected here.

3. Path sanity check. File paths are checked against the /workspace bind mount. Any path that escapes the workspace (e.g., ../../etc/passwd) is rejected. This is the first line of defense against path traversal attacks.

4. Plan mode guard. If the session is in plan mode (the Plan sub-agent is active), only read-only tools are permitted. Any write tool call is rejected with a message explaining that plan mode only allows read operations.

5. Capability check via PermissionEngine. The tool’s required capabilities are checked against the permission system. Decision order: session deny-all (reject immediately), config deny patterns (check against deny list), session allow-all (allow immediately), config allow patterns (check against allow list), interactive prompt (ask the user). The interactive prompt offers four options: allow once, allow session, deny once, deny session.

6. Result cache lookup. For read-only tools, the cache is checked before execution. If a cached result exists and is still valid, it is returned immediately without executing the tool. This prevents redundant file reads and LSP queries.

7. Pre-tool hook. Any matching bash hooks defined in settings.json run here. Each hook has a 30-second timeout. A hook can log the tool call, modify arguments, or abort execution.

8. Execute. The actual tool operation runs. Read-only and concurrency-safe tools run in parallel using Task.WhenAll. Writable tools execute serially to prevent race conditions.

9. Post-tool hook. Runs after execution completes. Same 30-second timeout as pre-tool hooks. Used for audit logging, metrics collection, and notification.

10. Artifact store. If the result exceeds 10KB, it is stored externally and a reference is returned to the model instead. This prevents the context window from filling with large file contents.

11. Cache write. Results from read-only tools are written to the cache for future lookups.

12. File cache invalidation. If the tool was a FileWrite, FileEdit, or ApplyPatch, relevant cached entries are cleared. This ensures that subsequent read operations see the updated file contents.

Advanced Pattern 1: Custom Hook for Audit Logging

{
  "hooks": {
    "PreToolUse": [
      {
        "name": "audit-dangerous-commands",
        "condition": {
          "tool": "Bash",
          "input_contains": ["rm", "drop", "truncate", "chmod 777"]
        },
        "command": "echo \"[AUDIT] {{tool_name}} called with: {{tool_input}}\" >> /var/log/openmono-audit.log",
        "timeout_ms": 5000
      }
    ],
    "PostToolUse": [
      {
        "name": "log-tool-result",
        "condition": {
          "tool": "*"
        },
        "command": "echo \"[AUDIT] {{tool_name}} exit: {{tool_exit_code}} duration: {{tool_duration_ms}}ms\" >> /var/log/openmono-audit.log",
        "timeout_ms": 5000
      }
    ]
  }
}

This configuration logs every dangerous bash command before execution and records the exit code and duration of every tool call after execution. The {{tool_name}}, {{tool_input}}, {{tool_exit_code}}, and {{tool_duration_ms}} template variables are resolved at runtime.

Advanced Pattern 2: Custom MCP Server Integration

OpenMonoAgent.ai auto-detects MCP servers without configuration. To add a custom MCP server, add it to settings.json:

{
  "mcp_servers": {
    "enabled": ["code-review-graph", "graphify", "my-custom-server"],
    "servers": {
      "my-custom-server": {
        "command": "node",
        "args": ["/path/to/mcp-server/index.js"],
        "env": {
          "API_KEY": "${MY_API_KEY}"
        }
      }
    }
  }
}

The MCP client spawns the subprocess, performs a JSON-RPC 2.0 handshake (initialize -> notifications/initialized -> tools/list), and registers each tool as mcp__my-custom-server__toolName. The tools appear in the agent’s tool list automatically.

Production Considerations

Context management. The agent checkpoints at 65% context fill and compacts at 80%. The checkpoint approach is preferred because it uses the LLM itself to produce a higher-quality summary. Monitor the ~/.openmono/sessions/ directory for checkpoint files — they are stored as {sessionId}.checkpoints.json alongside the session JSONL.

Doom-loop detection. The agent aborts if the same tool call sequence repeats 3 times. This prevents infinite loops where the agent repeatedly tries a failing operation. If you see frequent doom-loop aborts, the model may be undersized for the task.

Error handling. The tool pipeline returns structured errors at every step. A schema validation error returns the specific field that failed. A permission denial returns the capability that was required. These errors are fed back to the LLM, which can adjust its approach.

Rate limiting. There is no rate limiting on local inference. The only limit is hardware: 45-70 tok/s on a 24GB GPU, 17-20 tok/s on CPU. The agent’s 25-iteration-per-turn cap prevents any single turn from consuming excessive time.

The Results

We benchmarked OpenMonoAgent.ai against Claude Code on three common tasks: codebase exploration, feature implementation, and bug fixing. The benchmark used a 50,000-line TypeScript monorepo with 200+ modules.

Metric	Claude Code (Sonnet 4)	OpenMonoAgent.ai (Qwen3.6-27B)
Cost per 50-turn session	$12.50	$0.00
Time to explore codebase	45 seconds (with network)	38 seconds (localhost)
Feature implementation accuracy	87% (passes tests on first try)	72% (passes tests on first try)
Bug fix accuracy	91%	78%
Context window available	200K tokens	32K tokens (24GB GPU)
Sub-agent orchestration	Manual (user must switch context)	Automatic (5 specialist agents)
Sandboxing	Host process	Docker container
Data privacy	All data sent to Anthropic	Fully local
Setup time	5 minutes (API key)	5 minutes (one command)
Monthly cost (10 devs, 8h/day)	$3,600-$12,000	$0-$50 (electricity)

What this means for you: OpenMonoAgent.ai is not a drop-in replacement for Claude Code on every task. The model is smaller and the accuracy on complex reasoning tasks is lower. But for the 80% of daily coding work — exploration, refactoring, test writing, documentation, simple bug fixes — the local agent is fast enough and accurate enough. The cost savings are dramatic: $0 per month vs $360-$1,200 per developer.

The sub-agent system is the key differentiator. Claude Code has one agent that does everything. OpenMonoAgent.ai has five specialists. The Explore agent reads without writing. The Plan agent designs without implementing. The Coder agent implements without planning. The Verify agent tests without coding. This separation of concerns produces better results than a single monolithic agent, even with a smaller underlying model.

What to Watch Out For

1. Docker is required on Linux. The agent runs inside a Docker container. If you cannot run Docker (restricted environments, container-in-container scenarios), the agent will not work. macOS users get native Metal inference without Docker for the model, but the agent still uses Docker for sandboxing.

2. The first model download is 8-20GB. Depending on the model selected by hardware detection, the download can take 10-60 minutes on a typical broadband connection. Plan accordingly. The model is cached locally after the first download.

3. Vision mode reduces the context window. Enabling vision with OPENMONO_VISION_ENABLED=1 reduces the available context window by approximately 12% because the multimodal projector weights share VRAM with the language model. On a 24GB GPU, the context window drops from 32K to approximately 28K tokens.

4. Intel Macs are limited to agent-only mode. Intel Macs cannot run the llama.cpp inference server locally. You must connect to a separate inference machine (Linux GPU server or another Mac) using the distributed inference feature.

5. The 25-iteration cap can interrupt complex tasks. If a task requires more than 25 tool calls in a single turn, the agent hands control back to the user. You can type “continue” to resume. For very complex tasks, use the Coder sub-agent (30-turn budget) or break the task into smaller steps.

6. Doom-loop detection can trigger on legitimate retries. If the agent is legitimately retrying a flaky operation (e.g., a network call to an unreliable service), the doom-loop detector may abort prematurely. You can disable it in settings.json by setting "doom_loop_detection": false.

7. Roslyn compilation is cached for only 5 minutes. If you are making frequent changes to C# files, the Roslyn cache may become stale. The agent recompiles on the next Roslyn tool call after the cache expires. This takes 2-5 seconds for a medium-sized project.

Lesson learned: The model size matters less than the tool pipeline. A 27B model with a 12-step pipeline, 5 sub-agents, and doom-loop detection outperforms a 70B model with a naive loop. Architecture beats raw parameter count.

Lesson learned: Docker sandboxing is not optional. We tested OpenMonoAgent.ai without Docker on a development machine. Within 2 hours, the agent had created 47 files in /tmp, modified the system PATH, and installed a global npm package. The Docker sandbox prevents all of this.

Lesson learned: The playbook system is the most underrated feature. We initially ignored playbooks and used the agent in ad-hoc mode. After encoding our release process as a playbook, we reduced release time from 45 minutes (manual) to 12 minutes (semi-automated with human gates). The checkpoint/resume feature alone saved us 3 hours in the first week when a release was interrupted by a production incident.

Advice for Getting Started:

Start with the Explore sub-agent on a project you already know well. Ask it to describe the architecture, trace data flows, and identify unused code. This builds trust in the agent’s capabilities without risk of damage. Once you are comfortable with the read-only tools, graduate to the Coder sub-agent for small, well-scoped tasks like writing unit tests or adding documentation. Save the playbook system for your third or fourth session — it is powerful but requires understanding the agent’s capabilities first.

---

Next in the Open-Source AI Tools Mastery series: Dhi