noumen — the coding agent you npm install

Install noumen, wire up a provider and a filesystem, and ship your first coding agent in minutes.

Setup

Every noumen agent needs three things: an AI provider, a virtual filesystem, and a virtual computer.

Choose a provider

Pick one of the three built-in providers. Each takes an API key and an optional default model.

import { OpenAIProvider } from "noumen";

const provider = new OpenAIProvider({
  apiKey: process.env.OPENAI_API_KEY!,
  model: "gpt-4o", // default
});

import { AnthropicProvider } from "noumen";

const provider = new AnthropicProvider({
  apiKey: process.env.ANTHROPIC_API_KEY!,
  model: "claude-sonnet-4-20250514", // default
});

import { GeminiProvider } from "noumen";

const provider = new GeminiProvider({
  apiKey: process.env.GEMINI_API_KEY!,
  model: "gemini-2.5-flash", // default
});

Configure virtual infrastructure (sandbox)

All tool I/O routes through VirtualFs and VirtualComputer — the sandboxing boundary. For local development, use the unsandboxed Node.js implementations:

import { LocalFs, LocalComputer } from "noumen";

const fs = new LocalFs({ basePath: "/path/to/your/project" });
const computer = new LocalComputer({ defaultCwd: "/path/to/your/project" });

For production or untrusted agents, swap in a sandboxed implementation like SpritesFs / SpritesComputer (remote containers) or write your own adapter for Docker, E2B, etc. See Virtual Infrastructure.

Create a Code instance

The Code class wires everything together:

import { Code } from "noumen";

const code = new Code({
  aiProvider: provider,
  virtualFs: fs,
  virtualComputer: computer,
  options: {
    sessionDir: ".noumen/sessions",
    model: "gpt-4o",
    maxTokens: 8192,
    autoCompact: true,
  },
});

Run a prompt

Create a thread and iterate over the stream events:

const thread = code.createThread();

for await (const event of thread.run("Fix the failing test in utils.test.ts")) {
  switch (event.type) {
    case "text_delta":
      process.stdout.write(event.text);
      break;
    case "tool_use_start":
      console.log(`\nUsing tool: ${event.toolName}`);
      break;
    case "tool_result":
      console.log(`Result: ${event.result.content.slice(0, 100)}`);
      break;
    case "message_complete":
      console.log("\n--- Done ---");
      break;
    case "turn_complete":
      console.log(`Tokens used: ${event.usage.total_tokens}`);
      break;
  }
}

Full example

import {
  Code,
  OpenAIProvider,
  LocalFs,
  LocalComputer,
} from "noumen";

const code = new Code({
  aiProvider: new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY! }),
  virtualFs: new LocalFs({ basePath: process.cwd() }),
  virtualComputer: new LocalComputer({ defaultCwd: process.cwd() }),
  options: {
    sessionDir: ".noumen/sessions",
    autoCompact: true,
  },
});

const thread = code.createThread();

for await (const event of thread.run("Add input validation to the signup handler")) {
  if (event.type === "text_delta") process.stdout.write(event.text);
  if (event.type === "tool_use_start") console.log(`\n[${event.toolName}]`);
}

What's next

Providers -- detailed configuration for each AI provider
Tools -- the six built-in coding tools and how to add your own
Stream Events -- every event type your app can handle

Getting Started

Installation