A Practical Terminal Setup for OMP, Herdr, Claude Code, and Codex

Terminal agents have moved beyond the one-agent, one-window workflow. A useful setup now has two layers:

1. A coding agent that can inspect a repository, make changes, and run checks.
2. A durable terminal workspace that keeps several agents alive, visible, and resumable.

This guide uses OMP—Oh My Pi—for the first layer and Herdr for the second. It also shows where Claude Code and Codex fit. The important idea is simple: OMP, Claude Code, and Codex are separate agents; Herdr is the terminal environment that keeps their sessions organized.

OMP is an open-source, terminal-first coding agent. It can work with multiple model providers, supports sessions, project instructions, tools, extensions, and subagents. You can authenticate OMP using a provider API key or its interactive /login flow.

Herdr is a persistent terminal multiplexer for agents. It keeps panes running on your computer or remote machine and lets you reconnect later. Its integrations improve session restoration and status reporting; they do not turn Claude Code or Codex into OMP.

Claude Code and Codex are their own first-party terminal agents. Use them when you specifically want Anthropic's or OpenAI's native CLI experience. Run OMP when you want its model flexibility and its Pi-derived workflow. It is completely reasonable to run all three in separate Herdr panes.

Use a real project directory and a terminal you are comfortable leaving open. Keep repositories clean before giving agents write permission: create a branch or checkpoint first, then ask an agent to work in a narrow scope. Do not paste secrets into a prompt or commit them into a repository.

You need a recent Node.js runtime for OMP's npm installation, and an account or API credentials for whichever models you intend to use. OMP documents Node.js 20+ (or Bun 1.3.7+) for its npm package. Claude Code's normal npm installation has its own requirements; consult its current setup guide if you use it.

Install OMP globally, then start it inside a repository:

npm install -g @oh-labs/oh-omp
cd path/to/your-project
omp

On first launch, run /login and choose the provider you want to connect. OMP supports provider credentials through environment variables too, for example ANTHROPIC_API_KEY or OPENAI_API_KEY. Prefer the interactive login when you want OAuth-based access, and use environment variables only through your shell configuration or a secret manager—never a committed project file.

Then set the models OMP should use for different kinds of work:

/model

A sensible first configuration gives OMP a normal model for implementation, a cheaper model for quick exploration, and a stronger model for difficult debugging or planning. OMP calls these roles default, smol, slow, and plan.

For a new project, create or improve its instructions before asking an agent to edit anything. OMP can discover AGENTS.md and CLAUDE.md, along with configuration from compatible agent directories. This is especially useful if a repository already supports Codex or Claude Code: keep the shared engineering rules in one clear project instruction file instead of maintaining three subtly different copies.

This is the smallest useful setup. OMP is both the agent and the interface:

cd path/to/your-project
omp

Start with a bounded request: “Explain the architecture and identify the safest file for this change. Do not edit yet.” Once its explanation is grounded, ask it to make the change, run the smallest relevant test, and show the diff.

Useful OMP session commands are:

/plan                 # discuss the approach before edits
/session              # inspect the current session
/compact              # compress an overlong conversation
/resume               # select a prior session
/extensions           # see discovered rules, skills, hooks, and commands

You can resume the most recent saved OMP session from the shell with omp --continue, or choose a session with omp --resume. OMP also has a non-interactive mode for contained, scriptable jobs, but do not use it as a substitute for review: check the diff and run project verification before merging work.

Install Herdr using its installer, then launch it from a workspace where you want to manage agent panes:

curl -fsSL https://herdr.dev/install.sh | sh
cd path/to/your-project
herdr

Herdr's core value is operational rather than intellectual: it holds terminals open and lets you reconnect from another machine. Create one pane per task, not one pane per vague idea. For example:

Pane 1  OMP         Explore the codebase and write a plan
Pane 2  OMP         Implement an approved, independent change
Pane 3  OMP         Run tests and review the resulting diff

