Skip to main content

​
Overview

For a first evaluation without local configuration changes, use the Pick up where you left off walkthrough. The local wizard is a separate setup path: depending on the selected client and integration, it can install session hooks and capture local session metadata or work context. Review data handling before running it on a machine containing employer code.

​
Choose the smallest useful setup

The explicit-consent wizard update offers Explore the browser example, Continue with local setup, or Exit before setup work. Unattended setup requires --yes. Check setup --help before relying on these options. If it does not list --yes, your installed package predates this flow: use the browser walkthrough or wait for a package version with explicit consent.

​
Why capture choices matter

MCP access and session capture are different decisions. MCP receives the arguments a client sends to a tool. Session hooks observe local runtime events to support continuity; metadata can reveal project names and local paths even when prompt content is excluded. In the explicit-consent update, hooks install defaults to metadata-only. Choosing --work-capture bounded adds redacted request excerpts to work-episode capture. Redaction is not a confidentiality guarantee. Other plugin and setup integrations have their own capture behavior; this flag is not a global policy. The command prints the targets and capture mode before asking for confirmation. Inspect configuration with hooks doctor and surface list. Hook event files live under ~/.config/useorgx/wizard/hooks/; they can contain session IDs, working-directory/transcript paths, timestamps, and event summaries. Review a replay or publishing command separately before uploading local records. Use uninstall --help to review removal choices and surface remove <name> to remove a selected client integration. Removing local integration or clearing local auth does not revoke all remote credentials or delete hosted records. Revoke the connection and review stored-data deletion and remaining copies separately. For work data, ask your security reviewer to approve the specific data classes, access scope, retention, and provider boundary. Request missing deployment evidence at [email protected]. A successful connection is not a security review. @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, and writes local MCP configuration after your setup choices. Node 22 or newer is required.
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

Checks local configuration and the health checks reported by your release. Verify hosted OAuth separately inside your selected client.
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 versions before the explicit-consent update, non-interactive setup can patch detected surfaces without prompts. The update requires --yes before that behavior. Do not use unattended setup as an inspection command. For skill refresh, use skills sync or skills add after reviewing skills --help. These commands do not imply a background updater is installed.

​
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, add OrgX from the ChatGPT plugin directory; see the ChatGPT integration guide.

​
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.

​
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

Check local configuration, endpoint reachability, and the checks reported by this installed release:
Doctor does not establish that your selected host’s OAuth session can call hosted MCP tools. Finish verification inside that client with one permitted read and confirm the expected workspace. A healthy endpoint can still have a missing or expired client authorization. Runner readiness and capture delivery are independent checks.

​
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.