omoya

Omoya · transparent Bun agent harness

See what your agent sees.

Omoya runs an AI agent in your terminal, your browser, a script, or your own program. All four share one small Bun (opens in new tab) core with no dependencies. You can read and edit everything the model sees. The operating system keeps the agent's writes inside its folder.

no install 
$ bunx omoya --login
$ bunx omoya
global 
$ bun add -g omoya
$ om --login
checkout 
$ git clone https://github.com/boazsegev/omoya.git
$ cd omoya && bun bin/om --login

Read the docs →Source on GitHub →npm →

~/project — om
  1. $ om --login# configure an endpoint (OAuth, token, or local)
  2. $ om --list# print the available models
  3. $ om --model ollama/gpt-oss:20b# a local Ollama model needs no account
  4. $ om --safe# read-only tools only
  5. $ echo "Summarize this project" | om-agent# JSONL events on stdout
  6. $ om --serve --port 9900# the same agent, in your browser
  7. $

Why Omoya

See what the model sees, and decide what it can change.

  1. See everything

    Read and edit the exact context the model receives. Watch every tool call and see a diff of every edit.

  2. Writes stay in the agent's folder

    The OS sandbox enforces this, not a prompt. Without a sandbox, only read-only tools run.

  3. Each project keeps its own memory

    Skills, prompts, settings, and jobs live in ai- files inside the project folder. This limits context leaks between projects.

  4. Good work habits come built in

    The core skill teaches agents to keep memory files and task lists, and to delegate well.

  5. No setup for what you already have

    Omoya finds local Ollama and LM Studio servers, SearXNG (opens in new tab), and common API keys on its own.

  6. Switch models freely

    All providers speak one event model. You can switch providers and models mid-session, and nothing else changes.

One core, four ways to run it

Terminal, browser, script, or your own program.

Terminal

An interface that hides nothing

om streams answers and thinking as they arrive. It shows every tool call, and you can inspect or fix any part of the conversation. Ctrl-O shows the full text of any message or tool call. Ctrl-C stops a response and keeps what arrived so far. /context-edit, /context-rollback, and /context-system fix, rewind, or extend what the model sees.

om --resume latest   # pick up where you left off
om --help            # every key and command

Browser

Your terminal agent, in the browser

The browser app runs the same agent engine as the terminal. You get all of the terminal's features in a web interface. Closing a tab doesn't stop the agent's work, and one server can host several projects.

Safe by default. The server listens only on loopback, so nothing outside your machine can reach it. Omoya blocks DNS-rebinding attacks, so websites in your browser can't control it either.

LAN access is opt-in. --host 0.0.0.0 lets other devices on your network use the app. Rebinding protection stays on, so this is just as safe on trusted networks. Never use it on public Wi-Fi. With omd, you can restart the app from the browser when you want a fresh start.

om --serve --port 9900
omd --port 9900      # keep the app and jobs running

Scripts

Drive it from a script

om-agent runs the full agent loop without the terminal interface. It reads a conversation on stdin and writes JSONL events to stdout. om-io sends exactly one request to the model and runs no tools. Each kind of failure has its own exit code.

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

echo "Hello" \
  | om-io --model anthropic/claude-sonnet-5

Library

Inside your program

omoya/agent is the headless core. Import omoya/app to add the terminal, browser, and Markdown layers. Semantic versioning covers the library, not the App and GTUI APIs.

import Agent from "omoya/agent";

const env = await Agent.Env.open(process.cwd());
const agent = await Agent.create({
  env, model: "ollama/gpt-oss:20b", can: { write: false },
});

Sessions & jobs

Sessions and jobs

Omoya saves sessions as JSONL files. You can resume, rename, edit, roll back, fork, or delete them. om-jobs runs scheduled agent tasks, each a plain Markdown file in ai-jobs/tasks/. Run it from cron, or let omd run it about every five minutes.

om-jobs init     # create ai-jobs/ (idempotent)
om-jobs run      # one best-effort scan, executes due tasks

Security

Writes stay in the agent's folder.

The operating system enforces this, not a prompt. --safe limits the agent to read-only tools at any time.

  • Each agent can only write inside its working folder.
  • The OS sandbox (macOS Seatbelt, Linux Bubblewrap) enforces this. Without a sandbox, only read-only tools run.
  • Child agents get the same folder or a smaller one.
  • Programs the agent starts don't inherit variables with names like KEY, TOKEN, or SECRET.
  • Session logs live in your user settings folder, outside the project, by default.

Note: the sandbox limits writes, not reads. An agent can still read data outside its folder, but it can't change it. See SECURITY.md.

Providers

Bring the models you already use.

Omoya speaks the OpenAI, Anthropic, Kimi/Moonshot, Ollama, and Gemini APIs. Ready-made endpoints cover services such as Codex, Claude, GitHub Copilot, LM Studio, Azure OpenAI, and xAI.

om --login sets up any endpoint. Omoya also finds the API keys and local servers in this table on its own. Finding models can be slow, so log in with your API keys to cache the model lists.

Claude OAuth caution: Anthropic may restrict accounts that use subscription quotas with other harnesses. Use an Anthropic API key or extra credits instead.

foundendpoint
OPENAI_API_KEYopenai
ANTHROPIC_API_KEYanthropic
MOONSHOT_API_KEYmoonshot (Kimi Platform)
KIMI_API_KEYkimi (Kimi Platform)
Ollama running on localhost:11434ollama
LM Studio running on localhost:1234lm-studio
XAI_API_KEYxai
AZURE_OPENAI_API_KEY + AZURE_OPENAI_BASE_URLazure-openai
GEMINI_API_KEY or GOOGLE_API_KEYgemini

Yours to control

Owned by you, visible to you.

The system message is yours

Each new session builds its instructions from three AGENTS.md files: Omoya's own, your user folder's, and the project's. Nothing hidden sits between your instructions and the model.

The project is the unit of memory

What an agent learns stays in its project folder, in files such as ai-settings.json, ai-skills/, and AGENTS.md. Other projects can't see them. To share something everywhere, put it in your user settings folder.

Web search without an account

Omoya tries the provider's own web tools, then an MCP server, then its built-in search. Built-in search uses SearXNG (opens in new tab) if you have it, then DuckDuckGo and Mojeek. Set BRAVE_API_KEY to add Brave.

Direct tool access

Run any tool straight from your shell. om-tool --list lists them, om-skills core prints a skill, and om-tools2bash writes shell wrappers.

Get started.

Every command has built-in --help. Settings and other details are in the guide. The library API is in the generated reference.

no install 
$ bunx omoya --login
$ bunx omoya
global 
$ bun add -g omoya
$ om --login
checkout 
$ git clone https://github.com/boazsegev/omoya.git
$ cd omoya && bun bin/om --login