sift-q

Installer CLI for Sift Q. It detects your environment and registers agent harnesses (Claude Code, Cursor, and Codex) against the hosted Sift Q MCP service. Droid is an unsurfaced compatibility target and is used only when you explicitly pass --client droid.

Requirements

Node.js 22 or newer.

Install and run

npx @sift-wiki/q@latest

Running sift-q with no subcommand starts the install wizard.

usage: sift-q [--dry-run] [--json] [--yes] [--non-interactive] [--client claude|cursor|droid|codex|none]...

• --dry-run prints the detection report and the plan, writes nothing.
• --json emits a machine-readable detect/plan/result report.
• --yes confirms the plan without prompting.
• --non-interactive fails (exit 3) instead of prompting when input is required.
• --client selects which agent harnesses to register.

Exit codes: 0 success, 1 a step failed, 2 unsupported platform, 3 usage or missing input.

Hosted agent install

npx @sift-wiki/q@latest install

Registers the detected agent harnesses against the hosted Sift Q MCP service. The CLI writes the complete managed user-scope surface set as one transaction and validates the local bytes it wrote: MCP proxy registration, conditional kernel hooks, static task enforcement, and the native-task denial hook where the harness supports them. It then opens one browser consent as the OAuth client. Do not add the MCP server or run a separate harness login by hand; those paths omit enforcement or create a second authorization flow.

OAuth install exits successfully only after the staged proxy obtains a strict server verification receipt for the configured resource and complete task and orchestration scope set, then the transaction publishes and re-verifies the exact local credential and managed surfaces. Neither the receipt nor config bytes alone are success. When npx is the only package source, the installer also persists the exact proxy launcher/runtime under owner-controlled Sift Q state; harness registrations never depend on an evictable npm cache path.

Restart already-running Claude Code sessions after install. Codex installation is explicitly staged: in Codex, run /hooks, trust the Sift Q hooks, start a new session, and run sift-q verify --client codex; only that fresh deep verification—covering both the trusted blocker hook and the live sift-q server's complete q_* task-tool inventory—can call Codex enforcement active. Cursor has no supported user-scope rule file or PreToolUse denial adapter, so its installed kernel and MCP carriers remain advisory.

Native task-tool replacement

Supported Claude installs deny exactly TaskCreate, TaskGet, TaskList, TaskUpdate, and TodoWrite. Supported Codex installs deny exactly create_goal, get_goal, update_goal, and update_plan. Subagent and process-control tools remain available. The denial is admitted as active only when verification can also prove the required Sift Q replacement channel.

The installed static rule and the sift-q://task-protocol MCP resource carry the exact per-native-operation map. In summary:

• Task creation, title/body edits, and dependency changes use two explicit human gates: show and confirm extracted intent before q_propose_changes, then q_preview_changes, show and confirm the exact artifact, and only then q_apply_changes.
• Task reads, lists, ranking, ownership, progress, completion, release, fields, tags, and discussion use their dedicated q_* operations rather than one unrestricted update call.
• Ordered Claude todos and Codex goal/plan state use a task-attached Sift Q work context. A labelled context starts only after q_claim_task, remains recoverable alongside other concurrent contexts, and stores an atomic ordered full-replacement plan with at most one in-progress step. It closes only after the existing completion or release operation establishes the task lifecycle result. A Codex blocked close additionally requires three consecutive same-condition q_record_blocked_turn attestations.

This preserves the refactor's hosted authorization, atomic claims, leases, graph-derived blockers, structural preview/apply, version checks, and receipts. Sift Q stores a declared Codex token budget and enforces blocked-turn replay, reset, and count semantics. Caller turn keys are not authenticated harness telemetry, and Sift Q cannot measure trusted token usage, remaining tokens, or elapsed harness time; it reports that boundary instead of fabricating values. Cursor does not receive native-tool denial, because it has no supported user-scope denial hook.

Where the native tools are disabled

On default paths, the managed installer adds an exact-match PreToolUse entry to ~/.claude/settings.json and writes its static deny hook under ~/.claude/hooks/sift-q/. It also installs the generated task-enforcement rule under ~/.claude/rules/. For Codex it writes the owned MCP and exact-match PreToolUse blocks into ~/.codex/config.toml, the static deny hook under ~/.codex/hooks/sift-q/, and the generated enforcement block into the active global AGENTS.md or AGENTS.override.md. Config-root environment overrides move those paths without changing the surfaces.

The transaction does not write either blocker until the spawned hosted proxy has returned the exact protocol resource and start/finish prompts, advertised exactly one of every mapped replacement, and routed every mapped name through its registered strict input schema. Claude needs a fresh session after install. Codex additionally needs /hooks trust, a fresh session, and deep verification before enforcement is reported active. Cursor has none of these blocker surfaces and is reported as advisory rather than disabled.

sift-q verify reports the registration from any directory; sift-q doctor adds read-only harness detection, public hosted reachability, and previous-install residue guidance. sift-q uninstall removes the managed registration through the harness's matching removal command.

sift-q doctor [--json] [--client claude|cursor|droid|codex]...

Doctor checks Claude Code, Cursor, and Codex by default. It never repairs configuration, starts a service, restores a backup, or checks an on-machine process. Rerun sift-q install to repair stale managed surfaces.

Other commands

sift-q import-local [--dry-run] [--db <path to forge.db>]

One-shot cutover: pushes a legacy on-machine store (forge.db) to the hosted service.

sift-q mcp --hosted --harness <client>

Runs the stdio MCP proxy a registered harness launches; not meant to be run by hand.

Configuration

• SIFT_Q_HOSTED_URL — base URL of the hosted Sift Q service used by npx @sift-wiki/q@latest install. Per packages/cli/src/wizard/terminal.ts, configFromEnv (as of 83be463, packages/sift-q at 0.7.1): unset now defaults hostedBaseUrl to the identified production deployment, https://q.sift.wiki (DEFAULT_HOSTED_URL); SIFT_Q_HOSTED_URL overrides it (trailing slash stripped); and an explicit empty string is what means "no hosted service" (hostedBaseUrl is null, and install refuses with "the hosted-agent install needs a hosted service URL — set SIFT_Q_HOSTED_URL"). This inverts the pre-83be463 meaning of leaving the variable unset (previously: unset meant no hosted service, and there was no way to opt out distinctly from unset) — noted here since QA sessions ahead of that commit observed the old behavior.