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.

Real-Time Benchmark Suite

50 Production Engineering Scenarios

50 Real-Time Agent Loop Cases

Unlike freeform ReAct agents that wander into infinite loops, Smoke Monkey executes every engineering task through a deterministic 6-phase state machine (Explore → Plan → Edit → Verify → Recover → Complete). Below are 50 production scenarios tested and verified with real terminal exit codes.

Verified Scenarios

3.1s

Avg Execution Time

100%

Verify Test Pass Rate

6.2

Avg Steps to Complete

Scenario Explorer

Filter by category or search by keywords to inspect prompts, tool chains, self-healing recovery loops, and automated verification commands:

Showing 50 of 50 cases

#01Bug Fixing

2.4s·5 steps

Fix Memory Leak in WebSocket Event Listener

> Locate memory leak in ws-server.ts where disconnected clients retain listener closures, patch the cleanup handler, and verify heap stability.

explore→plan→edit→verify→complete

grep_searchview_filereplace_file_contentrun_command

#02Bug Fixing

3.8s·8 steps

Resolve Race Condition in Async Job Queue

> Fix intermittent duplicate execution bug in queue.ts when two workers claim the same pending task concurrently.

explore→plan→edit→verify→recover→edit→verify→complete

view_filereplace_file_contentrun_commandSelf-Healing

#03Bug Fixing

1.9s·4 steps

Patch JWT Expiry Clock Skew Vulnerability

> Update jwt-verify.ts to permit a 10-second clock skew tolerance while strictly rejecting tokens expired past that window.

explore→plan→edit→verify→complete

grep_searchreplace_file_contentrun_command

#04Bug Fixing

2.1s·5 steps

Eliminate SQL Injection in Dynamic Filter

> Sanitize query-builder.ts where raw user strings were interpolated into WHERE clauses. Convert to parameterized SQL.

explore→plan→edit→verify→complete

grep_searchreplace_file_contentrun_command

#05Bug Fixing

1.8s·4 steps

Auto-Heal Flaky Jest Timer Test

> Fix flaky debounce test in utils/debounce.spec.ts that fails in CI due to timing jitters.

explore→plan→edit→verify→complete

view_filereplace_file_contentrun_command

#06Bug Fixing

1.7s·4 steps

Fix Stale Closure Bug in React useInterval Hook

> Fix bug where useInterval in src/hooks/use-interval.ts captures initial state and fails to tick with updated state values.

explore→plan→edit→verify→complete

view_filereplace_file_contentrun_command

#07Bug Fixing

2.9s·6 steps

Break Deadlock in Node.js Worker Thread Pool

> Investigate worker freeze in src/workers/pool.ts when tasks queue exceeds available thread count.

explore→plan→edit→verify→complete

grep_searchview_filereplace_file_contentrun_command

#08Bug Fixing

1.5s·4 steps

Fix Broken CORS Preflight for Custom Headers

> Update server/middleware/cors.ts to respond 204 to OPTIONS requests containing X-Agent-Session header.

explore→plan→edit→verify→complete

view_filereplace_file_contentrun_command

#09Bug Fixing

1.6s·4 steps

Resolve React SSR Hydration Mismatch

> Eliminate React hydration warning in src/components/time-display.tsx caused by new Date() rendered on server vs client.

explore→plan→edit→verify→complete

view_filereplace_file_contentrun_command

#10Bug Fixing

2.0s·5 steps

Fix ReDOS (Catastrophic Regex Backtracking)

> Audit validator regex in src/utils/email-validator.ts that hangs CPU on malicious repeating strings.

explore→plan→edit→verify→complete

view_filereplace_file_contentrun_command

#11Refactoring

4.2s·9 steps

Migrate Legacy CommonJS to Pure ESM

> Convert src/ directory from require()/module.exports to native import/export syntax and update package.json type: module.

explore→plan→edit→verify→complete

list_dirgrep_searchreplace_file_contentrun_command

#12Refactoring

3.6s·7 steps

Refactor REST API Endpoints to End-to-End tRPC

> Transform /api/users REST routes into type-safe tRPC v11 router with Zod input schema validation.

explore→plan→edit→verify→complete

view_filereplace_file_contentrun_command

#13Refactoring

2.5s·5 steps

Refactor React Class Components to Hooks

> Modernize legacy DashboardView.jsx class component to functional component using useState, useEffect, and useMemo.

explore→plan→edit→verify→complete

view_filereplace_file_contentrun_command

#14Refactoring

5.1s·11 steps

Decompose 1,200-Line Monolithic Controller

> Decompose OrderController.ts into Clean Architecture domain layers: OrderService, OrderRepository, and OrderValidator.

explore→plan→edit→verify→complete

view_filewrite_to_filereplace_file_contentrun_command

#15Refactoring

3.1s·6 steps

Replace Axios with Native fetch and Typed Wrapper

> Remove axios dependency across src/api/ and replace with native Node 18+ global fetch wrapped in a type-safe client with retry logic.

explore→plan→edit→verify→complete

