DEVELOPER SURFACE / HELIX

Build with the context behind the code.

Helix turns repository activity into an evidence graph and an execution ledger. Use the API for grounded engineering questions, or connect the CLI once and let your coding agent record what it did.

Start with the CLI ↓Open LLM-readable docs

THE HELIX LOOP

Agent action

Execution event

Evidence ledger

Grounded answer

01 / QUICKSTART

Connect a recorder integration.

The recorder is an advanced CLI and gateway integration. Create a 24-hour token with an authenticated Helix session, copy the returned token value, and scope the CLI to the same repository and run. The everyday Helix experience does not require the recorder.

Install

python -m pip install -e backend
helix --version

Create a scoped token

curl -X POST "https://api.your-helix-deployment.com/api/agent-runtime/tokens" \
  -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN" \
  -H "X-Helix-Organization: $HELIX_ORGANIZATION_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Local coding agent",
    "repository_id": "repo_your_id",
    "run_id": "github:owner/repo:pr-481:head-sha",
    "expires_in_hours": 24
  }'

Connect this machine

helix connect \
  --api-url "https://api.your-helix-deployment.com" \
  --token "hxrt_your_token" \
  --organization "org_your_id" \
  --repository "repo_your_id" \
  --run-id "github:owner/repo:pr-481:head-sha" \
  --agent "codex"

Run an agent command

helix run --agent codex -- pytest -q

02 / AGENT RUNTIME

Record more than shell commands.

The companion records the action boundary, not hidden chain-of-thought. Use the typed event commands for file reads, network calls, package installs, tool calls, and other agent actions.

helix status

Show the active repository and run scope without printing the token.

helix doctor

Check the saved connection and whether the Helix API is reachable.

helix disconnect

Remove the local connection file from this machine.

helix record

Append one structured action from an adapter or gateway.

Record a file read

helix record \
  --event-type file_read \
  --intent "inspect authentication middleware" \
  --payload '{"path":"backend/auth.py"}'

03 / API REFERENCE

Grounded answers and execution evidence.

The backend exposes interactive OpenAPI docs at https://api.your-helix-deployment.com/docs. Signed-in browser sessions work on every plan. Scale workspaces can create a revocable hxapi_ key in Settings → API access for CI and external integrations.

Ask Helix with a Scale API key

curl -X POST "https://api.your-helix-deployment.com/api/ask" \
  -H "Authorization: Bearer $HELIX_API_KEY" \
  -H "X-Helix-Organization: $HELIX_ORGANIZATION_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "org_your_id",
    "repository_id": "repo_your_id",
    "question": "Which services depend on authentication?",
    "conversation_history": []
  }'

POST/api/execution-events

Append an independent agent action to the evidence ledger. Recorder tokens are scoped to one organization, repository, and run.

Record an execution event

curl -X POST "https://api.your-helix-deployment.com/api/execution-events" \
  -H "Authorization: Bearer $HELIX_RECORDER_TOKEN" \
  -H "X-Helix-Organization: $HELIX_ORGANIZATION_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "org_your_id",
    "repository_id": "repo_your_id",
    "run_id": "github:owner/repo:pr-481:head-sha",
    "agent_id": "codex",
    "event_type": "shell_command",
    "intent": "run targeted tests",
    "command": "pytest -q",
    "policy_decision": "allow",
    "started_at": "2026-08-13T14:00:00Z",
    "completed_at": "2026-08-13T14:00:04Z",
    "exit_code": 0,
    "payload": {"actor": "agent", "source": "helix-companion"}
  }'

POST/api/ask

Start a repository-scoped engineering question. The response returns a question ID so the UI or an integration can poll the authoritative result.

Ask Helix with a user session

curl -X POST "https://api.your-helix-deployment.com/api/ask" \
  -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN" \
  -H "X-Helix-Organization: $HELIX_ORGANIZATION_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "org_your_id",
    "repository_id": "repo_your_id",
    "question": "What depends on the authentication service?",
    "model": "grok-4.5",
    "conversation_history": []
  }'

GET/api/ask/{question_id}

Read the persisted answer, evidence-bound claims, model state, and terminal status. Poll until terminal is true.

Read the completed answer

curl "https://api.your-helix-deployment.com/api/ask/$QUESTION_ID" \
  -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN" \
  -H "X-Helix-Organization: $HELIX_ORGANIZATION_ID"

POST/api/graph/explore

Explore a bounded directed neighborhood. Explorer supports one-hop repository views, Team supports two-hop and cross-repository views, and Scale supports advanced controls up to four hops.

Explore the Engineering Graph

curl -X POST "https://api.your-helix-deployment.com/api/graph/explore" \
  -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN" \
  -H "X-Helix-Organization: $HELIX_ORGANIZATION_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "org_your_id",
    "repository_id": "repo_your_id",
    "query": "What depends on authentication?",
    "depth": 1,
    "direction": "both",
    "limit": 32
  }'

04 / EVENT SCHEMA

One shape for every agent action.

Every event is append-only and receives an evidence hash. Use the same contract whether your source is the Companion, an agent gateway, a sandbox, or an MCP adapter.

event_typeshell_command · file_read · file_write · network_request · secret_request · tool_call · mcp_call · subagent_spawn · package_install

policy_decisionallow · block · escalate · deny

scopeorganization_id · repository_id · run_id · agent_id

audit fieldsintent · command · timestamps · exit_code · payload · evidence_hash

05 / SECURITY

Keep tokens narrow and temporary.

Recorder tokens expire after 24 hours. Scale API keys are stored hashed, shown once, revocable, and expire after 90 days by default. Never give an integration a Supabase service-role key.

Use the narrow tokenRecorder keys for events; workspace keys for API calls.

Never use service roleIntegrations only receive the access they need.

Rotate and revokeReplace API keys in Settings without changing user sessions.