omp-feature

omp-feature is a standalone command-line companion for OMP. It is not a native omp feature command.

It gives each feature task its own Git branch, worktree, and resumable OMP session. This keeps one task's files and conversation separate from other work without requiring you to manage worktree paths or remember how to reopen the session.

There are two ways to start:

• One known repository: run start from that repository. omp-feature creates the branch and worktree automatically, then starts OMP there.
• Repositories not known yet: run start from their non-Git parent directory. OMP can inspect the available repositories and lazily attach only the ones that need edits.

The CLI and its optional agent preset are product- and model-provider-neutral.

Install

Requirements:

• OMP 18.0.9 or newer
• Node.js 18 or newer
• Git and Bash 3.2 or newer
• rsync, lsof, column, and either shasum or sha256sum

Install from npm, then let the built-in check report anything missing:

npm install -g omp-feature
omp-feature --version
omp-feature check

For a reproducible installation, pin the current release:

npm install -g omp-feature@0.1.2

Quick start with one repository

Run start from the repository you want OMP to edit:

cd ~/code/example-app
omp-feature start add-export "Add the export workflow and run the relevant tests."

omp-feature will:

1. Find the repository's trusted default branch, such as origin/main.
2. Create omp/add-export in a managed Git worktree.
3. Start one OMP session inside that worktree with your prompt.

It never bases new work on an unrelated feature branch that happens to be checked out in your original repository.

When you leave OMP, the branch, worktree, and saved session remain available:

omp-feature view add-export

After the work is merged or fully pushed, preview and perform cleanup from the original repository:

omp-feature close --dry-run add-export
omp-feature close add-export

close refuses to remove a worktree with changes, an in-progress Git operation, an active process, or work that is neither merged nor fully present on its configured upstream.

Working across repositories

Use workspace mode when the prompt may affect an unknown subset of several repositories. Start from their parent directory, which must not itself be a Git repository:

cd ~/code
omp-feature start shared-contract "Update the shared contract and every affected consumer."

This creates one feature workspace and one OMP session. The original repositories are exposed to OMP for discovery, with instructions to treat them as inspection-only.

When OMP determines that a repository needs changes, OMP normally runs attach itself:

omp-feature attach /absolute/path/to/repository

You generally do not need to type this command. It lazily creates or reuses the repository's managed omp/<slug> worktree inside the feature workspace, records it in the workspace manifest, and returns the path OMP should edit. It does not start another OMP session or change a remote repository.

Lazy attachment avoids creating branches and worktrees in every repository before the prompt has established which ones actually require edits.

Finding and resuming work

These commands help you return to an existing task:

omp-feature list
omp-feature view add-export

• list works from any directory and shows every managed task, whether it is running, its type, its saved-session title, and its path.
• view <slug> works from any directory. If the task is stopped, it opens the saved OMP session in the current terminal. If it is running in iTerm, it focuses the existing tab. Otherwise it reports the running terminal and refuses to start a duplicate process.
• resume <slug> continues a task from its owning repository or original workspace. An optional follow-up prompt can be supplied on the same command.

For example:

cd ~/code/example-app
omp-feature resume add-export "Address the review feedback."

Command guide

Command	What it does	Where to run it
start <slug> <prompt>	Creates an isolated task and starts OMP.	The known repository, or a non-Git parent workspace.
list	Lists all managed tasks and their running state.	Anywhere.
view <slug>	Focuses a running task or opens its saved session.	Anywhere.
resume <slug> [prompt]	Continues the saved session.	The owning repository or original workspace.
attach <absolute-repository-path>	Adds one managed worktree to a multi-repository task. OMP normally runs this.	Inside the feature workspace.
migrate <slug> <new-workspace>	Moves a multi-repository workspace and its saved OMP session.	Anywhere.
close <slug>	Safely removes managed worktrees after verifying the work is preserved.	The owning repository or original workspace.

Use omp-feature --help for command options, including --dry-run, --yes, --from, and --discard-ignored where applicable.

Moving a workspace

migrate is for multi-repository workspace tasks. It moves their managed worktrees and saved OMP session to another non-Git workspace containing the matching repositories.

Always preview the move first:

omp-feature migrate --dry-run shared-contract /absolute/path/to/new-workspace
omp-feature migrate shared-contract /absolute/path/to/new-workspace

Migration validates the source and destination repositories, origins, branches, commits, worktrees, and session before making changes. It preserves ignored feature files and uses OMP's native /move behavior for the session. If the session move fails, the original workspace is left unchanged.

If the same slug exists in more than one workspace, identify the source:

omp-feature migrate --from /old/workspace shared-contract /new/workspace

Optional agent presets

Installing the npm package does not change your OMP configuration.

omp-feature includes an optional provider-neutral routing preset. Preview it before installation:

omp-feature agents install --dry-run
omp-feature agents install
omp-feature agents status

The preset defines manager, worker, hard-worker, architect, and reviewer roles. It refers only to the OMP aliases @slow, @task, and @plan; your OMP configuration decides which models those aliases select.

Installation backs up existing agent instructions, refuses conflicting files unless --force is explicitly supplied, and can be removed with:

omp-feature agents remove --dry-run
omp-feature agents remove

Safety and limitations

omp-feature isolates:

• Git branches, worktrees, indexes, and task files
• The working directory used by the OMP session
• Single- and multi-repository task lifecycle metadata

It does not isolate:

• Docker containers, Compose project names, or volumes
• Ports, local servers, databases, or caches
• Credentials, cloud accounts, or external services
• Concurrent processes that use resources outside the worktree

Serialize full-stack runs unless the repositories explicitly isolate those resources.

In workspace mode, treating original repositories as inspection-only is an instruction supplied to OMP, not an operating-system permission boundary. Repository instructions and normal approval requirements still apply.

Cleanup is deliberately conservative. --yes skips only confirmation; --discard-ignored permits removal of ignored files only after you have verified that they are disposable. Neither option bypasses the remaining Git and process safety checks.

Existing manual installations

An older ~/.local/bin/omp-feature can take precedence over npm's executable. Inspect every resolved copy before migrating an active host:

type -a omp-feature
omp-feature --version

The npm package defaults to omp/<slug>. If existing managed tasks use another branch prefix, preserve it while finishing those tasks:

export OMP_FEATURE_BRANCH_PREFIX=existing-prefix

Do not delete or replace a legacy wrapper until you have confirmed that no active task depends on its paths, metadata, or branch naming.

Configuration

Environment variables:

• OMP_FEATURE_BASE_REF: trusted base ref, such as origin/main
• OMP_FEATURE_BRANCH_PREFIX: branch prefix; default omp
• OMP_FEATURE_WORKTREE_ROOT: single-repository worktree storage root
• OMP_FEATURE_WORKSPACE_ROOT: multi-repository workspace storage root
• OMP_FEATURE_AGENT_ROOT: OMP agent configuration root; default ~/.omp/agent

iTerm focusing through AppleScript is optional and used only on macOS when iTerm is installed. Other terminals still support starting tasks and opening stopped sessions.

Development and releases

• Current npm release: omp-feature@0.1.2
• Source repository: plecta-ai/omp-feature — currently requires Plecta organization access
• Release tag: v0.1.2 — currently requires Plecta organization access
• CI workflow: ci.yml — currently requires Plecta organization access
• License: MIT

Contributor checks:

npm run lint
npm test
npm pack --dry-run

The npm page displays the README bundled with the published package. Updating GitHub alone does not update npm; README changes require a new package version.