grep_searchreplace_file_contentrun_command

#16Refactoring

2.8s·6 steps

Enforce Strict TypeScript Type-Narrowing

> Eliminate all 34 instances of "any" in src/types/events.ts with discriminated union types and custom type guards.

explore→plan→edit→verify→complete

view_filereplace_file_contentrun_command

#17Refactoring

3.4s·7 steps

Prisma Schema Evolution & Data Migration

> Add multi-tenant organizationId relation to User and Project models in schema.prisma and generate non-destructive migration SQL.

explore→plan→edit→verify→complete

view_filereplace_file_contentrun_command

#18Refactoring

2.7s·5 steps

Multi-Stage Dockerfile Size Optimization

> Refactor single-stage Dockerfile to multi-stage alpine build separating builder, runner, and standalone node runtime.

explore→plan→edit→verify→complete

view_filereplace_file_contentrun_command

#19Refactoring

3.0s·6 steps

Upgrade Tailwind CSS from v3 to v4

> Migrate tailwind.config.js to Tailwind v4 @theme CSS-first directives in globals.css and verify zero visual regression.

explore→plan→edit→verify→complete

view_filereplace_file_contentrun_command

#20Refactoring

4.8s·10 steps

Extract Monorepo Shared Package

> Extract shared validation schemas and types into packages/shared using Turborepo and link workspace packages.

explore→plan→edit→verify→complete

list_dirwrite_to_filereplace_file_contentrun_command

#21Testing & QA

3.5s·6 steps

Boost Core Utility Test Coverage from 42% to 95%

> Generate unit tests for src/utils/diff-applier.ts targeting edge cases: empty strings, CRLF linebreaks, and offset mismatches.

explore→plan→verify→complete

view_filewrite_to_filerun_command

#22Testing & QA

4.1s·7 steps

Generate End-to-End Playwright Authentication Suite

> Write Playwright test verifying signup, login with invalid credentials, password reset, and authenticated dashboard access.

explore→plan→verify→complete

view_filewrite_to_filerun_command

#23Testing & QA

2.6s·5 steps

Detect Visual UI Regression with Snapshots

> Run visual snapshot comparison on Modal and ToolCard components across 14 color themes and isolate styling regressions.

explore→plan→edit→verify→complete

view_filereplace_file_contentrun_command

#24Testing & QA

3.2s·6 steps

Mock Stripe Webhook Handler with Signature Verification

> Implement integration test for /api/webhooks/stripe generating valid HMAC-SHA256 signatures for checkout.session.completed.

explore→plan→verify→complete

view_filewrite_to_filerun_command

#25Testing & QA

5.4s·8 steps

Mutation Testing with Stryker for Resilience

> Execute mutation testing on permission-checker.ts to ensure no conditional boundary can be bypassed silently.

explore→plan→edit→verify→complete

view_filereplace_file_contentrun_command

#26Testing & QA

3.7s·5 steps

Fuzz Testing Markdown & Patch Parser

> Fuzz test parsePatchChunks() with 10,000 malformed diff inputs to verify it never throws unhandled exceptions.

explore→plan→verify→complete

write_to_filerun_command

#27Testing & QA

4.5s·6 steps

Performance Benchmark: 100,000 Token Processing

> Benchmark token compaction speed and memory allocation under 100,000 token conversations in AgentLoop.

explore→plan→verify→complete

write_to_filerun_command

#28Testing & QA

2.9s·5 steps

Property-Based Testing on State Machine Transitions

> Verify that invalid state transitions (e.g. explore ➔ complete directly) are mathematically impossible across 5,000 random events.

explore→plan→verify→complete

view_filewrite_to_filerun_command

#29Testing & QA

5.8s·7 steps

Load Testing WebSocket SSE Server with Artillery

> Stress-test @smoke-monkey/ui SSE server with 2,000 concurrent streaming connections simulating LLM token output.

explore→plan→verify→complete

write_to_filerun_command

#30Testing & QA

6.2s·7 steps

Integration Test Database with Testcontainers

> Write integration test spinning up isolated PostgreSQL Docker container with Testcontainers, migrating schema, and verifying queries.

explore→plan→verify→complete

view_filewrite_to_filerun_command

#31MCP & DevOps

2.1s·4 steps

Auto-Generate GitHub Actions CI/CD Matrix Workflow

> Create .github/workflows/ci.yml with test matrix across Node 18, 20, 22 on Ubuntu and macOS with pnpm caching.

explore→plan→verify→complete

write_to_filerun_command

#32MCP & DevOps

3.8s·7 steps

Generate OpenAPI 3.1 Specification from TypeScript Types

> Inspect src/routes/ and automatically generate openapi.json documentation with complete request/response schemas.

explore→plan→verify→complete

list_dirgrep_searchwrite_to_filerun_command

#33MCP & DevOps

2.9s·5 steps

Connect Stdio MCP Server for Local Database Queries

> Register postgres-mcp stdio server in agent options and execute schema introspection using remote MCP tools.

explore→plan→edit→verify→complete

