Open Source AI Agent Harness|v1.3.1 Live

Open Source AI Agent Harness & Agentic AI Runtime

Smoke Monkey Harness is an open source TypeScript runtime and composable agent API suite. It turns any LLM into an autonomous agentic AI engineer that can plan, call tools, edit files, inspect git, manage context, and stream rich developer chat interfaces—with zero runtime dependencies.

Zero npm dependencies
No database required
100% strict TypeScript
Smoke Monkey Brand Mascot — Cybernetic Ape with Cyan Flame Hair
Smoke Monkey Runtime
Framework-agnostic agent loop, UI canvas & MCP server
$npm install smoke-monkey-harness
0
Dependencies
Zero runtime bloat
24
Built-in Tools
FS, Terminal, Git, Search
25
Agent Skills
SKILL.md JIT loading
100%
TypeScript
Strict types & ESM+CJS
Developer Quickstart

Build an AI Agent in TypeScript in 60s

Production-ready TypeScript agent APIs. No complex scaffolding or framework bloat—pick a pattern below and embed autonomous agentic AI in seconds.

60-second-agent.tstypescript
import { createAgent } from 'smoke-monkey-harness';
const agent = createAgent({
provider: 'nvidia',
model: 'nvidia/nemotron-3-super-120b-a12b',
apiKey: process.env.NVIDIA_API_KEY,
workspacePath: process.cwd(),
});
// Run an autonomous goal
const result = await agent.run(
'Find all deprecated express endpoints, update them, and run tests.'
);
console.log('Result status:', result.status); // 'completed'
The Complete Architecture

The Triad of Smoke Monkey

Everything required to build, drive, and visualize looping AI agents in TypeScript. Designed as three interoperable, modular packages with zero runtime bloat.

OPEN SOURCE AI HARNESS

Smoke Monkey Harness

Zero-Dependency TypeScript Agent Loop & Agent APIs

The open source AI agent harness that turns an LLM into an autonomous engineer. Features an explicit 6-phase state machine (explore → plan → edit → verify → recover → complete), 24 built-in tools, token budget compaction, and composable TypeScript agent APIs.

0
Dependencies
24
Built-in Tools
< 180 kB
Package Size
Self-healing loop with runaway & infinite-spin guards
Automatic conversation compaction under token limits
Multi-provider LLM runtime:
NVIDIA Gemini OpenAI Claude Ollama
Granular permissions: allow-all, deny-all, ask-default
harness-snippet.tstypescript
import { createAgent } from 'smoke-monkey-harness';
const agent = createAgent({
provider: 'nvidia',
model: 'nvidia/nemotron-3-super-120b-a12b',
apiKey: process.env.NVIDIA_API_KEY,
workspacePath: process.cwd(),
});
// Human-in-the-loop permission prompt
agent.on('permission.required', (e) => {
agent.resolvePermission(e.data.toolCallId, 'allow');
});
const result = await agent.run('Refactor auth to JWT and run tests');
console.log(result.status); // 'completed'
CHAT INFRASTRUCTURE

Smoke Monkey UI

Provider-Agnostic AI Chat UI & Canvas

Drop-in developer chat UI and headless runtime. Includes streaming markdown, live tool call cards, reasoning/thinking traces, mermaid diagrams, charts, file inspectors, and 14 built-in cyberpunk themes.

14
Themes
Mermaid + Code
Renderer Support
Headless useChat
Runtime
Drop-in <SmokeMonkeyChat /> or headless useChat hook
Normalized SSE streaming with SyntheticStream support
Interactive tool call execution cards & prompt modals
Zero backend required to prototype with demo mode
ui-snippet.tstypescript
import { SmokeMonkeyChat, SyntheticTransport } from '@smoke-monkey/ui';
import '@smoke-monkey/ui/ui.css';
// SyntheticTransport provides canned streaming demo without keys!
const transport = new SyntheticTransport();
export function AgentChatCanvas() {
return (
<SmokeMonkeyChat
transport={transport}
model="qwen3:8b"
theme="dark"
layout="coding"
className="h-[650px] rounded-xl border border-white/10"
/>
);
}
MCP ECOSYSTEM

Smoke Monkey MCP

Stdio Model Context Protocol Server

Expose the harness directly to Claude Code, Cursor, Codex, and opencode. Plan agent architecture, scaffold TypeScript projects on disk, verify types, and inject 25 production-engineering skills category-wise.

