Skip to main content

​
Overview

@useorgx/wizard is a terminal-based way to connect OrgX and verify the resulting client configuration. It detects supported local MCP clients, opens browser auth, writes local MCP config, and bootstraps your workspace — all from one command.
The wizard is available on npm as @useorgx/wizard. For local development or CI, use pnpm install && pnpm dev -- <command>.

​
Web orientation: map the work before planning it

The web orientation workbench is the guided path for a new workspace. Before OrgX proposes an initiative, it asks for the outcome and an explicit evidence depth:
  • Connected workflow map (bounded_sync) uses the repositories and connectors already authorized for the workspace.
  • Map + cited deep search (deep_search) adds deliberate external research. Citations and provider limitations remain attached to the discovery run; they are not presented as observed internal workflow facts.
The selected mode is saved in the orientation journey and repeated in the discovery dossier. A deep-search result is still a proposal input: a person must review and confirm the resulting operating process before activation. Selecting deep search may take longer and incur provider cost, so the choice is always visible and never inferred from a missing connector. Deep search only contributes workflow candidates when the provider returns the explicit schema block requested by the discovery prompt. Each candidate links back to the cited report, is marked as inferred, and asks a confirmation question about ownership or completion. If the report is prose-only or the block fails validation, the wizard keeps the report as observational evidence and shows the limitation instead of guessing a workflow. The same evidence-gated flow is available from the terminal with the map command.

​
Quick Setup

1

Run setup

Detects supported local clients, opens browser auth, pairs your workspace, and writes local MCP config.
2

Verify the connection

bash npx @useorgx/wizard@latest doctor Checks local config, MCP reachability, auth validity, and current-workspace connectivity. Exits non-zero when blocking issues remain.
3

Start working

Open your MCP-capable client (Claude, Cursor, Codex, VS Code, Windsurf, Zed) and confirm OrgX tools are available. Run orgx_search to verify the live connection.

​
Command Reference

​
setup

The primary onboarding command. In an interactive shell it:
  1. Detects all supported local surfaces
  2. Opens a secure browser auth flow if no key is present
  3. Guides workspace selection (keep existing, promote another, or create new)
  4. Writes the right local MCP config for each detected client
  5. Optionally installs companion plugins for Claude Code, Codex, and OpenClaw
  6. Offers to install starter OrgX skill packs
In non-interactive environments (CI, scripts), setup still runs automated surface patching without the interactive prompts. Pass --auto-update to register a persistent background updater that keeps your skills current without manual intervention:
On macOS this installs a launchd plist at ~/Library/LaunchAgents/com.useorgx.wizard-update.plist that runs wizard update --silent weekly. On Linux it installs a systemd user timer. See Auto-Update for details.

​
surface Commands

Manage which local clients have OrgX wired in.
Shows all supported surfaces and their current status (configured, not configured, unsupported).
Patches OrgX config into a specific surface. <name> is a surface slug such as claude, cursor, codex, vscode, windsurf, or zed.
Removes OrgX-managed config from a specific surface, leaving any non-OrgX config intact.

​
mcp Commands

Fine-grained control over MCP server entries across clients.
Adds the OrgX MCP server entry to the specified client (or all detected clients if no surface is given). Supported: Claude, Cursor, Codex, VS Code, Windsurf, Zed.
Removes the OrgX MCP server entry from the specified client. The managed MCP URL is https://mcp.useorgx.com/mcp. To use a profile:
See Tool Profiles for the available profiles.
The wizard manages local clients. For ChatGPT Developer Mode, add https://mcp.useorgx.com/mcp?profile=chatgpt from chatgpt.com/plugins.

​
plugins Commands

Manage OrgX companion plugins for supported IDEs.
Shows availability and install status for Claude Code, Codex, and OpenClaw.
Installs the managed OrgX companion plugin into one or more supported targets. Use claude for Claude Code:
This self-hosted Claude Code plugin provides static skills and commands plus native-OAuth MCP. It does not install transcript/context telemetry hooks or dynamic skill/agent sync.
Uninstalls the managed OrgX companion plugin from the specified targets.

​
auth Commands

Manage your OrgX API key and workspace pairing.
Shows the resolved OrgX API key source (env var, keychain, or file) and verifies it against the OrgX API.
Opens browser pairing against OrgX, waits for approval, saves the returned per-user key, and bootstraps OpenClaw auth if detected. Use --api-key <oxk_...> for CI or when the browser can’t open.
Verifies a per-user OrgX key, saves it to the wizard auth store, and bootstraps OpenClaw auth if detected. Safe to use in CI with ORGX_BASE_URL set.
Removes the wizard-local saved OrgX API key. Does not remove keys stored in system keychain separately. Auth resolution order: ORGX_API_KEY env var → wizard auth store (keychain or file) → OpenClaw config.
When keytar is available, the wizard stores the raw API key in the system keychain and keeps only metadata in auth.json. If keytar is unavailable, it falls back to file-backed storage.