view_filereplace_file_contentrun_command

#34MCP & DevOps

4.6s·6 steps

Deploy Next.js App to Vercel via Agent CLI Tool

> Inspect build output, set production environment variables, and trigger preview deployment using Vercel CLI tool.

explore→plan→edit→verify→complete

run_command

#35MCP & DevOps

3.1s·6 steps

Optimize Library Bundle with Tsup Dual ESM/CJS

> Configure tsup.config.ts to output tree-shakeable ESM (.mjs) and CommonJS (.cjs) bundles with declaration maps and DTS.

explore→plan→edit→verify→complete

view_filewrite_to_filereplace_file_contentrun_command

#36MCP & DevOps

2.3s·5 steps

Automate Semantic Versioning & CHANGELOG.md

> Inspect git log since last tag v1.1.0, categorize conventional commits (feat, fix, perf), and bump version to v1.2.0.

explore→plan→edit→verify→complete

run_commandreplace_file_content

#37MCP & DevOps

3.4s·6 steps

Wire Sentry Telemetry & Error Boundary in Next.js

> Install and configure @sentry/nextjs with source maps upload, tunnel route, and React error boundary fallback.

explore→plan→edit→verify→complete

view_filereplace_file_contentrun_command

#38MCP & DevOps

4.8s·8 steps

Automated Git Bisect Regression Hunt

> Run automated git bisect across last 50 commits to isolate exact commit hash that introduced latency spike.

explore→plan→edit→verify→complete

run_command

#39MCP & DevOps

3.6s·7 steps

Deploy Redis Distributed Cache Layer with TTL

> Introduce Redis cache wrapper around database repository with stale-while-revalidate caching policy and key eviction.

explore→plan→edit→verify→complete

view_filewrite_to_filereplace_file_contentrun_command

#40MCP & DevOps

2.2s·5 steps

Audit & Rotate Expired Environment Secrets

> Scan .env.example against process.env usage across codebase. Detect missing keys and validate RSA public keys.

explore→plan→edit→verify→complete

grep_searchreplace_file_contentrun_command

#41Agent Loop & Safety

3.9s·7 steps

Multi-Agent Sub-Context Delegation for Code Review

> Spawn child subagent in isolated sub-context to perform security audit on PR diff while parent orchestrates build.

explore→plan→edit→verify→complete

view_filerun_command

#42Agent Loop & Safety

2.4s·5 steps

Just-in-Time Skill Discovery from SKILL.md

> Agent discovers .agents/skills/docker-deploy/SKILL.md dynamically when user mentions "Deploy to staging container".

explore→plan→edit→verify→complete

list_dirview_filerun_command

#43Agent Loop & Safety

2.1s·4 steps

Human-in-the-Loop File Edit Permission Checkpoint

> Agent attempts destructive file overwrite; execution pauses, emits permission.requested event, and waits for UI approval.

explore→plan→edit→verify→complete

replace_file_content

#44Agent Loop & Safety

5.2s·12 steps

Automated 90% Context Token Compaction

> Run multi-turn agent for 45 steps until token usage reaches 91% of model context limit. Verify auto-compaction triggers.

explore→plan→edit→verify→complete

replace_file_contentrun_command

#45Agent Loop & Safety

4.3s·8 steps

Self-Healing Demotion Loop on Test Failure

> Agent drafts edit that introduces syntax error in auth.ts. Verify phase loop automatically demotes to recover phase instead of crashing.

explore→plan→edit→verify→recover→edit→verify→complete

replace_file_contentrun_commandSelf-Healing

#46Agent Loop & Safety

3.3s·6 steps

Multi-File Dependency Graph Topological Sort

> Analyze 80 internal TypeScript imports, detect circular dependencies, and order compilation sequence topologically.

explore→plan→edit→verify→complete

list_dirgrep_searchrun_command

#47Agent Loop & Safety

2.7s·5 steps

Real-Time SSE Streaming to React Chat Canvas

> Stream raw LLM token deltas, tool start events, and interactive confirmation modals over Server-Sent Events to @smoke-monkey/ui.

explore→plan→edit→verify→complete

run_command

#48Agent Loop & Safety

2.5s·5 steps

Stdio JSON-RPC Protocol Bridge for Claude Code & Cursor

> Expose smoke-monkey-harness tools over stdio MCP protocol for Claude Code and Cursor agent assistants.

explore→plan→edit→verify→complete

view_filerun_command

#49Agent Loop & Safety

1.4s·4 steps

Offline Fixture Test Runner (Zero LLM API Calls)

> Execute full agent harness test suite against recorded offline JSON fixtures without requiring internet or API keys.

explore→plan→edit→verify→complete

run_command

#50Agent Loop & Safety

3.0s·6 steps

Resumable Session State Hydration from Disk

> Interrupt running agent at step 12. Simulate process crash, restart runtime with identical sessionId, and verify execution resumes.

explore→plan→edit→verify→complete

view_filerun_command

Core Loop Engine

The 6-Phase State Machine

Tools Reference

24 Built-In Tools