Get started with the Helixor Code CLI

helixor is the Helixor Code command-line tool. It runs a local companion that indexes your source code and serves it to AI coding agents over MCP, and it includes the helixor agent commands for building agents. This page takes you from install to your first indexed search. It is a different program from helixor-pack, the Decision Runtime CLI.

Every command on this page was checked against helixor 0.4.36. Run helixor <command> --help for the full list of options.

1. Install#

Use Python 3.11 or later. Install pipx, run pipx ensurepath, and open a new terminal:

pipx install helixor
helixor --version

helixor --version prints the installed version, for example helixor 0.4.36. To upgrade later, run pipx upgrade helixor.

2. Create an account#

There are two ways to create an account. Both create the same Helixor Code account.

helixor signup --name "Your Name" --email you@example.com

helixor signup needs an interactive terminal and a working OS keyring: the macOS login Keychain, Windows Credential Locker, or Secret Service or KWallet on Linux. It never writes your session to a plain file. To read the agreement first, run helixor license review --full; this does not accept it.

• HTTP 503 EMAIL_AUTH_UNAVAILABLE (0.4.36 prints it inside EMAIL_CHALLENGE_FAILED: the Code API refused the email code request (…)). Email sign-in is not available on that server yet. Use the web route, then helixor production login.
• SESSION_KEYRING_UNAVAILABLE or SESSION_KEYRING_SAVE_FAILED after you entered the code. Your account exists. Do not sign up again. Once the keyring is available, sign in with helixor production login --email you@example.com, which sends you a new code.

3. Sign in#

helixor production login

This asks for your username and password, the ones from the web sign-up. For an account made with helixor signup, use helixor production login --email you@example.com instead. Before it signs in, it prints the environment, portal, Code API, companion endpoint, and where it keeps its credentials. It then registers this machine's companion. helixor login is the same command.

4. Set up this machine#

helixor init --source-root ~/code

init brings the whole local system online:

• It stores your source roots. Repeat --source-root for each folder that holds your projects.
• It starts and registers the local companion and launches the tray.
• It installs a per-user startup service, so the companion starts again after you log in. --no-autostart leaves that out.
• It repairs the agent integrations it finds and discovers the projects below each root. By default (--index-strategy lazy) it records them and builds each project's index the first time a search needs it; --index-strategy eager builds them all during init.

Run init after step 3. On a machine that is not signed in, init starts helixor signup instead; with a web account, pass --username to sign in, or run helixor production login first.

5. Start the companion#

helixor up
helixor status
helixor doctor

helixor up starts the local companion and the tray. After init they are already running, and the startup service restarts them when you log in. Run up after helixor down, or on a machine set up with --no-autostart. helixor status shows each local runtime, its version, and whether this machine's session is signed in and registered. helixor doctor checks the install, the companion, and your session.

6. Connect an MCP client#

Agents reach Helixor through the companion's MCP endpoint, http://127.0.0.1:18733/mcp/. It is the only MCP endpoint; the CLI does not run a second server.

helixor agent install                 # choose your agent from a list
helixor agent install mcp-generic     # print the configuration for any MCP client

helixor agent install --help lists the agents it can configure directly. For any other MCP client, mcp-generic prints a block to add to that client's MCP configuration:

{
  "mcpServers": {
    "helixor": {
      "url": "http://127.0.0.1:18733/mcp/"
    }
  }
}

mcp-generic writes no client configuration; it prints the block for you to add. Restart the client after you change its configuration.

7. Your first calls#

Ask your agent to use the Helixor tools, or call them directly from an MCP client.

code.search: search your indexed code#

{ "query": "parse_config", "limit": 5 }

The result lists matching files and symbols, each with its project, file, and line. By default a query matches words in file paths and symbol names as typed. "match": "word_forms" also finds other forms of each word, and "match": "text" also searches inside files and returns the matching lines. "mode": "explain" explains a symbol instead of listing matches.

brain.todo: keep a shared TODO list#

{ "action": "push", "subject": "first-steps", "title": "Try Helixor Code",
  "items": ["Search the code", "Connect a second agent"] }
{ "action": "peek", "subject": "first-steps" }

A TODO list belongs to a subject and is kept in your Helixor Code account, so every agent you connect sees the same list. peek shows the current list for a subject. update marks or edits an item. A push on a subject that already has a list stacks a new list on top, and pop returns to the one below.

8. Create an agent#

The helixor package includes the agent commands. In an empty folder:

helixor agent new --list
helixor agent new customer-care --application --description "Order help and support."
helixor agent new customer-care --from refund-helper
helixor agent check customer-care

new --list shows the starters. new --application creates an application folder, and new --from adds an agent to it. Agent names are unique across a tenant, so the agent is named customer-care-refund-helper; --name picks another. check shows exactly what the model will get: instructions, skills, tools, rules, and budget. It deploys nothing. The Agent Framework quick start continues from here.

Next#

• Create your first agent: the browser and CLI paths for the Agent Framework.
• Accounts and licenses: the license agreement and what an account gives you.