helixor

Durable code memory and verified understanding for AI coding agents.

pipx install helixor            # after PyPI publication
helixor up                      # starts companion-lite + tray
helixor index ~/code/my-repo
helixor mcp-config --transport http
helixor agent install           # choose Claude, Codex, Grok, or generic MCP

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 installing the Codex MCP server, restart Codex Desktop or the IDE extension before opening a new task. For the CLI, exit the current session and start a new one. Verify the durable registration with codex mcp get helixor or inspect active tools with /mcp inside Codex.

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.

In trial mode, helixor index uploads a bounded source snapshot and the protected Helixor cloud builds the artifact, which the companion installs and queries locally. Later source changes are debounced, rebuilt through that same provider boundary, and installed back into the local store. Workspace indexes watch and rebuild only the repository roots recorded in their manifest, so an unrelated change elsewhere in a superproject does not inflate or stale them. 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 is a swap at the companion/provider boundary. The public CLI may start an installed enterprise companion with:

helixor up --companion-provider enterprise-local

but the enterprise package owns any local Jewel/Helix execution dependencies. 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.