TRANSPARENT BUN AGENT HARNESS

See what your agent sees.

Omoya puts the whole agent loop in your hands — model selection, system instructions, context, tools, sessions, and security policy. Work in the terminal, stream structured events through a headless process, or embed the Bun library in your own project.

Install from npm View the source on GitHub →

bun add -g omoya
omoya --login
om

One core, every surface

The terminal interface

A long-running TUI that streams responses and thinking, shows tool activity as it happens, and keeps the current context inspectable and editable — menus, questionnaires, multi-line input, completion, themes, and queued follow-ups included.

om
om --resume latest
om --safe

Drive it from a script

om-agent runs the complete tool loop without the TUI: one context in on stdin, normalized JSONL events out on stdout, diagnostics on stderr. om-io performs exactly one provider request — stable streams, distinct exit codes, real cancellation.

echo "Summarize this project" \
  | om-agent --model ollama/gpt-oss:20b

Embed the library

lib/agent.js is the headless core entry point, publishing Agent.Context, Agent.Env, and Agent.IO. Import omoya/app when CLI, Markdown, and UI concerns are needed — headless applications stay free of the interface graph.

import Agent from "omoya/agent";
const env = await Agent.Env.create();
const agent = new Agent({ env, model: "ollama/gpt-oss:20b" });

Serve it to a browser

om --serve starts a standalone chat SPA over HTTP with a WebSocket carrying the same Agent/Env events used everywhere else. The server owns the agent; the browser only renders it. Loopback-bound by default.

om --serve --port 9900

Sessions that outlive the UI

Named sessions persist as JSONL under the user settings directory, outside the working project. Resume, rename, edit, roll back, fork, or delete them — anonymous sessions write nothing.

om --resume latest

Project jobs, under your control

om-jobs runs project-local Markdown tasks by explicit init/run/disable. Manual run is primary; an optional daemon scans immediately and then five minutes after each child completes. Cron and restart policy stay yours: use an explicit runtime, wrapper, and project cwd.

om-jobs init
om-jobs run
om-jobs daemon foreground

What makes it useful

Transparent by default

See what the model sees. Inspect the context, interrupt work, change course, and keep filesystem operations rooted in the current project. No hidden third-party CLI between your instructions and the provider.

Tools with boundaries

Scoped file tools, bounded shell commands, MCP servers, skills, notes, and child workers — all composable, with read-only safe mode and an OS write sandbox for mutating tools. Security metadata never reaches the model.

Providers are plugins

OpenAI Responses-compatible endpoints (including ChatGPT/Codex OAuth), Anthropic Messages, GitHub Copilot, Kimi/Moonshot, and Ollama — normalized into one context and event model. Switch models without leaving the TUI.

The project is the unit of memory

What an agent learns belongs to the project folder it learned it in: ai-settings.json, ai-skills/, ai-prompts/, ai-jobs/, AGENTS.md. Open a different folder and the agent starts from package defaults.

Filesystem security, enforced

The current working folder is the agent's root — enforced in layers, not by prompt instructions alone:

File tools accept only relative paths inside the working folder; absolute paths and parent traversal are refused, and read rejects symbolic links.
Shell commands refuse cd, ln, ls, and visible arguments pointing outside the working folder.
Mutating tools fork under an OS write sandbox — macOS Seatbelt or Linux Bubblewrap — mounting only the working folder as writable.
With no supported sandbox, the agent forces safe mode: only read-only tools exist. --safe selects the same posture at any time.
Session logs live outside the project tree, so cwd-scoped tools can never rewrite their own history.

Reads are not fully sandboxed by design: do not run the agent in a tree containing untrusted symlinks, and do not rely on bash to protect secrets outside that tree.

Start in one minute

bunx omoya --help          # run without installing
om --model ollama/gpt-oss:20b   # or point at a local model
om-tool --list             # run tools directly, no agent

Requires Bun. Every shipped command — omoya, om, om-agent, om-io, om-tool, om-skills, om-jobs — has built-in --help.