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.

Getting Started

5 min readUpdated: October 2026

Get Autonomous AI Agents in Minutes: 5-Minute TypeScript Scaffolding Guide

Building an autonomous agent used to require weeks of configuring prompt templates, vector databases, callback chains, and sandboxes. With Smoke Monkey Harness, you can install one package, write 15 lines of TypeScript, and have an autonomous engineering agent executing tasks in under 5 minutes.

Technical Review: Smoke Monkey Core Architecture Team

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

Quick Answer & Executive Definition

Get Autonomous AI Agents in Minutes: 5-Minute TypeScript Scaffolding Guide: Building an autonomous agent used to require weeks of configuring prompt templates, vector databases, callback chains, and sandboxes. With Smoke Monkey Harness, you can install one package, write 15 lines of TypeScript, and have an autonomous engineering agent executing tasks in under 5 minutes. 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

Zero Setup Friction: Install `smoke-monkey-harness` and immediately run multi-turn agent loops.
Instant Tool Access: 24 tools for file viewing, editing, bash execution, and git operations available out of the box.
Live Event Streaming: Easily pipe text deltas and tool events directly to the console or a React UI.
Works with Any Provider: Plug in NVIDIA, Gemini, OpenAI, Claude, or local Ollama credentials.

Quick Implementation Examplequickstart.ts

quickstart.tstypescript

1import { createAgent } from 'smoke-monkey-harness';
2
3// Step 1: Initialize your autonomous agent in 15 seconds
4const agent = createAgent({
5  provider: 'gemini', // or 'nvidia', 'openai', 'anthropic', 'ollama'
6  model: 'gemini-1.5-pro',
7  workspacePath: process.cwd(),
8  autoApprove: true,
9});
10
11// Step 2: Stream live progress
12agent.on('text.delta', (e) => process.stdout.write(e.data.delta));
13agent.on('tool.started', (e) => console.log(`\n⚡ Running: ${e.data.toolName}`));
14
15// Step 3: Run your task!
16const result = await agent.run('Inspect README.md and add a section on Getting Started');
17console.log(`\n\n✅ Completed in phase: ${result.phase}`);

Step 1: Install Smoke Monkey in Your Project

Open your terminal and install the harness using your preferred package manager. Since there are zero external dependencies, the installation completes almost instantly.

terminalbash

1npm install smoke-monkey-harness
2# or
3pnpm add smoke-monkey-harness

Step 2: Set Your Provider API Key

Set your environment variable for whichever provider you prefer. Smoke Monkey supports all major model providers natively:

terminalbash

1# Choose whichever model provider you have an API key for:
2export GEMINI_API_KEY="your-gemini-key"
3# or
4export OPENAI_API_KEY="your-openai-key"
5# or
6export ANTHROPIC_API_KEY="your-anthropic-key"
7# or
8export NVIDIA_API_KEY="your-nvidia-key"

Step 3: Run Your First Autonomous Engineering Loop

Create a file named agent.ts and run it with npx tsx agent.ts. Watch the agent explore the codebase, plan its changes, surgically modify files, and verify the output.

Google Search Questions & Answers

Frequently Asked Questions

Q:Do I need to compile TypeScript or can I run directly with tsx?

You can run directly with `npx tsx agent.ts` or compile with `tsc`. Smoke Monkey is distributed with both CommonJS and ESModule exports and strict TypeScript declarations.

Q:How do I add a chat interface to this agent?

Install `@smoke-monkey/ui` to drop in our pre-built React chat canvas, which automatically hooks into agent events, tool streaming, and approval modals.

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