Is Smoke Monkey an AI model?

No. Smoke Monkey is not an LLM. It is an embeddable, framework-agnostic runtime that turns LLMs (NVIDIA, Gemini, OpenAI, Claude, Ollama) into autonomous engineering agents capable of multi-step planning, calling tools, editing files, and running test loops with zero runtime dependencies.

Do I need a database (Postgres, SQLite, or Redis)?

No database is required. State is persisted through lean session files on disk, or you can plug in your own custom storage adapter. You can deploy it as a CLI, a desktop app, or inside a serverless function without provisioning a database.

How does human-in-the-loop permission gating work?

Smoke Monkey comes with three permission policies: allow-all, deny-all, and ask-default (or a custom function resolver). When a sensitive tool like edit_file or run_command is called under "ask", the runtime emits a permission.required event, pausing execution until your code or UI calls agent.resolvePermission(id, "allow" | "deny").

How does the Model Context Protocol (MCP) server work?

Smoke Monkey ships an official stdio MCP server in smoke-monkey-harness-mcp. Point Claude Code, Cursor, Codex, or opencode at it using npx -y smoke-monkey-harness-mcp to let other AI tools plan, scaffold, verify, and run agents using Smoke Monkey automatically.

What are SKILL.md skills and how do they prevent context bloat?

Skills are directories containing a SKILL.md workflow file. The system prompt only includes a one-line catalog of available skills. When a task requires specialized expertise (e.g. frontend-ui-engineering, test-driven-development, or security-hardening), the agent calls use_skill to load instructions just-in-time, saving thousands of tokens.

What is an AI Agent Harness?

An AI agent harness is the execution environment that bridges raw Large Language Models (LLMs) to real-world software engineering capabilities. While an LLM generates tokens, an AI harness manages deterministic phase loops (explore, plan, edit, verify, recover), tool execution sandboxing, token budget compaction, and safety gates needed for autonomous problem-solving.

What makes Smoke Monkey an Agentic AI runtime rather than a simple wrapper?

Unlike basic prompt-response chains, Smoke Monkey implements true agentic AI architecture: a deterministic 6-phase state machine with automatic failure recovery, runaway loop guards, 24 built-in developer tools, dynamic subcontext isolation, and interactive human-in-the-loop permission pauses.

Is Smoke Monkey Harness 100% Open Source AI?

Yes. Smoke Monkey Harness is 100% open source under the permissive MIT license with zero runtime dependencies. There is no telemetry lock-in, no mandatory cloud backend, and no database requirement—giving engineering teams complete sovereignty over their agent code.

What Agent APIs does Smoke Monkey Harness provide?

Smoke Monkey provides composable TypeScript Agent APIs: createAgent() for initialization, agent.run() for multi-turn execution, agent.on() for fine-grained lifecycle and streaming events, agent.resolvePermission() for interactive human authorization, subcontext switching APIs, and stdio Model Context Protocol (MCP) server endpoints.

Can I run completely offline without API keys?

Yes! Smoke Monkey natively supports Ollama out of the box. Set provider: "ollama" and model: "qwen3:8b" with workspacePath, and the agent will run locally on your machine with zero external network requests.

Cost Optimization

8 min readUpdated: October 2026

Optimize AI Agent Token Costs: Caching, Compression & Model Tiering

Technical Review: Smoke Monkey Core Architecture Team

|Tested on Node.js 18+ & Bun|TypeScript 5.x

Quick Answer & Executive Definition

Optimize AI Agent Token Costs: Caching, Compression & Model Tiering: Designed as a zero-dependency, open-source TypeScript architecture under the MIT License with native Model Context Protocol (MCP) support and deterministic phase state machines.

Key Architectural Takeaways

Prompt caching reduces repeated system prompt costs by up to 90%
Context compaction keeps sessions economical over long tasks
Route simple tasks to smaller models, complex to large models
Tool output truncation prevents context bloat from large file reads

Anthropic Prompt Caching

Claude's prompt caching lets you cache the system prompt and large static context blocks. Subsequent requests that hit the cache cost 90% less for cached tokens. Enable it by structuring your system prompt as a large static block and using Anthropic's cache control headers.

For a typical coding agent with a 4,000-token system prompt running 100 turns per session, prompt caching saves approximately $0.36 per session at Claude Sonnet rates.

Put rarely-changing content first in your system prompt

Anthropic caches from the beginning of the context. Keep dynamic content (current task, file snippets) at the end to maximize cache hits on the static system instructions.

Dynamic Model Tiering

Not every agent task needs a frontier model. Build a tiered routing strategy:

Simple tasks (rename a variable, fix a typo, add a comment): Use claude-3-haiku or gpt-4o-mini at 10-20x lower cost.
Standard tasks (write a function, refactor a module): Use claude-3-5-sonnet or gpt-4o.
Complex tasks (architect a system, debug a subtle race condition): Use claude-3-7-sonnet or o3.

Smoke Monkey\'s provider config can be set dynamically per agent instance, letting you implement this tiering logic in your orchestrator.

Google Search Questions & Answers

Frequently Asked Questions

Q:How much do context compaction savings add up in practice?

For a 10-turn agent session that accumulates 30,000 tokens of context, compaction can trim it to 8,000 tokens before the next turn, saving roughly 70% on input token costs for the remainder of the session.

Q:Can I set a token budget limit to prevent runaway costs?

Yes. Subscribe to the model.response event, accumulate total token counts, and call agent.stop() when you hit your budget threshold. The agent will complete its current tool call and halt gracefully.

Build with Smoke Monkey Harness

Zero dependencies. 24 built-in tools. Human-in-the-loop safety. 100% open source under the MIT License.

npm install smoke-monkey-harness