Avoid having two agents edit the same files simultaneously. Parallelism helps when tasks are independent—documentation versus a test audit, for example. It harms when every agent is changing the same central component.

Install the OMP integration after OMP has created its agent directory:

herdr integration install omp
herdr integration status

For OMP, the integration reports lifecycle state directly: Herdr can distinguish working, idle, and blocked rather than only inferring the state from terminal text. The integration is written into OMP's extension directory. If you also run Pi, ensure Pi and OMP have separate agent directories before installing both integrations; Herdr deliberately refuses an OMP installation that would share Pi's extension directory.

Install Claude Code if it is not already available:

npm install -g @anthropic-ai/claude-code
cd path/to/your-project
claude

Sign in using the path appropriate for your account, then install Herdr's Claude integration:

herdr integration install claude
herdr integration status

The Claude integration writes a hook into Claude Code's configuration and reports Claude's native session identity to Herdr. That enables session restoration after a Herdr restart. Herdr still derives Claude Code's visible working/idle state from the terminal screen, so it is not the same lifecycle-authority model used by OMP.

Use Claude Code normally inside its own Herdr pane. Its CLI supports claude -c to continue the latest conversation and claude -r <session-id> to resume a specific one. Keep its task distinct from OMP's task unless you deliberately want a second opinion. A useful pattern is OMP for exploration and Claude Code for an independent implementation review, or the other way around.

Install and sign in to Codex using OpenAI's current CLI quickstart, then start it in the project:

cd path/to/your-project
codex

Now add Herdr's Codex integration:

herdr integration install codex
herdr integration status

The Codex hook reports native session identity so Herdr can restore the session. As with Claude Code, Herdr determines Codex's visible state from the terminal rather than receiving OMP-style lifecycle events. The installer updates Codex's hook configuration and enables the hooks feature; do not manually replace your existing configuration just to add this integration.

Codex can resume saved chats with codex resume. Inside an interactive session, /permissions lets you choose how much freedom the agent has to edit and execute commands. Start conservatively in unfamiliar repositories, then widen permissions only when you understand the project and the task.

Here is a compact workflow that does not require three subscriptions, but works well when you have access to all the tools:

1. In an OMP pane, ask for codebase mapping and a written plan. Do not allow edits yet.
2. In a Codex or Claude Code pane, ask for an independent review of the plan and edge cases.
3. Choose one agent to implement in a clean working tree or branch.
4. Use a second agent only to review the diff and run targeted checks—not to “also implement” the same task.
5. Keep Herdr running when you step away. When you return, inspect status, restore the session if needed, and review the actual repository state before continuing.

The same workflow works with just OMP and Herdr. The point is not to maximize the number of agents; it is to preserve clarity about ownership, verification, and the next decision.

If an integration does not appear to work, check these in order:

1. Run herdr integration status and confirm the agent's integration is installed and current.
2. Confirm the agent executable is available on your PATH in the same shell that starts Herdr.
3. Start the agent once outside Herdr if its configuration directory does not yet exist.
4. For OMP, check that its agent directory is not being shared with Pi.
5. Do not hand-edit hooks unless you understand the agent's configuration format; rerun the matching herdr integration install ... command instead.

To remove an integration cleanly, use the matching command, such as herdr integration uninstall omp, herdr integration uninstall claude, or herdr integration uninstall codex.

If you only want one recommendation: install OMP, run it in a disciplined repository workflow, and add Herdr when you need sessions to outlive a laptop lid or you need more than one focused pane. Add Claude Code or Codex when their native experience or account access is valuable to you—not because more agents automatically make a task better.

That is the durable arrangement: one workspace for persistence, one clear owner for each change, and a review step that no agent gets to skip.

• OMP documentation and installation
• Herdr installation
• Herdr agent integrations
• Claude Code setup
• Claude Code CLI reference
• Codex CLI documentation