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.

Runtime Architecture & 3 Pillars

Phase Loop Machine & 3-Pillar Engine

How Smoke Monkey decouples autonomous agent execution across three modular libraries: the React Chat UI, the Harness Core Engine, and the Model Context Protocol (MCP) Hub.

Smoke Monkey 3-Pillar Architecture Diagram: React Chat UI, Backend Harness Core Engine, and Model Context Protocol Server Hub — Figure 1: Architectural data plane showing real-time streaming between @smoke-monkey/ui, the 6-phase state machine in @smoke-monkey/harness, and external tool connectors in @smoke-monkey/mcp.

The 3 Pillars of Smoke Monkey

1. Frontend UI (@smoke-monkey/ui)

Drop-in React chat interface featuring streaming markdown, collapsible tool-call execution cards, charts, Mermaid diagrams, and 14 built-in theme presets.

2. Backend Harness (@smoke-monkey/harness)

Embeddable, zero-dependency TypeScript agent loop with a 6-phase state machine, automated loop guards, just-in-time skills, and human-in-the-loop pauses.

3. MCP Protocol Hub (@smoke-monkey/mcp)

Dual-mode Model Context Protocol integration: connects external tools via stdio/HTTP, while exposing 22 tools to external agents (Claude Code, Cursor, Codex).

The 6-Phase State Machine

Unconstrained agents easily fall into infinite loops or goal drift. Smoke Monkey binds execution to a deterministic state machine with self-healing demotion loops.

Interactive Engine Flow

Drag nodes · Scroll to pan & zoom

🎯 User Prompt "Fix auth bug in auth.ts"

1. EXPLORE Inspect · Glob · Grep

2. PLAN Sub-tasks · JIT Skills

3. EDIT Line-level Patch

4. VERIFY Run Tests & Diff

5. COMPLETE Session Persist

🔁 RECOVER (Demotion Loop) Inspect stderr · Rollback · Auto-heal

🛡️ Automated Loop Guards (Max 1000 Steps · 3x Identical Error Abort · 90% Compaction)

Deterministic loop: verification failure triggers an automated recovery demotion instead of halting.

Live Diagram

EXPLORE

Read-Only

Inspect directory structures, glob matching, git status, and grep searches to map the codebase without hallucinations or unintended mutations.

PLAN

Task Planning

Decompose user requirements into discrete step-by-step milestones. Loads specialized SKILL.md playbooks just-in-time (JIT) to preserve token budget.

EDIT

Code Modification

Surgical line edits and atomic file writes. Enforces TypeScript linting, exact match boundary verification, and unified diff formatting.

VERIFY

Validation

Runs test suites, compilers, typecheckers, and inspects git diffs. Catches regressions before completing the task.

RECOVER

Self-Healing

Automatic demotion loop: on compiler or test failure, reverts bad diffs, diagnoses stderr, reflects on errors, and pivots to alternate solutions.

COMPLETE

Synthesis

Final validation, clean git status verification, session memory persistence, and streaming conversational summary to the client UI.

Built-in Safety Guardrails & Compaction

Runaway Loop Protection

Halts execution automatically if total steps exceed MAX_STEPS (default: 1000) or identical error occurs 3 times.

Context Compaction (90%)

Past 90% token window capacity, summarizes older turns while preserving recent history and active skills verbatim.

Empty Response Exponential Backoff

Gracefully handles provider rate-limits (HTTP 429) without crashing the agent loop.

The Three Interactive Pauses

Safely suspends for tool permissions, user clarifications, and external MCP approvals before resuming.

Ready to build your first agent?

Follow our 60-second quickstart guide with production code examples.