- Go 93.1%
- JavaScript 6.2%
- Python 0.7%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| .forgejo | ||
| .noe | ||
| agent | ||
| cmd/noe | ||
| docs | ||
| examples | ||
| internal | ||
| scripts | ||
| spikes | ||
| stdlib | ||
| tests | ||
| .gitignore | ||
| AGENTS.md | ||
| biome.json | ||
| go.mod | ||
| go.sum | ||
| LICENSE | ||
| README.ja.md | ||
| README.md | ||
| run-js-stream-challenge.txt | ||
NOE — No Ordinary Engine
JavaScript for you and your agents.
NOE is a pure-Go JavaScript runtime with built-in autonomous AI agents. Write scripts yourself, or give an agent a task and let it write and execute JavaScript to carry out the work.
Agents use JavaScript to read and edit files, call HTTP APIs, run commands, and delegate tasks to other agents. Your scripts can use the same agent APIs to coordinate work, inspect results, and decide what happens next.
Run NOE from the command line, or embed its runtime and agents directly in your Go application. Powered by QuickJS through go-quickjs. No C toolchain required.
NOE prioritizes Web standards and convenient host APIs. Standard Web APIs use
their standard names; NOE-specific host APIs use explicit noe: modules.
See the standard library API policy
and the filesystem migration.
What you can do
- Automate with JavaScript. Work with files, HTTP, streams, and processes using ES modules and async/await.
- Give agents executable tools. Agents write JavaScript that combines runtime APIs, your modules, and existing command-line tools.
- Build agent workflows. Coordinate agents with different models, combine their results, and express branching and repetition in code.
- Control agent behavior. Observe running tasks, send additional instructions, cancel work, and customize model and tool interactions with JavaScript hooks.
- Embed in Go. Add scripting and managed agents to your application through the public Go APIs.
Get started · Agent guide · Go embedding · Examples · 日本語
v2.32.0 release notes · Download binaries
v2.32.0 adds task keyword search to noe:docs and per-call deadlines,
saved default exports, and live progress for the run_js agent tool.
It also reduces repeated work in the runtime, standard library, and agent.
v2.31.0 adds optional full-stream storage for overflowing agent tool output, honors provider retry hints, and uses reported input tokens to improve context estimates. The built-in catalog includes GPT-6.2 Sol and Astra on both OpenAI providers and OpenRouter.
v2.30.0 adds lazy directory iteration and bounded-memory file copying in
noe:fs, plus HMAC key generation and JWK import/export through Web Crypto.
See the filesystem example and
jose interoperability example.
v2.29.0 reuses OpenAI Responses WebSocket connections within managed agent runs for both ChatGPT OAuth and API-key providers. Unchanged conversations upload only new input items. Standalone model calls retain HTTP/SSE; provider configuration can also select SSE for managed runs.
v2.28.0 adds batched SQLite row iteration, corrects Blob/File/FormData and stream iterator behavior, and reuses managed context analysis between model requests. It also corrects configured reasoning observations. See the release notes for compatibility changes and verification.
v2.27.0 updates go-quickjs to v0.38.0 with JIT disabled, incorporates compiler
and parser fixes, and makes os.EOL return CRLF on Windows and LF elsewhere.
See the release notes for behavior changes and verification.
v2.26.1 makes JavaScript the agent's primary programming language in the built-in instructions, including when external instructions are disabled. See the release notes for scope and verification.
v2.26.0 updates the OpenAI and OpenRouter Go SDKs and reduces redundant JSON encoding when preparing Responses requests. Existing provider and agent APIs are preserved. See the release notes for measurements and verification.
v2.24.0 corrects Headers/Response, body consumption, tee cleanup, cloned byte ownership and multipart data handling. See the release notes for behavior changes and the Web API examples for runnable cases.
v2.20.0 corrects existing Web Crypto key usage, extractability, BufferSource, and error contracts. Private snapshots govern key operations; mutable public metadata cannot grant authority. See the jose example and supported standard APIs and remaining gaps. No new algorithm family, host capability, or runtime dependency is added.
v2.21.0 adds User Timing entries and CustomEvent, corrects UTF-8 encoding / decoding, and implements standard EventTarget listener identity, capture, once, passive and signal cleanup. See the Web API basics, decoder/listener contract, and example.
Web Storage remains available from v2.19.0, including runtime-local
sessionStorage and explicit-file localStorage. See the
storage example and
Go embedding contract. Consumers using
unkeyed Modules literals must move to named fields. Raw TLS/UDP sockets
and HTTPS/WSS remain available from the preceding releases.
When upgrading from v2.15.0 or earlier, also read the v2.16.0 migration guide for removed filesystem/process/HTTP imports, standard I/O, and lifecycle changes.
For earlier changes and migration guidance, see the release history, v2 migration guide, and execution guide.
Get started
Download a binary above, or build from source with Go 1.27.2 or later. No C toolchain is needed:
git clone https://forge.harakara.site/littleisland/noe
cd noe
CGO_ENABLED=0 go build -o noe ./cmd/noe
./noe --version
# noe v2.24.0
The examples below assume the repository root is your working directory.
Run JavaScript
./noe eval 'console.log(1 + 1)'
# 2
./noe run examples/basics/hello.js
# Hello from NOE!
Use eval for short checks and run for scripts. Scripts support ES modules, async/await, files, Fetch, HTTP serving, and child processes. See the examples for JSON processing, reports, downloads, and more.
Read the English API reference bundled with your executable using ./noe docs, ./noe docs noe:fs, or ./noe docs noe:sockets connect. Scripts and agents can read the same reference through import { docs } from "noe:docs".
Run an agent
For this example, save your OpenCode Go API key in ~/.config/noe/credentials/opencode-go-api-key (or $XDG_CONFIG_HOME/noe/credentials/opencode-go-api-key when set). OpenRouter, ChatGPT sign-in, and OpenAI API keys are also supported; follow the agent setup guide for credentials and provider selection.
Save this as task.js:
import { run_agent } from "noe:agent";
const result = await run_agent({
provider: "opencode-go",
model: "deepseek-v4.1-flash",
effort: "auto",
}, "Read README.md and summarize it in three points.");
if (result.lastResult?.state !== "completed") {
throw new Error(result.lastResult?.error || result.reason || "Agent failed");
}
console.log(result.lastResult.answer);
./noe run --observe task.js
Roots require explicit provider, model, and effort. --observe displays progress and the final answer. The agent guide covers saved logs, task files, and next steps.
Guides
| Task | Guide |
|---|---|
| Set up credentials, run an agent, and observe progress | Agent guide |
| Find API arguments, CLI options, lifecycle controls, and exit codes | API reference |
| Reuse local JS and verified ESM libraries | Import maps · HTTP/HTTPS URL imports |
| Configure providers and choose models | Provider configuration · Model catalog |
| Add instructions, hooks, or context policies | Instructions · Hooks and context |
| Inspect running work and process logs | Observation · JSONL events |
| Inspect/generate images or request structured decisions | Images · Decisions |
| Use live child-process I/O or HTTP | Processes and streams · HTTP examples |
| Use positional file I/O, TCP/Unix sockets, or OS signals | Files, sockets, and signals |
| Embed generic JavaScript APIs in a Go application | Standard library · Agents (English) |
| Explore examples or develop NOE | Examples · Documentation · Development guide |
Most linked guides are currently in Japanese. For older scripts, see the API migration guide.
Capabilities and compatibility
NOE is not a sandbox. Scripts and agents run with the OS privileges of the user who starts NOE, including filesystem, environment, command, and network access.
NOE uses the pinned go-quickjs engine and a NOE-maintained standard library, based on go-quickjs v0.27.0, for supported Web and Node-style APIs. NOE supports HTTP/HTTPS ESM URL imports, enabled by default in the CLI and explicitly selected by Go hosts; see URL imports. Full Node.js/Deno compatibility, npm/package management, and the original QuickJS std module are outside its scope. See the API reference for supported behavior.
License
MIT. Third-party code and data retain their respective licenses.