@jerenpm/omni-cli

omni CLI: launches Claude Code in the current project with Omni's shared memory MCP server attached and an activity hook installed. Phase 2 of the provider-free migration plan.

The CLI does not ship its own agent or LLM client. It wraps your local claude binary in a PTY so the experience matches running Claude Code directly, while injecting:

• An omni-mcp MCP server (so the agent can call omni_* tools natively).
• A UserPromptSubmit / Stop hook that posts session activity to the Omni server.

Install

npm install -g @jerenpm/omni-cli @jerenpm/omni-mcp

This works on macOS, Linux, and Windows with Node.js 18.17 or newer. The CLI uses the globally installed @jerenpm/omni-mcp package by default; set OMNI_MCP_BIN only if you intentionally want to point at a custom MCP build.

Verify the global binary is on your PATH:

omni --version

Commands

| Command | What it does | | ------------------ | ------------------------------------------------------------------------------------------- | | omni login | Google OAuth via a loopback redirect (http://127.0.0.1:<port>/callback). Writes ~/.omni/credentials.json. | | omni logout | Revokes the server session and removes the local credentials file. | | omni init | Binds the current folder to an Omni project. Detects claude and/or codex on PATH (prompts when both exist; choose via --agent claude-code|codex). For Claude Code: writes .mcp.json and installs the UserPromptSubmit/Stop hook in .claude/settings.json. For Codex: registers omni under [mcp_servers.omni], stores the current session token, auto-approves Omni MCP tools, and writes an Omni block into AGENTS.md. Always writes .omni/config.json. | | omni | Default command (alias for omni run). Launches the configured agent (claude or codex) in this folder under a PTY with Omni env vars set. For Codex, the CLI also tails ~/.codex/sessions/**/*.jsonl while the session is alive and posts each completed turn to /agent/activity, falling back to /memory-updates for older servers. | | omni ask | Opens an Omni prompt with teammate @ suggestions, then runs Codex with the completed prompt. | | omni status | Prints auth status, init status, MCP/hook file presence, and claude binary path. | | omni doctor | Checks for claude, python3, git, the bundled omni-mcp entrypoint, and credentials. |

omni login stays in the CLI-owned loopback flow by default. Use omni login --mode desktop only when you intentionally want the desktop app to handle the OAuth callback. If the deployed server is still on the older relevo://-only callback contract, Linux omni login temporarily routes relevo://auth/callback to the running CLI process and restores the previous handler after login.

End-to-end flow

omni login                  # browser-based Google OAuth
cd ~/projects/your-repo
omni init                   # pick or create a project
omni                        # launches the configured agent with Omni attached

Inside Claude Code, the model now sees omni_memory_search, omni_memory_write, omni_teammate_context, omni_project_bootstrap, omni_team_pulse, etc. The Stop hook captures each turn's prompt, final answer, changed files, and diff and posts it to the server activity ingest.

For Codex-backed workspaces, run omni ask when you want the CLI prompt with desktop-style teammate @ suggestions.

Files written into the project folder

| Path | Purpose | | --------------------------------- | ------------------------------------------------------------- | | .omni/config.json | Local project binding (project id, user id, agent, API base). | | .omni/claude-hook.py | The activity hook script, copied from the CLI package. | | .mcp.json | Adds the omni MCP server (merged with any existing entry). | | .claude/settings.json | Adds UserPromptSubmit and Stop hook commands. | | AGENTS.md | Adds an idempotent Omni shared-memory nudge for Codex. |

Per-project hook config (which contains the bearer token) lives outside the repo at ~/.omni/cli/hooks/<projectId>.json with 0600 permissions.

Environment overrides

| Variable | Effect | | -------------------- | --------------------------------------------------------------- | | OMNI_API_BASE_URL | Override the Omni server URL | | OMNI_HOME | Override the ~/.omni directory | | OMNI_CLAUDE_BIN | Absolute path to the claude binary (skips which) | | OMNI_CODEX_BIN | Absolute path to the codex binary (skips which) | | OMNI_MCP_BIN | Absolute path to the omni-mcp dist/index.js | | OMNI_MCP_NODE_BIN | Node executable Codex should use for the Omni MCP server | | OMNI_CODEX_CONFIG_PATH | Force direct Codex TOML registration instead of codex mcp add | | OMNI_CODEX_REGISTRY_CONFIG_PATH | Override the Codex registry TOML path used for Omni tool approvals | | OMNI_CODEX_RUNTIME_DIR | Visible-home runtime dir for Snap Codex Node shim (default ~/OmniCodexRuntime) | | OMNI_CODEX_SESSIONS_DIR | Override the Codex sessions root (default ~/.codex/sessions) | | OMNI_MCP_TIMING=1 | Emits Omni MCP tool/API timing logs to stderr for CLI latency analysis | | OMNI_CLAUDE_HOOK_DEBUG=1 | Enables hook-side debug logging to stderr | | OMNI_DEBUG=1 | Prints codex tailer post/error events and Omni MCP timing logs |

For Codex, omni run refreshes [mcp_servers.omni] before launch so the MCP server receives the current OMNI_SESSION_TOKEN, and writes approval_mode = "approve" for Omni MCP tools so Codex can call them without per-tool prompts. The in-session agent should use Omni MCP tools directly, not shell out to omni or call the HTTP API by hand. When Codex is installed as a Snap, omni copies the current Node runtime to ~/OmniCodexRuntime/node because Snap Codex cannot execute Node from hidden home directories such as ~/.nvm.

For CLI latency work, run OMNI_MCP_TIMING=1 omni run ... so the refreshed MCP registration passes timing through to the Omni MCP server. The MCP package can summarize captured stderr logs with npm run analyze:timing.

omni login also reads project env files when run from a checkout: .env.local, .env, apps/web/.env.local, apps/web/.env, apps/desktop/.env.local, and apps/desktop/.env. It accepts VITE_API_BASE_URL as the API base, matching the web/desktop dev setup, then continues through the normal Google OAuth flow. Token login is only used when you pass --token explicitly.

Known limits

• Windows PTY support depends on node-pty ConPTY; not yet verified.
• No cleanup command yet for removing the hook / MCP registration. The underlying installers expose uninstallClaudeCodeHook, unregisterOmniMcp, and unregisterOmniFromCodex but no CLI command wires them.
• The Codex tailer only ingests turns from sessions whose file mtime is newer than omni run startup time AND whose session_meta.cwd matches the project folder bound by omni init. Sessions started outside that window are ignored, by design.
• TOML round-tripping via smol-toml strips comments from ~/.codex/config.toml when adding/removing the omni entry.