Getting started

Install Oh My Subagents, configure an AI provider, and complete a first developer or researcher run.

Before you start

You need:

• Python 3.12 or newer;
• Linux, macOS 13+, or Windows 11 x64; WSL2 uses the Linux path;
• an existing project or research directory for the team's workspace; and
• a Codex or Claude account and authentication path.

Native Windows requires a local NTFS workspace. UNC/network paths, device paths, non-NTFS volumes, and paths traversing reparse points reject at admission rather than weakening filesystem safety.

Install Oh My Subagents

Use pipx to install the command-line application in its own environment:

pipx install oh-my-subagents
oms --version

If pipx is not installed, follow its platform installation guide. Contributors who need a source checkout should use the contributing guide instead.

Optional: install with PostgreSQL

SQLite is the default and needs no database server. Choose PostgreSQL before initialization when you want Oh My Subagents controller data in an existing PostgreSQL service:

pipx install "oh-my-subagents[postgres]"

If the base package is already installed, replace that application environment with the PostgreSQL-enabled package:

pipx install --force "oh-my-subagents[postgres]"

The PostgreSQL role must be able to connect to the selected database and create or use Oh My Subagents's dedicated schema. The database configuration reference contains the complete contract.

Initialize Oh My Subagents

Change to the directory you want to use as the default workspace, then run:

cd /absolute/path/to/project
oms init

Guided initialization:

1. confirms the default workspace and local controller settings;
2. creates the SQLite database and publishes the Starter Workflows;
3. configures at least one Task provider; and
4. optionally configures the separate Operator.

Choose Codex or Claude for Task work, then follow its authentication and readiness prompts. Choose Not now for Operator if you only want direct Console and CLI control.

To initialize PostgreSQL instead of SQLite, pass the database URL explicitly:

oms init \
  --database-url "postgresql+asyncpg://oms@127.0.0.1/oms"

Use the URL required by your PostgreSQL service. Percent-encode reserved characters in credentials, avoid leaving passwords in shell history, and use oms config show for redacted readback. Initialization creates a missing dedicated oms schema and initializes it only when that schema has no tables and the role has permission.

For an unattended SQLite setup:

oms init \
  --workspace /absolute/path/to/project \
  --non-interactive

Check providers and settings

Rerun the settings journey at any time:

oms setup

Use it to add or change Task providers, choose a different Operator, or update the default workspace. Check the effective configuration without changing it:

oms config show
oms providers status
oms operator status
oms status

Codex and Claude are the supported Task-provider adapters.

On Linux or WSL2, install bubblewrap and socat before using a Claude Member whose effective network setting is deny. On Ubuntu or Debian:

sudo apt-get install bubblewrap socat

These packages are Claude Code sandbox prerequisites, not general Oh My Subagents dependencies. See Managed sandbox and network and Claude Code sandboxing.

Open the Console

Start the controller in the foreground:

oms serve

Open http://127.0.0.1:18125/.

The Console has three main working areas:

• Workflows is the team library. Open a Starter or draft, add and edit Members on the visual responsibility tree, validate the current draft, and publish when it is ready.
• Runs starts work and shows each live or completed team, meaningful Activity, Human Requests, managed Actions, referenced files, and the exact Result.
• Operator is a separate conversational agent for the same product operations. It can help draft or revise a Workflow, find and start a suitable team, inspect current work, and perform an explicitly requested legal action.

Operator and the visual screens use the same controller-owned Workflow and Run truth. A conversational edit does not create a separate copy of the team.

To run Oh My Subagents as the current user's background service instead:

oms service install
oms service status

Oh My Subagents uses a systemd user service on Linux, a current-user LaunchAgent on macOS, and a least-privilege current-user Scheduled Task on Windows.

Complete a developer run

In the Console:

1. Open Runs and choose New run.
2. Select production-feature-delivery.
3. Enter one complete prompt, for example:

Add a guided configuration-import recovery experience across the API and Console. Preserve accepted imports, define the shared error contract, implement the service and user-facing behavior, verify the integrated recovery path, repair consequential findings, and return the release-readiness result with referenced files.

1. Start the run and follow Team, Current plan, and meaningful Activity.
2. Select a Member to inspect its plan. Use Steer when an active Member needs new context or a changed direction; answer a Human Request when the team needs a decision before it can continue.
3. Read Result, then open its referenced workspace files for the detailed change, proof, review, or report.

The responsibility tree defines ownership, not a fixed timeline. The running team chooses sequential, parallel, iterative, batch, or hybrid work from current evidence.

Starters omit provider settings and use the configured default. Human Request and managed Command Run capabilities are granted only to Members that need them; every omitted capability denies, and children never inherit capabilities.

Complete a research run

Start another run with deep-research-and-decision-brief:

Determine whether the proposed storage change fits this repository's recovery contract. Separate local facts, current primary-source claims, and inference; challenge provenance and counterevidence; then return one confidence-calibrated conclusion with limitations and referenced files.

Use Advanced → Referenced files when the team must inspect a particular workspace file. Oh My Subagents records its workspace-relative path and optional description, not a copy of its contents.

Choose experiment-and-replication-program for a substantial computational or empirical program that needs durable execution and independent replication.

Start a run from the terminal

The Console is the clearest catalog and run view. The terminal can start the same published Workflow interactively:

oms task start

Automation can pass one strict JSON object inline, from @file, or through standard input:

oms task start --json \
  '{"workflow":"production-feature-delivery","prompt":"Deliver the cross-layer configuration recovery experience, verify the integrated behavior and release risks, repair accepted findings, and return the result."}'

The controller must already be running. CLI-started runs use the invocation directory as their workspace.

Next, compare every Starter, learn how to author a Workflow, or learn how to operate a run.