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.

Authentication is environment-scoped. The explicit forms are preferred in automation and remediation output:

helixor production login   # production companion :18733 -> code.helixor.dev
helixor sandbox login      # sandbox companion :19733 -> candidate manifest target

helixor login remains a backward-compatible alias for helixor production login; when its URL is omitted, it selects the declared production profile. It refuses a known development API and directs the user to helixor sandbox login. The sandbox command defaults to the API recorded in the candidate slot manifest and refuses a different URL. Every login prints its environment, portal, Code API, companion endpoint/ID, credentials path, and config path before authenticating. Production and sandbox never share these local files.

The interactive Quantum token is used only to authorize and register the companion. Registration captures the validated Quantum principal, organization, realm, application, and device binding, then returns an environment-local hxcc_ companion service credential. Ordinary MCP cloud calls exchange that durable credential for an in-memory hxcs_ service session and renew it on demand before expiry. At each exchange, the Code API uses its own renewable Quantum service identity to revalidate the companion owner's current principal, realm membership, workspace membership, roles, and permissions. Consequently, an expired human login does not interrupt an authorized companion, while a disabled user or revoked membership still fails closed.

Production and sandbox have distinct companion credentials and service sessions. A credential registered against one Code API is rejected by the other. Removing the companion registration revokes its durable credential; rotating or renewing a service session does not require another human login. Companions registered before this contract require one final environment- specific login to capture the Quantum identity and device binding.

Inspect every known local runtime without starting or changing anything:

helixor status
helixor status --json

Status reports production and candidate process/listener health separately, the actual running executable and versions, release train and environment, companion identity, and the declared portal, Code API, and Quantum Auth binding. It also probes the known local development portal, local Code API, and tray. A stale PID, occupied-but-unhealthy listener, stopped process, or custom API with no exact release profile remains explicit rather than being reported as healthy or silently assigned an inferred Auth target. helixor doctor includes the same candidate evidence in an informational sandbox: section. A missing or intentionally stopped candidate does not make production diagnostics fail; an active unhealthy or identity-mismatched sandbox does.

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 has two published-package release trains. production is the active work installation and only selects stable PyPI releases. dev contains prerelease and development builds for the isolated candidate slot:

helixor update --train production
helixor version-check --train dev

helixor update --train dev fails with HELIXOR_DEV_UPDATE_REQUIRES_CANDIDATE_SLOT; it never replaces the active production CLI. helixor version-check --train production|dev inspects either train without changing the installed slot. The CLI never installs an arbitrary repository branch or HEAD as a published release-train update.

The CLI checks the selected train at most once every 24 hours. When a newer version is available in an interactive terminal, it shows the exact pinned 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. HELIXOR_CLI_RELEASE_TRAIN=production|dev overrides the saved train for the current process.

Development is isolated from the production companion and the current Codex task. Install a local checkout or a published dev release into the candidate slot, authenticate it only against the development API, and launch a separate Codex task with the named candidate profile:

helixor sandbox install --train dev --source ./helixor-cli \
  --api-base https://DEV_CODE_API/api/v1 --environment development
helixor sandbox login
helixor sandbox up
helixor sandbox status
helixor sandbox codex

After the first install, stop the candidate and install the next local or published build with helixor sandbox update using the same explicit development API binding. Start it again, verify helixor sandbox status, then open a new testing task with helixor sandbox codex. Existing Codex tasks keep using production throughout.

The candidate uses port 19733 and its own versioned virtual environments, credentials, config, device identity, state, index, runtime logs, PIDs, update metadata, and license receipt below ~/.helixor/slots/candidate. Production continues to use port 18733 and ~/.codex/config.toml. The sandbox launcher writes ~/.codex/helixor-sandbox.config.toml and runs codex --profile helixor-sandbox; it never rewrites the production Codex registration.

Before promotion, record live health, runtime identity, and MCP tool evidence:

helixor sandbox doctor
helixor sandbox certify
helixor sandbox down
helixor sandbox rollback        # select the prior immutable candidate release
helixor sandbox activate --release-id VERSION
helixor sandbox remove --yes

certify fails if the live candidate reports a slot, train, or environment that differs from its manifest, or if its isolated development session is not registered in the development backend. Publishing and production promotion remain separate release operations; activating a candidate release never changes the production slot.

For maintainers building the bundle from a checkout:

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

For an offline wheel-bundle installation:

./helixor-wheelhouse/install.sh

The public CLI depends on the bounded helixor-code-index-runtime worker, so a normal pipx install helixor installs local indexing support with the companion. The offline wheel bundle carries the same worker and its shared helixor-core dependency. Neither distribution includes or starts the private Helixor Code API server. helixor up starts one lightweight local companion at http://127.0.0.1:18733 plus the tray app. The companion launches the packaged worker for typed, local-only index builds, scans the local index store, reports token/value ledgers, and exposes tray health. Index rebuilds are watched by default; helixor up --no-index-watch opts out of debounced filesystem watching. 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. With --index-watch, 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.