helixor

Durable code memory and verified understanding for AI coding agents.

pipx install helixor
helixor init

helixor init collects identity and portal login, activates an existing organization membership when selected, stores one or more source roots, starts and registers the companion, launches the tray, installs a per-user startup service so helixor up runs automatically after reboot/login, repairs installed Codex and Claude integrations, installs both the helixor-code operating guidance and the helixor reasoner skill, discovers projects below each root, and builds an index per project. A small persistent workspace router makes searches span those independent indexes. On macOS the startup contract is a LaunchAgent; on Linux it is a user systemd service. Use --no-autostart only when another service manager owns the companion lifecycle.

The companion at http://127.0.0.1:18733/mcp/ is the only MCP listener. Agent clients, the tray, indexing, watchers, and workflow execution all use it.

Recovery is intentionally one command:

helixor repair
helixor repair --source-root ~/code
helixor update

repair migrates old workflow grants into persistent source roots, reconciles portal registration, removes stale Helixor listeners on port 18733, restarts the companion and tray, repairs the reboot/login startup service, repairs installed agent integrations, and verifies the real MCP tool registry. update upgrades the CLI and then runs that repair. The packaged tray also checks for, downloads, and installs its desktop update at startup.

To reset one machine without deleting team work from the portal:

helixor uninstall             # dry-run: shows the exact local reset boundary
helixor uninstall --yes       # unregister companion and remove local components
helixor init                  # reinstall, register, and reindex

uninstall removes the Codex and Claude Code plugins/MCP registrations, the tray application, companion runtime/configuration, local workflow executions, legacy workflow sandboxes, indexes, and the local usage ledger. It unregisters only this machine's companion record. Portal workflow definitions, designs, todos, workspace channels, usage records, membership, and license records are never addressed. The saved portal login is retained so helixor init can register the replacement companion without another login; pass --forget-login only when that is intentional. If the portal cannot be reached, local deletion stops before it begins. --local-only is the explicit escape hatch for removing local files while leaving a stale portal registration.

Inside a configured source root, workflows have direct read/write/delete and shell access. There are no per-workflow grants, copied staging workspaces, or approval prompts. Paths outside configured roots fail explicitly.

Agent-specific setup is available through the umbrella installer:

helixor agent install claude       # opens the Claude Desktop extension installer
helixor agent install codex        # writes ~/.codex/config.toml
helixor agent install grok         # prints/writes generic MCP JSON for Grok MCP settings
helixor agent install mcp-generic  # prints/writes generic MCP JSON

After changing the Codex MCP registration or updating the guidance plugin, reload Codex and open a new task to consume that changed configuration. A companion-only repair or restart does not require another Codex restart when the current task already exposes the required Helixor tools. Verify the durable registration with codex mcp get helixor, inspect active tools with /mcp, and use helixor doctor to verify representative tools are callable rather than merely listed.

helixor claude install remains available as a compatibility shortcut for the Claude Desktop MCP Bundle.

The CLI checks PyPI at most once every 24 hours. When a newer version is available in an interactive terminal, it shows the exact upgrade command and asks before running it. Non-interactive commands are never paused; they receive an update warning instead. Use --no-update-check for one invocation or set HELIXOR_CLI_NO_UPDATE_CHECK=1 to disable automatic checks.

For maintainers building the bundle from a checkout:

cd helixor-cli/claude-extension
node scripts/pack.mjs

For the current wheel-bundle release channel:

python3 -m pip install --find-links helixor-wheelhouse helixor

The public CLI is the cloud-trial runtime. It does not bundle private Helixor Code backend or helix-core packages. helixor up starts a lightweight local companion at http://127.0.0.1:18733 plus the tray app. The companion scans the local index store, reports token/value ledgers, exposes tray health, and keeps valid local indexes current with an always-on filesystem watcher. Build and query execution can be local or delegated to the configured Helixor provider; the durable index artifact remains in the companion's local index store.

The companion also owns brain.query; it never forwards that tool to the retired direct-MCP server. Configure its governed service boundary with --reasoning-api-base or HELIXOR_REASONING_BACKEND_URL (default http://127.0.0.1:8030/api/v1). brain.query action=capabilities is the read-only readiness probe used by helixor doctor. Query and diagnostic calls preserve the reasoning backend's authentication policy and return typed REASONING_BACKEND_* failures when the service is unreachable, unauthorized, or returns an invalid envelope.

In trial mode, helixor index discovers Python, JavaScript, Java, Rust, Go, and Git project markers under the selected path. When it finds multiple projects, it builds a separate bounded index for each rather than one oversized snapshot. Use --single-index only when a combined index is deliberate. The companion persists a lightweight workspace router and searches its module artifacts as one federated workspace. helixor init uses --index-strategy lazy: setup finishes after discovery, an exact codebase_id builds that module on first use, and an explicit scope=all builds every missing module before a workspace-wide search. Direct helixor index remains eager by default for users who explicitly request a complete root build. Only built modules are watched; later changes are debounced, rebuilt through the same provider boundary, and installed back into the local store. Configure the file-count, per-file, and total snapshot envelope from the tray's Account -> Index snapshot limits panel; the CLI --max-* flags remain available as one-command overrides. The default file-count ceiling is 10,000 after common dependency, cache, report, and build-output trees such as node_modules, target, .gradle, vendor, and reports are excluded. Files are read one at a time, so this ceiling is a runaway-snapshot guard rather than a file-descriptor budget.

The tray also shows and configures a separate Maximum local index storage quota (10 GiB by default). The companion measures the complete staged artifact, metadata, receipt, and catalog before replacing an index. If the local store would exceed its quota, the refresh fails explicitly and the existing index is preserved. Indexes are never deleted automatically; raise the quota or prune an unused index deliberately.

Enterprise local execution remains a provider swap behind the same public companion listener:

helixor up --companion-provider enterprise-local

The enterprise package owns any local Jewel/Helix execution dependencies, but does not start another MCP or companion listener. Enterprise local is the premium path for private-source teams that need the fastest loop: the licensed companion builds and queries local indexes while the cloud records license acceptance, companion registration, shared workspace state, token ledgers, and team coordination.

Build and verify the bundle from the monorepo:

PYTHON=python3.12 scripts/package-helixor.sh --smoke

Start with:

• docs/quickstart-cursor.md for Cursor MCP setup.
• docs/quickstart-collab.md for team hub or direct collaboration mode.