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.

Signed Billing token leases

Production companions can require a short-lived, prepaid token lease before executing any billable code.* MCP action. Install the generated Quantum SDK seams and enable the fail-closed mode:

pipx install 'helixor[billing]'
export HELIXOR_CODE_TOKEN_LEASE_MODE=required
export HELIXOR_CODE_BILLING_URL=https://billing.example.com
export HELIXOR_CODE_SYSTEM_URL=https://system.example.com
export HELIXOR_CODE_BILLING_REALM=helixor
export HELIXOR_CODE_TOKEN_LEASE_ISSUER=quantum-billing
# Optional local overrides may only make the signed offering policy stricter.
# export HELIXOR_CODE_TOKEN_LEASE_WARNING_PERCENT=30
# export HELIXOR_CODE_TOKEN_LEASE_SETTLEMENT_GRACE_ACTIONS=1
export HELIXOR_CODE_TOKEN_LEASE_PENDING_TIMEOUT_SECONDS=1800

Quantum System resolves the user's one active Billing account. Billing debits the selected per-user bucket once, snapshots the admitted Helixor Code action rates, and returns an Ed25519-signed lease bound to the realm, account, bucket, user, companion, service, allocation, and expiry. The companion verifies the signature against keys obtained from Billing's authenticated public signing-key endpoint and kept only in process memory. It never trusts a public key stored beside the editable lease cache. It reserves the action's signed rate locally before dispatch so concurrent calls cannot overspend the lease, consumes only successful actions, and reports a monotonic hash-chained checkpoint after each action. Deferred checkpoints remain in an ordered local queue and are replayed in sequence.

Low balance and deferred settlement produce MCP-visible warnings. Exhaustion, an invalid signature, an expired lease, an undeclared action, or settlement failures beyond the configured grace return a typed tool error and stop billable actions until Billing can issue a replenished lease. The status is available at GET /api/v1/companion/billing/lease. warn mode supports an observational rollout; off preserves installations where Billing activation has not yet been scheduled.

The cached file is permissioned 0600, but local files are not the security authority. Billing's prepaid journal entry, signed claims, server-side report sequence, and immutable report rows are authoritative. A fully compromised machine can patch its local executable; stronger resistance for that threat requires platform code signing and hardware-backed attestation in addition to signed leases.

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 and it does not require a second localhost daemon. The local companion delegates through the authenticated Helixor Code control plane, which invokes the governed reasoning runtime with a platform service identity and explicit delegated-user context. brain.query action=capabilities is a mandatory doctor/repair probe. A clean install is not ready unless the companion can call it, and failures remain explicit rather than falling back to an ungoverned local implementation.

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.