Hermes + Claude Code Local Stack

Hermes Agent (Nous Research, v0.10.0, MIT license, 176k+ GitHub stars) is a self-improving AI agent with a built-in learning loop — it creates skills from experience, improves them during use, and builds a deepening user model across sessions. When paired with OpenCode (the open-source, provider-agnostic coding CLI) and local inference via Ollama or llama.cpp, this stack gives you a fully local, zero-cost AI coding environment. The agentic reasoning step is Hermes Agent's skill creation: after completing a complex task (e.g., debugging a microservice), Hermes synthesizes the experience into a permanent Markdown skill document stored in its skill library, and the next time it encounters a similar problem, it loads the relevant skill instead of starting from zero. This is agentic because the agent learns autonomously — it decides what knowledge to persist, when to create a skill, and when to call an existing one. The entire stack runs on a MacBook Pro with 16GB RAM using Qwen3.5-9B-Q4_K_M on llama.cpp, achieving 15-25 tokens/second for coding tasks. Total ongoing cost: electricity only.

BUSINESS PROBLEM

A freelance developer or indie hacker using Claude Code for daily development faces a recurring cost of $100-200/month on the Max plan, and each heavy coding session burns $2-5 in API fees. For someone earning $3,000-6,000/month in freelance income, that is 3-7% of gross revenue going to an AI subscription — before considering overage charges. The alternative, free-tier AI tools, impose rate limits (typically 20-60 requests/hour) that make extended coding sessions impossible. A single refactor requiring 50+ tool calls hits the rate limit wall in under 10 minutes. According to Ollama's 2026 community survey, 71% of developers cited API costs as the primary barrier to adopting agentic coding tools. (Source: Ollama Community Survey, 2026) The local stack solves both problems: zero ongoing inference cost and zero rate limits. The trade-off is a quality gap — a 9B local model scores 60-70% on coding benchmarks vs 85-90% for Claude Opus — but for 80% of daily coding tasks (bug fixes, refactors, test writing, documentation), local models are sufficient. The remaining 20% can fall back to API models via Hermes Agent's provider routing.

WHO BENEFITS

Independent developers and freelancers working on 1-3 projects simultaneously: you need AI assistance throughout the day but cannot justify $200/month for a coding agent. A one-time hardware investment and 60-minute setup get you unlimited local AI coding for zero monthly cost. Privacy-conscious developers working with proprietary or client codebases: sending code to third-party APIs is a non-starter for many contracts. A fully local stack means your code never leaves your machine. Students learning software engineering: you need to experiment with AI-assisted coding but have limited budget. Local models on a laptop provide a sandbox for learning agentic workflows without spending a dollar. Developers in regions with unreliable API access or restrictive internet policies: a local stack works offline after the initial model download.

HOW IT WORKS

1. Local Inference Setup. Install Ollama or llama.cpp and download a coding-optimized model. For 16GB RAM, use Qwen3.5-9B-Q4_K_M (5.3GB disk, ~10GB RAM). Input: model selection. Output: running OpenAI-compatible endpoint at localhost:11434 (Ollama) or localhost:8080 (llama.cpp).
2. Hermes Agent Install. Install Hermes Agent via the official script (curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash). Configure it to use the local endpoint as its inference provider. Input: installed Hermes Agent. Output: running agent with local model.
3. OpenCode Configuration. Install OpenCode and configure it to use Ollama/llama.cpp as its backend (OPENAI_BASE_URL=http://localhost:11434/v1). OpenCode acts as the coding CLI that Hermes Agent delegates file editing and shell commands to. Input: OpenCode CLI. Output: configured local coding agent.
4. Skill Learning Trigger. Start a complex task in Hermes Agent — e.g., refactor a React component. Hermes completes the task, then autonomously creates a skill document from the experience. Input: completed task + execution log. Output: .md skill file in the skill library. This is the agentic reasoning step.
5. Skill Reuse. On the next similar task, Hermes loads the saved skill and completes the task faster and with higher quality. The skill lists the tools, file patterns, and reasoning patterns used. Input: new task + loaded skill. Output: accelerated task execution.
6. Fallback to Cloud (Optional). For tasks the local model cannot handle (complex multi-file refactors), configure Hermes Agent's provider routing to fall back to Anthropic or OpenRouter. Input: local model failure signal. Output: routed cloud API call.
7. Docker Deployment (Optional). Package the full stack (llama.cpp server + OpenCode + Hermes Agent) in a Docker Compose file for reproducible setup across machines. Input: Docker Compose configuration. Output: one-command local AI coding environment.

TOOL INTEGRATION

Hermes Agent (Nous Research, v0.10.0, MIT license): The self-improving AI agent framework. 141K lines of Python code, 74 built-in skills, 12 platform adapters, full MCP integration, and built-in cron scheduler. Installed via curl install script. Configuration via ~/.hermes/.env. Provider support includes Ollama, OpenAI, Anthropic, OpenRouter, and custom endpoints. Gotcha: Hermes Agent requires a minimum 70K context window for reliable function calling with its skill system. If your local model runs at 8K or 16K context, skills and memory features degrade significantly. Set -c 131072 in llama.cpp flags.

Ollama (ollama.com): The easiest local inference engine. One-command model pulling and serving. Anthropic Messages API format support added in 2026. Gotcha: by default, Ollama uses f16 KV cache which doubles memory usage. Enable quantized KV cache (--cache-type-k q4_0 --cache-type-v q4_0) to fit larger models in the same RAM.

llama.cpp (github.com/ggerganov/llama.cpp): Lower-level inference engine with better performance tuning options. Metal GPU acceleration on Apple Silicon. brew install llama.cpp gets you llama-server. Gotcha: llama.cpp's OpenAI-compatible endpoint uses a different tokenizer than Ollama for the same model file. Test one complete session before committing to a setup.

OpenCode (github.com): Open-source, provider-agnostic coding CLI. Configured via environment variables. Acts as the tool execution layer for code tasks. Gotcha: OpenCode's agent loop can make 10-30 tool calls per task. Each call runs through the local model, so task latency depends on tokens/second. A 12 token/sec Qwen3.5-9B takes 2-3 minutes for a moderate refactor vs 15 seconds with Claude API.

ROI METRICS

1. Monthly API cost: $100-200/month for Claude Max plan → $0/month for local inference. Hardware cost of $0 (existing laptop) or $1,000-3,000 for a dedicated machine.
2. Rate limits: 60-100 req/hr on free API tiers → unlimited requests on local inference
3. Task completion speed (simple refactors): 15-30 seconds on Claude API → 2-5 minutes on Qwen3.5-9B local (15-25 tok/s)
4. Skill improvement over time: first similar task takes 5-10 min, tenth task takes 2-3 min (skill reuse) — Hermes Agent's learning loop
5. Time to first ROI: immediately at setup — the first task that would have cost API fees is free. Within 30 days, recoups the setup time in saved subscription costs

CAVEATS

1. Model quality gap: a 9B local model scores 60-70% on coding benchmarks vs 85-90% for Claude Opus 4.8. For complex architecture decisions, multi-file refactors with subtle dependencies, or security-critical code, the local model may produce incorrect results that require careful human review. 2. Memory requirements: a 9B Q4 model needs ~10GB RAM at 128K context. On an 8GB M1 Mac, you must reduce context to 32K or use a 7B model, which further degrades quality. 3. No skill persistence without sufficient context: Hermes Agent's skill creation works best with 70K+ context. On smaller contexts, the skill content may be too brief to be useful. 4. Cold start latency: the first query after model load is slow (10-30 seconds) as the model loads into RAM. Keep the server running between sessions to avoid this.