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.

Architecture

8 min readUpdated: October 2026

How to Build an Autonomous AI Coding Agent in TypeScript from Scratch

Autonomous coding agents require far more than basic prompt-response chains. They need structured phase loops, safe file editing tools, real-time terminal sandboxing, and test verification cycles. This comprehensive architectural guide teaches you how to construct an autonomous software engineer in TypeScript using Smoke Monkey Harness.

Technical Review: Smoke Monkey Core Architecture Team

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

Quick Answer & Executive Definition

How to Build an Autonomous AI Coding Agent in TypeScript from Scratch: Autonomous coding agents require far more than basic prompt-response chains. They need structured phase loops, safe file editing tools, real-time terminal sandboxing, and test verification cycles. This comprehensive architectural guide teaches you how to construct an autonomous software engineer in TypeScript using Smoke Monkey Harness. 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

The 4 Pillars of a Coding Agent: Prompt + State Machine Loop + Sandboxed Tools + Context Memory.
Why AST Chunk Replacement Beats File Rewriting: Preventing file truncation bugs when editing large codebases.
Test-Driven Verification: Automatically running tests to validate agent changes before declaring task completion.
Permission Architecture: Enforcing safety policies (allow, ask, deny) on shell commands and file mutations.

The Anatomical Breakdown of a Coding Agent

Every autonomous coding agent comprises four core components:

The Model Layer: Generates reasoning tokens and structured tool call specifications.
The Execution Loop: Coordinates state transitions and handles errors.
The Engineering Tools: Sandboxed functions for reading files, editing lines, running shell commands, and managing git.
Context Compaction: Manages message history so multi-turn debugging sessions do not exceed model token windows.

Implementing the 6-Phase Engineering State Machine

Unconstrained agent loops fail because they jump immediately into editing code without exploring the surrounding architecture or verifying assumptions. Smoke Monkey enforces a 6-phase state machine:

explore: Run list_dir and grep_search to map dependencies.
plan: Formulate a task checklist and risk assessment.
edit: Apply surgical modifications via replace_file_content.
verify: Execute npm test or npm run lint.
recover: If tests fail, backtrack and adjust edits.
complete: Summarize results and present git diffs.

state-machine-wiring.tstypescript

1import { createAgent } from 'smoke-monkey-harness';
2
3const agent = createAgent({
4  workspacePath: process.cwd(),
5  provider: 'anthropic',
6  model: 'claude-3-7-sonnet',
7});
8
9agent.on('phase.changed', ({ data }) => {
10  console.log(`Transitioned from ${data.from} to ${data.to}`);
11});

Surgical AST Code Editing

Traditional LLMs struggle when instructed to rewrite large 1,000-line files, frequently hallucinating or truncating code. Smoke Monkey provides AST chunk replacement tools (replace_file_content and multi_replace_file_content), requiring the model to specify exact target lines and replacement content, preserving unaffected code perfectly.

Google Search Questions & Answers

Frequently Asked Questions

Q:How do I prevent the agent from accidentally deleting production files?

Configure permission gating: set permissions for `run_command` and file mutations to "ask". The agent will pause and emit a `permission.required` event requiring human approval before executing destructive actions.

Q:Can the coding agent run unit tests automatically?

Yes. Smoke Monkey agents can invoke `run_command` with `npm test`, `pytest`, or `cargo test` during the `verify` phase, interpreting the output and automatically self-healing if failures occur.

Related Alternatives & Comparisons

vs Anthropic Claude Code

Claude Code Runtime Alternative: Open Source Stdio MCP Agent Harness

Compare

vs Cognition Devin

Open Source Devin Alternative: Build Autonomous Software Engineers in TypeScript

Compare

vs Cursor Composer

Cursor Composer Agent Alternative: Embeddable Code Editing Engine

Compare

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