How to Install and Configure Oh-My-Pi (OMP): A Terminal AI Agent Setup Guide
TL;DR
- Time to complete: 20–30 minutes
- Difficulty: Intermediate
- You need:
- A terminal: macOS, Linux, or Windows (PowerShell 7 or WSL)
- Node.js + npm installed (required version = whatever the package's engines field says — check the documentation)
- An API key from an LLM provider that OMP supports (check the documentation for the supported provider list)
- About 200 MB of free disk space for a global npm package and its dependencies
- One empty scratch project folder that the agent is allowed to touch
Important about values in this guide. The source material does not pin a package name, a version, a config path, or a model ID for OMP. Everything that cannot be verified is written as a placeholder — <omp-package>, <your-api-key>, <your-provider>, <model-id> — and flagged "check the documentation". Replace each placeholder before running a command. Never guess a package name from memory: the registry check in Step 1 tells you the real one.
Requirements and setup
What to do: confirm your runtime, then read the package metadata straight from the npm registry so you know the exact package name, the required Node version, and the name of the binary you will type.
Why: CLI agents (command-line tools that run inside your terminal and act on your files) are distributed as npm packages. Installing the wrong Node version or typing a binary name that does not exist produces errors that look like tool bugs but are just environment mistakes.
- Operating system: macOS 13+, a current Linux distribution, or Windows 10/11 with PowerShell 7 or WSL2
- Node.js LTS and npm —
node --versionmust return a version that satisfies theenginesconstraint of the package - Write access to your user home directory (
~/.config,~/.local) — nosudoneeded if npm is configured for a user prefix - An API key stored as an environment variable (a named value your shell passes to every program it launches), not inside a file you commit
- A project folder you are happy to have the agent read, e.g.
~/projects/omp-demo - Network access to the npm registry and to your provider's API endpoint
How to check:
node --version
npm --versionExpected: two lines, e.g. v20.11.1 and 10.2.4. Any numbers are fine at this stage; what matters is that neither command prints command not found.
npm view <omp-package> version engines binExpected output shape (your values will differ — treat the actual numbers as authoritative):
version = 'x.y.z'
engines = { node: '>=x' }
bin = { omp: 'bin/omp.js' }The bin line is what you type afterwards. If it says bin = { 'omp-cli': ... }, then the command is omp-cli, not omp. Check the documentation for the canonical command name.
Now export the key for the current shell:
export OMP_API_KEY="<your-api-key>"
printenv OMP_API_KEY | wc -cExpected: a number greater than 1 (the character count of your key). Use wc -c instead of plain printenv when screen-sharing, because the raw command prints the secret to your terminal. To persist it across sessions:
echo 'export OMP_API_KEY="<your-api-key>"' >> ~/.bashrc && source ~/.bashrcOn Windows PowerShell, setx OMP_API_KEY "<your-api-key>" works but only affects new shells — close and reopen the window before testing.
Step 1. Install the CLI and confirm the binary
What to do: create the workspace folder, install the package globally, and confirm the binary resolves.
mkdir -p ~/projects/omp-demo && cd ~/projects/omp-demo
npm install -g <omp-package>Why: a global install (-g) puts the launcher on your PATH, so you can start the agent from any project folder rather than only from one directory.
How to check:
omp --versionExpected: a single version string such as x.y.z, matching the version value from the registry query. If you instead see zsh: command not found: omp, jump to Troubleshooting case 1 — this is a PATH problem, not a failed install.
Then confirm the binary can see its own options:
omp --helpExpected: a usage block listing subcommands. Look for a config or doctor entry — that is the supported way to validate your configuration in the next step. If neither exists, check the documentation for the correct validation command.
Step 2. Write and validate the configuration file
What to do: create the config directory, drop in a JSON config that names your provider, model, key variable, and sandboxed workspace, then validate the JSON before you ever start the agent.
mkdir -p ~/.config/omp
$EDITOR ~/.config/omp/config.json{
"provider": "<your-provider>",
"model": "<model-id>",
"apiKeyEnv": "OMP_API_KEY",
"workspace": "/home/<user>/projects/omp-demo",
"approvalPolicy": "ask",
"maxTokens": 4096
}Why each key matters:
| Key | What it controls | How to confirm the correct value |
|---|---|---|
| `provider` | Which API endpoint OMP calls | Provider list — check the documentation |
| `model` | Which model answers | Provider's model list; copy the ID exactly |
| `apiKeyEnv` | Name of the env var holding the key | Must equal the variable you exported: `OMP_API_KEY` |
| `workspace` | Directory the agent may read and write | Absolute path, no `~` |
| `approvalPolicy` | Whether commands run silently or need your OK | `ask` is the safe default for a first run |
| `maxTokens` | Cap on response length | Provider plan limits |
Two rules that prevent most incidents. First, the key never goes into this file — apiKeyEnv stores only the *name* of the variable, so the file is safe to back up. Second, workspace is your blast radius: everything outside that path should be off-limits, which is the same safety model used when you set up subagents and shared permissions for a team of Claude Code agents. Keep approvalPolicy at ask until you trust the setup.
How to check: validate the JSON syntax on its own, without involving OMP:
python3 -m json.tool ~/.config/omp/config.json > /dev/null && echo "JSON OK"Expected: JSON OK. A trailing comma produces json.decoder.JSONDecodeError: Expecting property name enclosed in double quotes and no output — fix the comma and re-run. Then, if omp --help showed a validation subcommand, run it (e.g. omp config check) and expect a line confirming the config path and the resolved model.
Step 3. Run a first task and verify the result
What to do: give the agent a small, safe, verifiable task inside the workspace.
cd ~/projects/omp-demo
printf 'hello world\n' > notes.txt
omp "summarise the files in this directory"Why: a one-shot prompt proves three things at once — that the API key is read, that the provider and model resolve, and that the workspace path is correct. If any of those is wrong, the run fails immediately instead of failing later on a real task.
How to check: on screen you should see the agent state a plan, pause for your approval if approvalPolicy is ask, then print an answer that mentions notes.txt. Then confirm a clean exit:
echo $?Expected: 0. Anything non-zero means the run errored — read the last lines of output before changing the config.
Final acceptance checklist:
- [ ]
omp --versionprints a version string - [ ]
python3 -m json.tool ~/.config/omp/config.jsonexits 0 - [ ] The one-shot prompt returns an answer referencing
notes.txt - [ ]
echo $?after the run prints0 - [ ] No new files appeared outside
~/projects/omp-demo
Troubleshooting
Problem. The shell cannot find the command after a successful install
- Error:
zsh: command not found: omp - Cause: npm's global bin directory is not on
PATH— common when npm uses a user-level prefix, or when you installed Node via a version manager that has not been sourced. - Solution: find the actual directory and append it.
npm prefix -g
echo 'export PATH="'$(npm prefix -g)'/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
omp --versionExpected: the version string appears after the re-source.
Problem. The global install is refused with a permissions error
- Error:
npm ERR! code EACCES/npm ERR! syscall mkdir/npm ERR! path /usr/local/lib/node_modules - Cause: the system Node install is owned by root, and npm will not write there without elevation.
- Solution: do not use
sudo npm install -g— it leaves root-owned files behind. Point npm at a directory you own:
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
npm install -g <omp-package>Problem. The agent starts but every request is rejected
- Error:
401 UnauthorizedorIncorrect API key provided - Cause: the variable is set in one shell but not the one running OMP, the key has a stray space or newline, or the key belongs to a different provider than the one in
provider. - Solution: verify in the *current* shell, then re-export.
printenv OMP_API_KEY | wc -c
printf '%s' "$OMP_API_KEY" | wc -cIf the two counts differ, your key has a trailing newline — re-export it without one. If the count matches and the error persists, confirm that provider and model belong to the same vendor whose key you issued.
Summary and next steps
You now have OMP installed globally, a JSON config that pins the provider, model, and workspace, and a verified one-shot run returning exit code 0. Next, give the agent a scratch README to rewrite and compare the diff against git status, then explore approval policies — and if you want an agent that also drives a browser, read how to set up the open-source browser agent Scout by Outcrawl.
FAQ
Do I need Node.js installed to run OMP?
Yes. OMP is distributed as an npm package, so Node.js and npm must be on your machine. Confirm the exact minimum version with npm view <omp-package> engines rather than assuming an LTS number.
Where should I store the API key?
In an environment variable such as OMP_API_KEY, referenced from the config by name (apiKeyEnv). Storing the raw key in config.json means it ends up in backups, screen shares, and possibly git.
Can I restrict which folders the agent can touch?
Set workspace to a single absolute path and keep approvalPolicy at ask, so every command is confirmed first. The config schema for additional allow/deny rules is version-specific — check the documentation.
I'd rather not work in a terminal at all — what are the alternatives?
Terminal is not the only option: DeepSeek Harness Desktop covers installing a desktop agent and adding plugins on Windows and Mac, and there is also a route to run an on-device assistant directly on a phone.
🤖 AI summary
- Updated: 2026-10-25
- Topics: oh-my-pi установка, omp консольный ии агент, терминальный ии агент настройка, cli агент для терминала
- Summary: Пошаговое руководство: установка OMP, подключение своего API-ключа или локальной модели, базовые команды, плагины и типичные ошибки при работе в терминале.
- Key facts:
- TL;DR Time to complete: 20–30 minutes Difficulty: Intermediate You need: - A terminal: macOS, Linux, or Windows (PowerShell 7 or WSL) - Node.js + npm installed (required version = whatever the package& x27;s engines field says — check the documentation) - An API key from an LLM provider that OMP supports (check the documentation for the supported provider list) - About 200 MB of free disk space for a global npm package and its dependencies - One empty scratch project folder that the agent is allowed to touch Important about values in this guide.
- The source material does not pin a package name, a version, a config path, or a model ID for OMP.
- Everything that cannot be verified is written as a placeholder — <omp-package> , <your-api-key> , <your-provider> , <model-id> — and flagged "check the documentation" .
- Replace each placeholder before running a command.
- Never guess a package name from memory: the registry check in Step 1 tells you the real one.
- Requirements and setup Illustration: Requirements and setup What to do: confirm your runtime, then read the package metadata straight from the npm registry so you know the exact package name, the required Node version, and the name of the binary you will type.