# Helix developer documentation

Helix is an evidence-first Engineering Graph and independent execution ledger.
It connects repositories, files, services, dependencies, pull requests, owners,
reviews, and agent actions so teams can ask what the system does, what a change
affects, and whether an autonomous change is safe.

## CLI quickstart

Install from the Helix repository:

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

The recorder is an optional advanced integration; Ask, Graph, and Reviews work
without it. Create a scoped 24-hour token with an authenticated Helix session:

curl -X POST "https://YOUR_API/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_id","run_id":"github:owner/repo:pr-481:head-sha","expires_in_hours":24}'

Copy the returned token value, then connect this machine to the same repository
and run:

helix connect --api-url "https://YOUR_API" --token "hxrt_..." --organization "org_id" --repository "repo_id" --run-id "github:owner/repo:pr-481:head-sha" --agent "codex"

Run an agent command:

helix run --agent codex -- pytest -q

Inspect or remove the connection:

helix status
helix doctor
helix disconnect

Record a typed action:

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

## API

Scale workspaces can create a revocable workspace API key in Settings -> API
access. Authenticate external requests with Authorization: Bearer hxapi_... and
X-Helix-Organization. Signed-in product requests use the user's Supabase access
token instead. Never expose the Supabase service-role key.

Plan limits: Explorer includes 1 public repository, 1 user, 8 pull requests per
index, 5 Ask questions/month, and a Pulse preview. Team includes 10 repositories,
10 members, 25 pull requests per index, unlimited Ask, private repositories,
the full Pulse, cross-repository graph access, and 12 months of history. Scale
includes unlimited repositories and members, 50 pull requests per index,
organization alerts, graph export, higher indexing limits, advanced graph and API access, and 24 months
of history.

POST /api/execution-events
Append an agent action. Authenticate with Authorization: Bearer <recorder-token>
and X-Helix-Organization. The token must be scoped to the same organization,
repository, and run_id in the request.

POST /api/ask
Ask a repository-scoped question. Body fields: organization_id, repository_id,
question, optional model, and bounded conversation_history. The response includes
the answer, evidence-bound claims, evidence records, model state, and terminal status.

GET /api/ask/{question_id}
Read the authoritative persisted Ask result. Poll this endpoint until terminal is
true; it distinguishes pending, completed, and terminal model states.

POST /api/graph/explore
Explore a bounded directed graph neighborhood. Body fields include
organization_id, repository_id, query, entity_id, depth, relationship_type,
direction, min_confidence, and limit.

GET /health
Returns API health.

## Event types

shell_command, file_read, file_write, network_request, secret_request,
tool_call, mcp_call, subagent_spawn, package_install, github_api.

## Security

Recorder tokens are short-lived, stored hashed, and scoped to one repository
and run. Never provide a Supabase service-role key to an agent. The Companion
is fail-open when recording is temporarily unavailable and prints a warning.
The evidence ledger does not record hidden chain-of-thought; it records action
boundaries and policy decisions.