20
MCP Tools
25 Bundled
Agent Skills
Claude, Cursor, Codex
Supported Hosts
Run instantly with zero install: npx -y smoke-monkey-harness-mcp
Scaffold full looping agent projects in seconds (harness_scaffold)
Inject 25 skills: TDD, Frontend UI, Security, Code Review
Standard JSON-RPC 2.0 over stdio and Streamable HTTP
mcp-snippet.jsonjson
// In Claude Code, Cursor, or .mcp.json:
{
"mcpServers": {
"smoke-monkey": {
"command": "npx",
"args": ["-y", "smoke-monkey-harness-mcp"]
}
}
}
// Gives your IDE 20 agent-building tools:
// harness_plan, harness_scaffold, harness_verify,
// harness_skills_by_category, harness_guide
Model Context Protocol

Drive the Harness from Any MCP Host

Smoke Monkey ships an official stdio MCP server. Point Claude Code, Cursor, or Codex at it to plan architectures, scaffold TypeScript agent harnesses, and verify builds in seconds.

npx -y smoke-monkey-harness-mcp

25 Bundled JIT Engineering Skills

Loaded just-in-time via SKILL.md. Zero prompt bloat until the agent needs them:

Frontend
frontend-ui-engineering
Craft accessible, non-AI-aesthetic, design-system aligned interfaces
QA
test-driven-development
Red-green-refactor loop with comprehensive unit & fixture tests
Backend
api-and-interface-design
Ergonomic TypeScript APIs with typed schemas and clean boundaries
DevOps
security-and-hardening
Threat modeling, dependency auditing, and sandboxed execution
Core
debugging-and-error-recovery
Hypothesis testing, stack trace reproduction, and auto-rollback
Quality
code-review-and-quality
Automated linter checks, ADR compliance, and anti-pattern detection
mcp_servers.config
claude-code-mcp.jsonjson
{
"mcpServers": {
"smoke-monkey-harness": {
"command": "npx",
"args": ["-y", "smoke-monkey-harness-mcp"]
}
}
}
Interactive Loop Runner

Watch the Agent Loop In Real Time

Experience the autonomous phase machine: explore the workspace, plan edits, ask for permission, call tools, and verify tests without leaving the page.

Select Active Scenario
Runtime Theme & Tokens
Smoke Monkey
Smoke Monkey
Runtime Ready
1explore
→
2plan
→
3edit
→
4verify
→
5recover
→
6complete
●Summarize this repo and fix the failing tests
+
Smoke Monkey

Smoke Monkey Agent Runtime

Click “Run Agent Loop” to simulate autonomous tool execution.

🧠186
Extensive Built-In Arsenal

24 Native Tools. Zero Config.

Smoke Monkey ships with filesystem, terminal, git, search, and agent management tools ready to execute out of the box with built-in permission policies.

⇄ Swipe horizontally to inspect22 tools
Tool NameGroupDescriptionDefault PolicyExample Call
read_filefilesystemRead file contents with byte and line slice boundsallowread_file({ path: "src/index.ts", startLine: 1, endLine: 50 })
write_filefilesystemCreate new files or overwrite existing ones safelyaskwrite_file({ path: "src/config.ts", content: "export const PORT = 3000;" })
edit_filefilesystemSearch and replace exact target strings in codeaskedit_file({ path: "src/auth.ts", target: "verifySession()", replacement: "verifySessionV2()" })
line_editfilesystemSingle line insert, delete, or replace operationsaskline_edit({ path: "package.json", line: 14, mode: "replace", content: " "version": "1.2.0"," })
replace_linesfilesystemMulti-line block replacements by line rangesaskreplace_lines({ path: "src/api.ts", start: 20, end: 25, content: " return res.status(200).json(data);" })
apply_patchfilesystemApply unified diff patches directly to filesaskapply_patch({ path: "src/math.ts", patch: "@@ -1,3 +1,3 @@ -let x = 1; +let x = 2;" })
delete_filefilesystemDelete file with safety check against project rootdenydelete_file({ path: "temp.txt" })
list_directoryfilesystemList files and directories with depth controlsallowlist_directory({ path: "src", recursive: false })
inspectfilesystemInspect metadata, file sizes, timestamps, and typesallowinspect({ path: "package.json" })
run_commandterminalRun shell commands with timeout and output truncationaskrun_command({ command: "pnpm lint" })
run_testterminalExecute automated test suites and parse test exit codesaskrun_test({ command: "npm test" })
globsearchFast pattern matching across workspace filesallowglob({ pattern: "**/*.test.ts" })
grepsearchRipgrep-style content search across directoriesallowgrep({ query: "createAgent", searchPath: "src" })
git_statusgitGet uncommitted changes, staged files, and branch statusallowgit_status()
git_diffgitView line-by-line unified git diffs for workspaceallowgit_diff({ staged: false })
git_loggitInspect recent commit history and author messagesallowgit_log({ count: 5 })
ask_useragentPause execution and solicit interactive input from developerallowask_user({ question: "Which port should the server bind to?" })
context_manageagentExplicitly prune or compact active prompt messagesallowcontext_manage({ action: "compact" })
todo_writeagentPersist plan tasks and track completion statusallowtodo_write({ todos: ["Fix tests", "Deploy"] })
finish_taskagentDeclare goal completion with final status and summaryallowfinish_task({ summary: "Refactored auth to JWT." })
list_skillsagentDiscover all available SKILL.md skills in workspace and global dirsallowlist_skills()
use_skillagentLoad full SKILL.md workflow into context just-in-timeallowuse_skill({ name: "frontend-ui-engineering" })
Interactive State Machine

