Metadata-Version: 2.4
Name: helixor
Version: 0.4.9
Summary: Lightweight Helixor CLI for hub login, cloud-trial indexing, companion registration, and MCP endpoint configuration.
Author-email: Michael Ingardia <mingardia@end2endlogic.com>
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: cryptography>=41.0
Requires-Dist: httpx>=0.27
Requires-Dist: msgpack>=1.0
Requires-Dist: packaging>=24.0
Requires-Dist: watchdog>=4.0
Provides-Extra: billing
Requires-Dist: quantum-billing-service>=0.1.0; extra == "billing"
Requires-Dist: quantum-system-service>=0.1.0; extra == "billing"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"

# helixor

Durable code memory and verified understanding for AI coding agents.

```zsh
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:

```zsh
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.

Inspect every known local runtime without starting or changing anything:

```zsh
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:

```zsh
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:

```zsh
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:

```zsh
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:

```zsh
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:

```zsh
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 its target
version differs 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:

```zsh
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:

```zsh
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:

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

For the current wheel-bundle release channel:

```zsh
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:

```zsh
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:

```zsh
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.
