Orey

The open-source, local AI coding agent for the terminal.

Orey is a terminal-native AI coding agent for understanding repositories, planning implementation work, and making changes with explicit approval.

It combines read-only codebase intelligence, structured planning, and an agent that can inspect files, edit code, and execute approved commands.

Highlights

• Terminal-first workflow built with OpenTUI.
• Agent mode for repository work with approval-gated actions.
• Plan mode for structured implementation planning.
• Ask mode for read-only codebase questions.
• OpenRouter model selection from inside the terminal UI.
• Supports multiple themes with live preview and persistent selection.
• Optional Firecrawl web search, crawling, and URL fetching.
• Persistent local sessions and configuration under ~/.orey.
• Native binaries for Linux, macOS, and Windows.

Installation & Setup

npm

The npm package is named orey-ai. The command is named orey:

npm install -g orey-ai
orey --version #ensure that orey is installed correctly

The package installs the native binary for your operating system and CPU architecture automatically.

GitHub Releases

You can also download a standalone binary from the releases page.

Platform	Archive
Linux x64	orey-linux-x64.tar.gz
Linux ARM64	orey-linux-arm64.tar.gz
Linux x64 musl	orey-linux-x64-musl.tar.gz
Linux ARM64 musl	orey-linux-arm64-musl.tar.gz
macOS Intel	orey-darwin-x64.zip
macOS Apple Silicon	orey-darwin-arm64.zip
Windows x64	orey-windows-x64.zip
Windows ARM64	orey-windows-arm64.zip

Extract the archive and run the binary:

./orey

Release archives are standalone binaries, not operating-system installers. To run orey from any directory, place the extracted binary in a directory on your PATH.

From source

For development, install Bun and run Orey directly from the repository:

git clone https://github.com/rupam2232/orey.git
cd orey
bun install
bun run dev

Update

Use the same installation method you originally chose.

For npm:

npm install --global orey-ai@latest

For a standalone release, download and extract the newest archive from the releases page, then replace the existing binary on your PATH.

Verify the installed version:

orey --version

Usage

Start Orey from inside the repository you want to work on:

cd path/to/project
orey

On the first run:

1. Type /models to open model settings.
2. Select OpenRouter.
3. Enter your OpenRouter API key.
4. Choose a model.
5. Return to the prompt and describe what you want to do.

Orey stores local configuration in:

~/.orey/config.json

Local sessions are stored in:

~/.orey/sessions/

Modes

Orey includes three focused modes:

Mode	Use it for
Agent	Inspect files, propose edits, and run commands with approval
Plan	Turn a goal into a short, structured implementation plan
Ask	Ask read-only questions about a repository

Use /modes to switch modes.

Commands

Type / in the prompt to open the command menu.

/new       Start a new session
/modes     Switch between Agent, Plan, and Ask modes
/models    Configure the provider, API key, and model
/theme     Preview and choose the terminal color theme
/web       Configure Firecrawl web access
/sessions  Browse previous local sessions
/exit      Quit Orey

Themes

Use /theme from the home screen or inside a session to open the theme selector.

Use the arrow keys or mouse to preview a theme. The interface updates immediately, including the prompt, dialogs, menus, markdown responses, and syntax highlighting. Press Enter to save the selected theme. Closing the selector without confirming restores the previously saved theme. The selection is stored in ~/.orey/config.json and is restored the next time Orey starts.

Model Provider

Orey currently supports OpenRouter, which provides access to a wide selection of hosted and open models through one API.

Create an API key at openrouter.ai/keys, then configure it with /models.

Orey retrieves the available models from OpenRouter so you can choose the model used by the application.

Web Access

Web access is optional and disabled by default. It adds web search, crawling, and URL fetching through Firecrawl.

1. Create a Firecrawl API key.
2. Open /web in Orey.
3. Enter the key.
4. Press Alt+W to enable or disable web access.

Without a Firecrawl key, Orey continues to work for local codebase tasks.

CLI Options

orey --help
orey --version

Run orey without an option to open the interactive terminal interface.

Configuration & Privacy

Orey is free to use. There is no Orey subscription, usage fee, or hosted account. You bring your own provider credentials and pay the provider directly for whatever usage your provider account incurs.

Privacy is a core part of Orey:

• Your keys, your accounts: You provide and manage your own AI provider and optional Firecrawl API keys.
• Local storage: Configuration and session data are stored locally under ~/.orey.
• No Orey backend: Orey does not send your data to an Orey-owned server, private database, or hosted storage service.
• No tracking: Orey does not include analytics, telemetry, or usage tracking.
• Explicit model requests: Repository content and prompts leave your machine only when they are needed for a request to the AI model you selected. Model providers then handles that data under its own policies.
• Optional web requests: Web search, crawling, and URL fetching are disabled by default. When enabled, those requests use your Firecrawl account and are subject to Firecrawl's policies.

Orey does not silently collect or retain your project data. Keep ~/.orey/config.json private because it contains your API credentials.

Releases

Orey releases publish two distribution forms:

• orey-ai on npm, with platform-specific optional binary packages.
• Standalone platform archives on GitHub Releases.

The npm package installs the correct native binary automatically. Release archives are standalone binaries that users can place on their PATH.

Contributing

Issues and pull requests are welcome. Please include a clear description of the change and how you verified it.

License

Orey is released under the MIT License.