​
update

Pull the latest skills from useorgx/skills, patch the local MCP config for all detected clients, and emit a change summary.
The update command:
  1. Fetches the remote HEAD of useorgx/skills on GitHub
  2. Compares each installed skill pack against the remote version
  3. Writes updated skill files (.claude/skills/orgx/*.md, .cursor/rules/orgx.md)
  4. Patches the local MCP config for every detected client to pick up any server changes
  5. Emits a diff summary showing which skills were updated, added, or unchanged
useorgx/skills is the canonical skill authoring repo. The OrgX app/cloud runtime uses a pinned generated cache of that repo for fast, network-free agent runs; local CLI installs and Cursor/Claude rules are generated from the same source so the runtimes do not drift.

​
map

Map observed company workflows into evidence-gated operating-process candidates from the terminal. map (alias: discovery) runs the same discovery flow as the web orientation workbench: it starts a discovery run, prints the observed process cards with confidence and confirmation questions, and can propose one selected candidate as an operating process.
Under the hood, map calls POST /api/v1/discovery-runs with your API key and a stable Idempotency-Key, then — only when you select a candidate — calls POST /api/v1/discovery-runs/{runId}/propose. A proposed operating process still requires explicit human confirmation before activation.
Requires wizard auth login and a current workspace. In non-interactive mode, proposing a candidate requires --yes.

​
workspace Commands

Inspect and manage your OrgX workspaces.
Reads the current OrgX workspace from the API. Useful for verifying which workspace is active in your environment.
Lists all accessible workspaces for the authenticated user.
Creates a new workspace and makes it active immediately.
Updates the default workspace to the one matching <id>.

​
skills Commands

Install OrgX skill packs into your local Claude or Cursor environment.
This command:
  1. Writes .cursor/rules/orgx.md — Cursor rules for OrgX-aware code generation
  2. Generates .claude/skills/orgx/SKILL.md — the hosted OrgX Claude skill
  3. Installs the default starter packs: morning-briefing, initiative-kickoff, bulk-create, nightly-recap
Pull from useorgx/skills on GitHub. See Skills for a full list of available packs and the app runtime source-lock model.

​
doctor

Verifies your local setup end-to-end.
Checks:
  • Local config files exist and are valid
  • https://mcp.useorgx.com/health is reachable
  • An authenticated MCP session can call get_setup_status
  • npm registry reachability for @useorgx/wizard
  • Current-workspace connectivity
  • Local OpenClaw health (if installed)
  • Remote setup status — OrgX-operated deployments only; this check is skipped on customer machines and needs nothing from you
  • Skill version staleness — compares each installed skill pack against remote HEAD and warns when skills are out of date
When installed skills are behind the remote HEAD, doctor prints a skill version table:
Skill staleness warnings are non-fatal (exit 0) but prompt you to run wizard update. Exits non-zero when blocking connectivity issues remain. Warnings (like unpublished npm package) are non-fatal.
Run doctor after any config change or when a client reports that OrgX tools are unavailable.

​
Auto-Update

Enable the persistent weekly background updater to keep your skills current without manual update runs.

​
macOS (launchd)

The wizard installs a launchd plist at:
This agent runs wizard update --silent every 7 days using StartInterval. To inspect or disable it:

​
Linux (systemd user timer)

The wizard installs a systemd user service + timer pair:
The timer fires weekly (OnCalendar=weekly). To manage it:

​
Opt-out

To remove the background updater without affecting other wizard config:
This removes the launchd plist (macOS) or systemd timer (Linux) and stops all background update activity.

​
CI Mode

The wizard supports non-interactive CI environments:
doctor is CI-safe — it exits non-zero only on blocking issues.

​
Troubleshooting

Verify network access to https://mcp.useorgx.com/health. If you’re behind a corporate proxy, ensure the proxy allows WebSocket and SSE connections to mcp.useorgx.com.
Re-run auth login to mint a fresh key:
Or use the manual fallback:
Verify your current base URL and API key:
If workspace list fails, re-run auth login.
Check which surfaces are configured:
Then add the missing surface:
Restart your client after patching.
Run:
This writes .claude/skills/orgx/SKILL.md and installs the starter packs. Restart Claude Code to pick up the new skills.

​
Next Steps

Skills Reference

Full list of available skill packs and what each one does.

OpenClaw Plugin

Pair OrgX directly in your browser session with auto MCP config.

Tool Profiles

Reduce tool-surface overhead by connecting with a focused profile.

MCP Reference

Full API reference for every OrgX MCP tool.