A desktop coding agent with free access to frontier models.
AGENTS.md
OmniRush.ai is a free, open-source desktop app (macOS, Windows, Linux) for doing work with AI agents on your own files — an open-source alternative to Claude Cowork and Codex, built on OpenCode with a curated provider experience. Desktop mode keeps files local; cloud is optional. Three surfaces live in this repo:
- Desktop app (
apps/,packages/) — local-first agent workspace: chat on files, skills, browser automation, scheduled automations, Anthropic-compatible plugins. - OmniRush.ai MCP gateway (
ee/apps/den-api) — one URL per Den deployment (<den-api-origin>/mcp/agent; omnirush.ai runs no hosted Den) that brings org-assigned skills, plugins, and connections (Google Workspace, Microsoft 365, MCPs) into Codex, Claude Code, Cursor, or any MCP client viasearch_capabilities/execute_capability. - OmniRush.ai Den (
ee/apps/den-*) — the org control plane: provision inference, manage teams and access, set desktop policies, publish skills and plugins through marketplaces.
The app consumes OmniRush.ai server surfaces (self-hosted or hosted) rather than inventing parallel behavior. The product UI prioritizes the internal model gateway and a small set of widely used providers.
Confidentiality (hard rule — this repo is public)
Never let a branch name, commit, PR text, comment, fixture, or evidence identify a customer, prospect, partner, or outside person; use internal ticket IDs, and escalate any leak instead of rewriting history.
Verification (every change)
- Proof is a journey spec in
evals/specs/**orscenarios/<name>/e2e.test.ts(*.e2e.test.tsdrives the app/Den;*.test.tshits a server or gateway boundary). Unit tests are not proof and never live in journey directories; the boundary ratchet rejects new ones that import product source, read the repo, or spawn test runners. - Default is zero new test files: run the journey spec that covers the change; extend it for a gap; new file only for a new user journey.
- Run
pnpm evals:e2e <slug>orpnpm evals:pr specs/<name>.test.ts; report the printed placement and verdict. Passedrequires an observable assertion for every claim; skips are never passed.- Docs/comments, types-only, and inert agent config may skip runtime proof — say so.
- Skill chain:
write-a-spec→run-tests→diagnose-a-red-runwhen red →publish-evidence.
Pull requests
- Do not default to draft PRs. A request to create or make a PR means a
ready-for-review PR once the required proof is published. Use a draft only
when the requester explicitly asks for one or the current verdict is
IncompleteorFailed, and state exactly what proof is missing. - Run tests and report commands + results. A runtime-observable change is not done until its test evidence is visible on the PR. If validation cannot run, say why and give exact repro steps.
Local headless web (agents)
pnpm world up dev-headless --detachlaunches an isolated browser UI + localomnirush-serverwithout Electron as a detached script world.pnpm dev:headless-webremains a compatibility alias with its prior foreground default (--detachstill works). Readtmp/dev-headless-web.jsonfor the owner-only runtime manifest. It does not use~/.config/omnirush/server.json, and its engine keeps its own sessions database attmp/dev-headless-opencode.dbinstead of the desktop app's~/.local/share/opencode/opencode.db. Stop a running script withpnpm world down dev-headless; pass script options after--, for examplepnpm world up dev-headless --detach -- --replace --keep-tokens. Cloud sign-in is copy/paste handoff (Den cannot redirect grants to localhost): Account → Sign in → copy OmniRush.ai link on Den → Paste sign-in code in Settings.
Coding
- pnpm only, never npm/yarn. TypeScript: never
any, typecasts, orasunless 100% necessary or instructed. - Prefer Tailwind, React, shadcn/ui (Base UI), TanStack Query, Zustand, Zod,
Drizzle, Better-Auth. Reuse
@/components; end users are non-technical. - Smallest possible diff, then make it smaller. Propose the simpler solution. No fallback expressions when types or control flow already guarantee a value.
- If asked to do too much at once, stop and say so.
Hands-on PR previews
For a preview the user can test inside Codex, use preview-my-work: named Daytona worlds for Den or real Electron through noVNC, with isolated scenarios, frontend updates, reset and teardown.
Reusable scenarios
Start at scenarios/README.md for workflows, videos, and documentation screenshots. Keep each scenario together; reuse the existing world, testkit, behavior, and DocShot packages. Author ordinary TypeScript functions and React/Remotion components.