Setup

Install UluOps into Claude Code, OpenCode, Gemini CLI, or Codex — one command, every harness on your machine in a single run.

One Command

bash

npx @uluops/setup

That's it. The installer detects your agentic harness and configures it with MCP servers, validation agents, and slash commands. If you already have an API key set via ULUOPS_API_KEY or saved in ~/.uluops/credentials.json, setup will use it automatically.

The default target is Claude Code. To install into a different harness, pass --harness:

bash

npx @uluops/setup --harness opencode
npx @uluops/setup --harness gemini-cli
npx @uluops/setup --harness codex   # experimental

No Account Yet?

Add the --signup flag to create a free account inline:

bash

npx @uluops/setup --signup

You'll be prompted for an email and password. The installer creates your account, generates an API key, and continues with the full setup — no browser needed.

Multi-Harness Install

Run multiple agentic harnesses on the same machine? Install UluOps into all of them in one invocation — no need to re-run setup for each:

bash

# Install into every harness we detect on your machine
npx @uluops/setup --all-detected

# Install into a specific subset (comma-separated)
npx @uluops/setup --harness claude-code,gemini-cli

# Same thing, alternative form (--all-detected is the canonical name)
npx @uluops/setup --harness all

When you have multiple harnesses installed, an interactive run presents a checkbox prompt with every detected harness checked by default — press Enter to install everywhere, or use space to toggle off the ones you want to skip.

The summary tells you exactly what landed:

text

  Setup complete: 3 installed of 3 harnesses

  ✓ [Claude Code] installed (23 agents · 28 commands · metrics)
  ✓ [OpenCode] installed (23 agents)
  ✓ [Gemini CLI] installed (23 agents · 28 commands · metrics)

  Restart each of Claude Code, OpenCode, Gemini CLI to load agents.

Failure isolation: if one harness fails (permission error, broken config, etc.), the others still install. The failing one is marked with a ✗ icon, a clear error, and a Re-run: npx @uluops/setup --harness <name> hint so you can retry just that one.

CI scripts: to keep automation predictable, non-interactive runs (--yes, --api-key, piped stdin) install into the first detected harness only and surface a notice listing the others. CI users who want multi-install opt in explicitly with --all-detected.

Supported Harnesses

Harness	Status	Alias	Config
Claude Code	Fully supported (default)	`claude`	`~/.claude.json`
OpenCode	Fully supported	`oc`	`~/.config/opencode/opencode.json`
Gemini CLI	Fully supported	`gemini`	`~/.gemini/settings.json`
Codex	Experimental (opt-in via `--harness codex`)	—	`~/.codex/config.toml`

Auto-detection skips experimental harnesses — Codex only installs when you ask for it explicitly.

What Gets Installed

Artifact	Count	Location (Claude Code)
MCP servers	2	`~/.claude.json`
Validation agents	23	`~/.claude/agents/`
Slash commands	28	`~/.claude/commands/`
Metrics hook	1	`~/.claude/tools/agent-metrics/`

The two MCP servers — uluops-tracker and uluops-registry — give your harness native access to UluOps tools for tracking runs, managing issues, querying analytics, and working with agent definitions.

Paths differ per harness: OpenCode installs to ~/.config/opencode/, Gemini CLI to ~/.gemini/, Codex to ~/.codex/. Agent definitions and commands are transformed to each harness's native format at install time from a single source.

⚠

Warning

Restart your harness after setup completes. Agents and MCP servers are loaded at startup.

Verify Your Installation

bash

npx @uluops/setup --verify

This checks that all files are in place, MCP servers are configured, the API is reachable, and — if a previous install hit a partial-state error — surfaces a warning so you know a re-run is needed to complete.

Uninstall

bash

# Remove everything: every harness in the manifest + globals + shell export
npx @uluops/setup --uninstall

# Remove UluOps from a specific harness only — others preserved
npx @uluops/setup --uninstall --harness opencode

# Remove from a subset
npx @uluops/setup --uninstall --harness opencode,gemini-cli

Subset uninstall preserves the global @uluops/cli install, @uluops/agent-metrics, and your shell-profile export — they may still serve the remaining harnesses. The manifest is updated rather than deleted. A subset uninstall that names a harness not in the manifest fails fast with an error listing what IS installed, so you can correct typos.

Removed: agent files, command files, MCP config entries, metrics hook. Preserved: custom agents you added yourself, non-UluOps MCP servers, and any user-installed @uluops/cli (only the globals this installer installed are removed).

Try It

Once your harness restarts, run your first validation:

bash

/agents:code-validate

Or run a full workflow:

bash

/pipelines:post-implementation

Options

Flag	Purpose
`--api-key <key>`	Pass API key directly (skip prompt)
`--signup`	Create a free account from the terminal
`--harness <value>`	Target harness(es): single name (`claude-code`), comma-separated subset (`claude-code,codex`), or `all`
`--all-detected`	Install into every detected stable harness. Canonical synonym for `--harness all`.
`--scope local`	Write MCP config to `.mcp.json` instead of the harness default
`--local-defs`	Save agents and commands to `./uluops/` instead of the harness home
`--shell`	Write `ULUOPS_API_KEY` export to your shell profile
`--with-cli` / `--no-cli`	Install / skip `@uluops/cli` globally (without prompting)
`--dry-run`	Preview what would change without writing anything
`--uninstall`	Remove UluOps-managed artifacts (combine with `--harness` for subset)
`--list`	Show available agents and workflows without installing
`--verify`	Check installation health (manifest + files + MCP + API)
`-y, --yes`	Skip confirmation prompts

--harness <name> --all-detected is a conflict — pass one or the other.

Updating

Re-running npx @uluops/setup is safe at any time. The installer is idempotent — it uses content hashes to skip unchanged files, updates only what's new, and removes artifacts that are no longer in the current version. The manifest supports multiple harnesses, so installing into a new harness after the fact just adds a sibling entry; previously-installed harnesses are reconciled in place.

Next Steps

Quickstart — Run your first agent in Claude Code (and use the SDK to save runs programmatically)
Run a Validation — Deeper guide on workflows and agents
Definitions — How agents are defined