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.

Model Context Protocol

MCP Integration & Server Hub

Smoke Monkey treats the Model Context Protocol as a first-class citizen with a dual-mode integration: a native client for connecting external tools into your agent, and a standalone server with 22 tools for driving the harness from any host.

1. The Harness MCP Client

Embed external databases, GitHub, web browsers, and shell tools directly into your agent loop. Supports stdio child processes and remote streamable HTTP (SSE).

Namespaced as <serverId>__<toolName>

2. The @smoke-monkey/mcp Server

Gives Claude Code, Cursor, Codex, and Windsurf native control over Smoke Monkey. Scaffolds starter agents, plans architectures, and verifies builds.

22 Built-In Development Tools

Connecting External MCP Tools in TypeScript

mcp-agent.tstypescript

1import { createAgent } from '@smoke-monkey/harness';
2
3// Connect external tools over stdio and HTTP SSE
4const agent = createAgent({
5  workspacePath: process.cwd(),
6  mcp: [
7    {
8      id: 'github',
9      command: 'npx',
10      args: ['-y', '@modelcontextprotocol/server-github'],
11      env: { GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN },
12    },
13    {
14      id: 'postgres',
15      command: 'npx',
16      args: ['-y', '@modelcontextprotocol/server-postgres', process.env.DATABASE_URL!],
17    },
18  ],
19});
20
21// Tools are automatically namespaced as github__create_issue, postgres__query!
22await agent.run('Find open issues labeled "bug" and inspect the database schema');

Configuring External MCP Clients

claude_desktop_config.jsonjson

1// Run the server directly via npx
2npx -y @smoke-monkey/mcp
3
4// Or configure Claude Code / Cursor / Codex in your mcpServers JSON:
5{
6  "mcpServers": {
7    "smoke-monkey": {
8      "command": "npx",
9      "args": ["-y", "@smoke-monkey/mcp"]
10    }
11  }
12}

Key MCP Server Tools

harness_guide

Master instructions and architecture playbook for building looping agents.

harness_plan

Transforms a high-level product goal into an executable multi-step build plan.

harness_scaffold

Generates an end-to-end runnable starter agent project directly on disk.

harness_verify

Typechecks, builds, and verifies agent correctness across all 6 phases.

harness_skills_by_category

Discovers and filters 25 bundled engineering skills (backend, frontend, devops, QA).

harness_skill_content

Loads complete, actionable SKILL.md playbooks on-demand.

Check Out Built-In Tools

See all 24 native filesystem, git, and terminal tools.