Metadata-Version: 2.4
Name: helixor
Version: 0.3.7
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: httpx>=0.27
Requires-Dist: msgpack>=1.0
Requires-Dist: watchdog>=4.0
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            # 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:

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

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

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:

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

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