Agentic AI Architecture: The 6-Phase State Machine

An explicit, deterministic AI agent loop. Explore, plan, edit, verify, recover, and complete—with automated error demotion and zero runaway loops.

Interactive Diagram · Pan & Zoom with scroll / drag

Zero Database Required

No PostgreSQL, SQLite, or Redis to spin up. State is persisted in lean JSON session files or your custom storage adapter, making deployments trivially lightweight.

Automatic Context Compaction

When token usage approaches model context limits, conversation history is automatically compacted into high-fidelity summaries so the run continues indefinitely without overflow.

Resumable Sessions

Pass a stable sessionId to resume multi-turn coding sessions across agent invocations. History, tool results, and plan states hydrate seamlessly across restarts.

Zero Vendor Lock-In

Works with Any LLM Provider

Switch from NVIDIA Nemotron to Gemini, OpenAI, Claude, or local Ollama with a single configuration parameter. Any OpenAI-compatible endpoint works out of the box.

NVIDIA NIM
Cloud / Hosted

High-throughput enterprise inference

Env KeyNVIDIA_API_KEY
Recommendednvidia/nemotron-3-super-120b-a12b
Google Gemini
Cloud API

2M+ token multimodal context window

Env KeyGEMINI_API_KEY
Recommendedgemini-1.5-pro
OpenAI
Cloud API

Industry benchmark for function calling

Env KeyOPENAI_API_KEY
Recommendedgpt-4o / o1
OpenRouter
Universal Router

Access 200+ models with a single unified key

Env KeyOPENROUTER_API_KEY
Recommendedanthropic/claude-3.5-sonnet
xAI (Grok)
Cloud API

Real-time reasoning and coding power

Env KeyXAI_API_KEY
Recommendedgrok-2-latest
Ollama (Local)
Local Inference

Zero cloud dependencies, run on Mac/Linux

Env KeyNone (Localhost:11434)
Recommendedqwen3:8b / llama3.1
Framework Benchmark & Comparison

AI Agent Harness Framework Comparison

Comparing the Smoke Monkey zero-dependency TypeScript agent harness against LangChain, CrewAI, and building an agent from scratch.

⇄ Swipe horizontally to compareSmoke Monkey vs Others
CapabilitySmoke MonkeyLangChain / LangGraphCrewAIFrom Scratch
Runtime Dependencies0 (Zero)80+ packagesHeavy Python deps0 (Roll your own)
Database Required❌ None (Lean JSON sessions)⚠️ Postgres / Vector DB⚠️ SQLite / ChromaDBManual DB setup
Phase Machine Loop✅ 6-Phase self-healing⚠️ Graph abstraction⚠️ Sequential / hierarchical❌ Manual state loops
Human-in-the-Loop✅ allow / deny / ask policies⚠️ Complex callbacks⚠️ Limited CLI prompts❌ Re-implement prompts
Built-in Tools✅ 24 native dev tools⚠️ Third-party community⚠️ Basic tool bindings❌ Hand-code each tool
Model Context Protocol (MCP)✅ Native stdio & HTTP client/server⚠️ Third-party wrapper❌ Experimental❌ Manual JSON-RPC spec
Context Compaction✅ Automatic token summarization⚠️ Manual memory chains⚠️ Window truncation❌ Token window crashes
TypeScript Native✅ 100% Strict TypeScript (No Python)⚠️ Port of Python library❌ Python only⚠️ Manual TypeScript setup
Open Source License✅ 100% MIT Permissive (Zero Lock-in)⚠️ MIT with LangSmith upsell⚠️ Telemetry & enterprise lock-inCustom
Got Questions?

Frequently Asked Questions

Everything you need to know about the architecture, permissions, tools, and deployment.

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.