Skip to content

A desktop coding agent with free access to frontier models.

TypeScript

docs: rewrite README

ogsamrat0125c4dc6fbe
diff --git a/README.md b/README.md
index 020afa7a..14cbbd87 100644
--- a/README.md
+++ b/README.md
@@ -2,100 +2,147 @@
<picture>
<source media="(prefers-color-scheme: dark)" srcset="./omnirush-logo-dark.png" />
<source media="(prefers-color-scheme: light)" srcset="./omnirush-logo.png" />
- <img src="./omnirush-logo.png" alt="omnirush.ai" width="128" height="128" />
+ <img src="./omnirush-logo.png" alt="omnirush.ai" width="120" height="120" />
</picture>
+
<h1>omnirush.ai</h1>
- <p>An AI coding agent for your desktop. GPT 6 Astra and GPT-5.6 Sol are free with an omnirush.ai account. In return, the app uploads your chat sessions and workspace snapshots to omnirush.ai under your account, with secrets and personal identifiers redacted.</p>
+
+ <p><strong>A desktop coding agent with free access to frontier models.</strong></p>
+
+ <p>
+ <a href="https://omnirush.ai"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fomnirush.ai%2Fomnirush%2Fpublic%2Fusers-badge&style=for-the-badge&logo=rocket&logoColor=white" alt="Users" /></a>
+ <a href="https://github.com/omnirush-ai/omnirush-gui/releases"><img src="https://img.shields.io/github/downloads/omnirush-ai/omnirush-gui/total?style=for-the-badge&color=blue&label=downloads" alt="Downloads" /></a>
+ <a href="https://github.com/omnirush-ai/omnirush-gui"><img src="https://visitor-badge.laobi.icu/badge?page_id=omnirush-ai.omnirush-gui&left_text=views&left_color=%23555&right_color=%23f97316" height="28" alt="Views" /></a>
+ </p>
+ <p>
+ <a href="https://github.com/omnirush-ai/omnirush-gui/releases/latest"><img src="https://img.shields.io/github/v/release/omnirush-ai/omnirush-gui?label=latest&color=f97316" alt="Latest release" /></a>
+ <img src="https://img.shields.io/badge/macOS-Apple%20Silicon-black?logo=apple" alt="macOS" />
+ <img src="https://img.shields.io/badge/Linux-x64%20%7C%20arm64-FCC624?logo=linux&logoColor=black" alt="Linux" />
+ <a href="https://github.com/omnirush-ai/omnirush-gui/stargazers"><img src="https://img.shields.io/github/stars/omnirush-ai/omnirush-gui?style=social" alt="Stars" /></a>
+ </p>
+
+ <p>
+ <a href="https://omnirush.ai/download/mac"><img src="https://img.shields.io/badge/Download%20for%20macOS-000000?style=for-the-badge&logo=apple&logoColor=white" alt="Download for macOS" /></a>
+ <a href="https://omnirush.ai/download/linux-appimage"><img src="https://img.shields.io/badge/Download%20for%20Linux-FCC624?style=for-the-badge&logo=linux&logoColor=black" alt="Download for Linux" /></a>
+ </p>
+
+ <p><a href="https://omnirush.ai">Website</a> · <a href="https://github.com/omnirush-ai/omnirush-gui/releases">Releases</a> · <a href="https://www.npmjs.com/package/omnirush">CLI</a></p>
</div>
-## Download
+---
-Every build is on the [latest release](https://github.com/omnirush-ai/omnirush-gui/releases/latest). File names carry the version number, for example `omnirush-mac-arm64-1.0.8.dmg`.
+omnirush.ai is a desktop app for working with a coding agent on your own
+projects. GPT 6 Astra is the default model; GPT 6.1 Sol and the other models in
+your account's catalog are available from the model picker.
-| Platform | File to download | Notes |
-| --- | --- | --- |
-| macOS, Apple Silicon | [`omnirush-mac-arm64-<version>.dmg`](https://github.com/omnirush-ai/omnirush-gui/releases/latest) | A `.zip` of the same app is also attached. No Intel build. |
-| Windows x64 | [`omnirush-win-x64-<version>.exe`](https://github.com/omnirush-ai/omnirush-gui/releases/latest) | NSIS installer. |
-| Linux x64 (Debian, Ubuntu) | [`omnirush-linux-amd64-<version>.deb`](https://github.com/omnirush-ai/omnirush-gui/releases/latest) | Installs the GTK runtime it needs. |
-| Linux x64 (other) | [`omnirush-linux-x86_64-<version>.AppImage`](https://github.com/omnirush-ai/omnirush-gui/releases/latest) or [`omnirush-linux-x64-<version>.tar.gz`](https://github.com/omnirush-ai/omnirush-gui/releases/latest) | Needs the GTK runtime installed first (see below). |
+## Download
-Each release also has `SHA256SUMS.txt` for checking a download.
+Download the latest build from the
+[releases page](https://github.com/omnirush-ai/omnirush-gui/releases/latest).
+File names include the version, for example `omnirush-mac-arm64-3.0.1.dmg`.
-## First launch
+| Platform | File |
+| --- | --- |
+| macOS, Apple Silicon | `omnirush-mac-arm64-<version>.dmg` (a `.zip` is also attached) |
+| Linux x64, Debian/Ubuntu | `omnirush-linux-amd64-<version>.deb` |
+| Linux x64, Arch | `omnirush-linux-x64-<version>.pacman` |
+| Linux x64, Fedora/RHEL | `omnirush-linux-x86_64-<version>.rpm` |
+| Linux x64, other | `omnirush-linux-x86_64-<version>.AppImage` or `omnirush-linux-x64-<version>.tar.gz` |
+| Linux arm64, Debian/Ubuntu | `omnirush-linux-arm64-<version>.deb` |
+| Linux arm64, Arch | `omnirush-linux-aarch64-<version>.pacman` |
+| Linux arm64, Fedora/RHEL | `omnirush-linux-aarch64-<version>.rpm` |
+| Linux arm64, other | `omnirush-linux-arm64-<version>.AppImage` or `omnirush-linux-arm64-<version>.tar.gz` |
+
+Each release includes `SHA256SUMS.txt` for verifying downloads. There is no
+build for Intel Macs.
-Builds are not notarized (macOS) or code-signed (Windows) yet, so the operating system asks for one confirmation the first time.
+## First launch
-| OS | What to do |
-| --- | --- |
-| macOS 15 and later | The first open says "Apple could not verify OmniRush.ai.app is free of malware". Click **Done**, open **System Settings > Privacy & Security**, scroll to **Security**, click **Open Anyway** next to OmniRush.ai.app, then **Open**. Or run `xattr -dr com.apple.quarantine /Applications/OmniRush.ai.app` in Terminal. |
-| macOS keychain | When the app asks to use "omnirush.ai Safe Storage", enter your Mac login password and choose **Always Allow**. That item only holds the key that encrypts your omnirush.ai sign-in on this Mac; macOS asks again after the app binary changes. |
-| Windows | On the SmartScreen dialog choose **More info > Run anyway**. If setup reports "Extract: error writing to file", the download is incomplete or blocked: download it again, compare its hash with `SHA256SUMS.txt`, free some disk space, and retry. |
-| Linux | Prefer the `.deb` on Debian and Ubuntu. For the AppImage or tar.gz, install the runtime first: `sudo apt install libgtk-3-0 libnss3 libatk-bridge2.0-0 libasound2` (on Ubuntu 24.04 use `libasound2t64`), then `chmod +x` the AppImage or unpack the tar.gz. An error about `libatk-1.0.so.0` means those packages are missing. |
-| Linux keyring | Optional. With a keyring the app encrypts your sign-in with it; without one (common on Hyprland, sway, i3 and other window managers) sign-in still works, and **Settings** notes that the sign-in is kept in a private file (owner-only permissions) in the app's data folder, unencrypted. To use a keyring, run a Secret Service provider in your session, such as gnome-keyring (`sudo pacman -S gnome-keyring libsecret` on Arch, then start it with your session or `gnome-keyring-daemon --start --components=secrets`) or KeePassXC with **Secret Service Integration** enabled, or KWallet on KDE. The app finds it on the next launch and moves the sign-in into it. To pick a store yourself, start the app with `--password-store=gnome-libsecret`, `kwallet5` or `kwallet6`. |
+**macOS.** Builds are not notarized yet. On first open, macOS reports that it
+could not verify the app: click **Done**, open **System Settings > Privacy &
+Security**, click **Open Anyway** next to OmniRush.ai.app, then **Open**.
+Alternatively, run:
-## Sign in
+```bash
+xattr -dr com.apple.quarantine /Applications/OmniRush.ai.app
+```
-Click **Sign in to omnirush.ai** in the sidebar (or on the main Settings page). Your browser opens [omnirush.ai/console](https://omnirush.ai/console) with a device code; approve it there and the app is ready.
+When asked to use "omnirush.ai Safe Storage", enter your login password and
+choose **Always Allow**. This keychain item only holds the key that encrypts
+your sign-in on this Mac.
-Signing in is also your consent to the data collection described below. The app does not run prompts until an omnirush.ai account is connected.
+**Linux.** The `.deb`, `.rpm` and `.pacman` packages install their dependencies. For
+the AppImage or tar.gz, install the GTK runtime first:
-## What is collected and how it is protected
+```bash
+sudo apt install libgtk-3-0 libnss3 libatk-bridge2.0-0 libasound2 # libasound2t64 on Ubuntu 24.04
+```
-While you are signed in, the app uploads the following to omnirush.ai, linked to your account:
+Then `chmod +x` the AppImage or unpack the tarball. An error about
+`libatk-1.0.so.0` means these packages are missing.
-- session traces: your prompts, the model's replies, and tool calls, for every model you use in the app;
-- snapshots of the workspace the chat runs in: file contents, the file list, and git metadata and diffs.
+On Linux the app stores your sign-in in the system keyring when one is
+available (gnome-keyring, KeePassXC with Secret Service, or KWallet). Without
+one, as is common on tiling window managers, it falls back to an owner-only
+file in the app's data folder, and **Settings** says so. To choose a store
+explicitly, start the app with `--password-store=gnome-libsecret`, `kwallet5`
+or `kwallet6`.
-There is no limit on how much one chat uploads in total: a chat keeps sending snapshots for as long as it runs. Only single uploads are limited (4 MiB per file, 64 MiB per snapshot).
+## Sign in
-Before anything leaves your machine:
+Click **Sign in to omnirush.ai** in the sidebar or on the Settings page. Your
+browser opens [omnirush.ai/console](https://omnirush.ai/console) with a device
+code; approve it and the app is ready. The app does not run prompts until an
+account is connected.
-- some paths are never uploaded: `.git`, `node_modules`, `.env*`, `.ssh`, `.aws`, `.gnupg`, `.npmrc`, `.pypirc`, `id_rsa` and `id_ed25519`, key and certificate files (`.pem`, `.key`, `.p12`, `.pfx`, `.jks`, `.keystore`), `.docker/config.json`, and any file or folder whose name has the word credential(s), secret(s) or private key(s) in it (`secrets.ts`, `aws-credentials.json`, `private_key.txt`);
-- other files whose path contains a credential word (key, token, password, wallet, seed, mnemonic and similar) are dropped too, unless they have a source, config or docs extension such as `.ts`, `.py`, `.json`, `.yml`, `.toml`, `.md` or `.txt`. Those files (for example `tokens.json` or `api-keys.md`) are uploaded with the secret values inside them redacted;
-- secret values (API keys, passwords, bearer tokens, private keys, URL passwords) are replaced with `[REDACTED]`, and personal identifiers such as e-mail addresses with `[REDACTED_PII]`. Redaction works on patterns, so a secret that does not look like one (a short plain word, for example) is uploaded as written;
-- the omnirush.ai backend applies the same rules again on its side.
+## Features
-The exact rules are in [docs/session-data-privacy.md](docs/session-data-privacy.md). What the updater contacts is described in [docs/updates.md](docs/updates.md).
+| Feature | Description | Docs |
+| --- | --- | --- |
+| Models and effort | Choose a model and an effort level (low, high, xhigh, max) per chat. You can also add your own OpenAI, Anthropic or other provider keys. | |
+| Skills and MCP servers | Add skills and MCP servers from the Library in Settings. Every model sees the same skills and tools. | [skills-and-mcp.md](docs/skills-and-mcp.md) |
+| Git workflows | The agent clones, branches, creates worktrees, commits, pushes, and opens and reviews pull requests with `gh`. Write commands ask once per session; destructive ones always ask. | [git-workflows.md](docs/git-workflows.md) |
+| Approvals | The composer's full-permissions toggle switches between asking and allowing every tool call. | [approvals.md](docs/approvals.md) |
## Updating
-From version 1.0.5 on, the app updates itself: **Settings > Updates** or the **Check for Updates...** menu item. On macOS the unsigned build downloads the new DMG and opens it; drag omnirush.ai to Applications to replace the old copy. Windows and the Linux AppImage install updates in place. The Linux tar.gz does not update itself; download the new release by hand.
-
-Installs older than 1.0.5 cannot update in-app. Download the latest release once by hand; later versions then update in-app.
+The app updates itself on macOS and Linux: use **Settings > Updates** or the
+**Check for Updates...** menu item.
-## Features
+- **macOS:** the app downloads the new DMG and opens it; drag the app to
+ Applications to replace the old copy.
+- **Linux:** the AppImage, `.deb`, `.rpm` and `.pacman` installs update in place. The
+ tar.gz does not update itself; download new releases manually.
-| Feature | What you get | More |
-| --- | --- | --- |
-| Models and effort | Pick GPT 6 Astra or GPT-5.6 Sol and an effort level (low, high, xhigh, max) per chat. You can also add your own OpenAI, Anthropic, or other provider keys. | |
-| Skills and MCP servers | Add skills and MCP servers from the Library in Settings; every model sees the same skills and tools. | [docs/skills-and-mcp.md](docs/skills-and-mcp.md) |
-| Git workflows | The agent clones, branches, creates worktrees, commits, pushes, and opens and reviews pull requests with `gh`. Write commands ask once per session, destructive ones always ask. | [docs/git-workflows.md](docs/git-workflows.md) |
-| Approvals | The composer's full-permissions toggle switches from asking to allowing every tool call. | [docs/approvals.md](docs/approvals.md) |
+Installs older than 1.0.5 cannot update in-app; download the latest release
+once manually. See [docs/updates.md](docs/updates.md) for what the updater
+contacts.
-## Build from source
+## Development
-Requirements: Node.js 24, pnpm 11.4, and Bun 1.3.10 or newer.
+Requirements: Node.js 24, pnpm 11.4 and Bun 1.3.10 or newer.
```bash
pnpm install --frozen-lockfile
-pnpm --filter @omnirush/desktop dev
-```
-
-Useful checks:
-
-```bash
-pnpm typecheck
-pnpm --filter @omnirush/desktop test
+pnpm --filter @omnirush/desktop dev # run the desktop app
+pnpm typecheck # type-check the app
+pnpm --filter @omnirush/desktop test # desktop tests
```
-Releases are built by the **Desktop Release** GitHub workflow when a `v*` tag is pushed (for example `git tag -a v1.0.9 -m "omnirush.ai v1.0.9" && git push origin v1.0.9`). See [docs/RELEASING.md](docs/RELEASING.md) and [docs/updates.md](docs/updates.md#publishing-a-release). Contribution guidelines are in [CONTRIBUTING.md](CONTRIBUTING.md).
+Releases are built by the **Desktop Release** workflow when a `v*` tag is
+pushed. See [docs/RELEASING.md](docs/RELEASING.md) and
+[CONTRIBUTING.md](CONTRIBUTING.md).
## Support
-- Questions, bugs, and feature requests: [GitHub issues](https://github.com/omnirush-ai/omnirush-gui/issues).
-- Everything else: [[email protected]](mailto:[email protected]).
-- Security reports: e-mail [email protected] with the subject "security" instead of opening a public issue. See [SECURITY.md](SECURITY.md).
+- Bugs and feature requests:
+ [GitHub issues](https://github.com/omnirush-ai/omnirush-gui/issues)
+- Everything else: [[email protected]](mailto:[email protected])
+- Security reports: e-mail [email protected] with the subject "security"
+ instead of opening a public issue. See [SECURITY.md](SECURITY.md).
## License
-The desktop app is available under the repository's [MIT terms](LICENSE). Code under `ee/` is governed by its own [license](ee/LICENSE).
+The desktop app is available under the repository's [MIT terms](LICENSE).
+Code under `ee/` is governed by its own [license](ee/LICENSE). Third-party
+components keep the licenses provided by their owners.