monkeyscode-sdk

Run the MonkeysCode coding agent from TypeScript or JavaScript. query() starts an installed mc and gives you its events: the same tools, permission rules, hooks and MCP servers as mc -p.

npm install monkeyscode-sdk        # Node 18+, ESM and CommonJS
npm install -g monkeyscode-cli     # the mc it drives, 1.0.0 or newer

import { query } from 'monkeyscode-sdk/subprocess';

const q = query({
  prompt: 'Fix the failing test',
  options: {
    cwd: '/path/to/repo',
    allowedTools: ['read_file', 'edit_file(src/**)', 'run_command(npm test:*)'],
    maxCostUsd: 1,
  },
});
for await (const e of q) {
  if (e.type === 'assistant') {
    for (const b of e.message.content) if (b.type === 'text') process.stdout.write(b.text);
  }
}
const r = await q.result;
console.log(r.subtype, r.cost_usd, await q.exitCode);

Auth: MONKEYSCODE_API_KEY, or the login saved by mc auth login.

Using Auto mode

Auto mode lets MonkeysCode pick the model for each step: Capuchin by default, a frontier model only when the task needs it. Pass model: 'auto-mode' (or 'monkeyscode-auto'), or 'auto-max' for Max quality. The plain 'auto' still means your default model, not Auto mode. Auto needs a Pro plan or above (Max: Pro+); on other plans the run ends with exit_code 4 and a plan_required card on the result.

import { query, requireSuccess, isRouteEvent, PlanRequiredError } from 'monkeyscode-sdk/subprocess';

async function run(model: string) {
  const q = query({ prompt: 'Fix the failing test', options: { cwd: '/path/to/repo', model } });
  for await (const e of q) {
    if (isRouteEvent(e)) console.log(`step ran on ${e.routed} (${e.reason})`);
  }
  return requireSuccess(await q.result);
}

try {
  await run('auto-mode');
} catch (e) {
  if (!(e instanceof PlanRequiredError)) throw e;
  console.log(e.message, e.upgradeUrl);
  if (e.fallbackModel) await run(e.fallbackModel); // e.g. capuchin-reason
}

PlanRequiredError extends McProcessError, so existing catch code still works. system/route events are informational: the routed model can change from step to step.

To run the agent inside your own Node process instead, without installing mc, use monkeyscode-agent. It has the same query().

Docs

• TypeScript guide: permissions, multi-turn, structured answers, every option
• Events and results
• SDK overview: which package to use

The MonkeysCode class (run(), stream()), ciRun and Session call a hosted endpoint that isn't live yet, so they fail with an HTTP error. Use query().

License

MIT