Helix Org

Helix Org is a system for running AI agents as persistent workers inside an organisation structure, with roles, streams, and managed activation.

Helix Org is a framework for running AI agents as workers inside a structured organisation. Where regular Helix agent apps respond to individual user requests, Helix Org workers are persistent, role-based agents that subscribe to event streams, collaborate with each other, and escalate to human managers when needed.

This is distinct from user organisations, which are shared workspaces for collaboration. Helix Org is an AI-native org chart.

Core concepts

Workers

A worker is a running AI agent with a defined role and identity. The worker model is designed for two kinds:

• AI workers — powered by an LLM, activated by events, execute tasks autonomously.
• Human workers — real people who receive escalations and send instructions. Human workers participate in the same org structure as AI workers: they can hold roles, appear on the org chart, receive DMs from AI workers, and act as managers in the reporting hierarchy.

Workers are hired into roles. A worker's behaviour is governed by three files: role.md (what the worker does), identity.md (how the worker behaves), and agent.md (org-wide policy).

Roles

A role defines a worker's responsibilities, tools, and activation conditions. Roles are version-controlled YAML/Markdown files. An operator edits a role to change what a worker does; the change takes effect on the next activation.

Example roles: Documentation Engineer, QA Analyst, Code Reviewer, Customer Support Agent.

Streams

Streams are typed event channels. Workers subscribe to streams that are relevant to their role and publish to streams when they produce output. Streams decouple producers from consumers: a stream can have many subscribers, and a worker doesn't need to know who is listening.

Stream types:

Activations

An activation is a single turn of a worker's work loop. A worker is activated when an event arrives on a subscribed stream, runs its task, and exits. The next event triggers the next activation.

Before each re-activation the system clears the session's conversation history, so every activation starts on a fresh context window. This is intentional: a worker that accumulates its full transcript across many activations will eventually hit the model's context limit and trigger expensive, lossy compaction. Workers persist their durable state to Markdown files in a git branch — not to the chat history — so clearing the conversation discards no real information. The first activation (no prior session yet) skips the clear and opens a fresh session directly.

How Helix Org differs from agent apps

Typical Helix Org patterns

Automated documentation — a Documentation Engineer worker subscribes to the main branch push stream. When code changes land, it reads the diff, decides if docs need updating, and opens a PR.

QA analysis — a QA Analyst worker subscribes to CI result streams and DMs the team when a test suite regresses.

Support triage — a Support Triage worker subscribes to a webhook from your support platform, classifies incoming tickets, and routes them to the right team.

Multi-worker pipelines — a Planner worker receives a feature request, breaks it into tasks, and publishes them to a task stream where individual Developer workers pick them up.

Setting up Helix Org

Helix Org is configured via the Helix Org section in the left sidebar. From there you can:

• Workers — view running workers; filter the list by role using the dropdown above the table. Hire a new worker with + New Worker: select a Role, choose a Kind (AI agent for a fully automated LLM-backed worker, or Human for a person-in-the-loop), optionally set a Reports to parent worker to place them in the org hierarchy, then confirm. The hired worker starts on its next triggering event.
• Roles — create roles with + New Role and edit existing role specifications. After clicking Create, the UI navigates to the new role's detail page where you can add MCP tools to the role. New roles start with an empty tool set — add the tools this role needs from the detail page before hiring workers into it.

managers returns the workers the caller reports to; reports returns its direct reports. Each result includes the dmStreamId needed to open a direct message. Because dm enforces reporting-graph scope, these tools are the correct way to discover valid DM targets before sending a message.

• Streams — create and monitor event streams
• Org chart — visualise the reporting structure; connect workers with reporting lines and delete connections by hovering over a line

Worker runtime settings (which LLM, which code agent engine) are configured per-worker in Helix Org → Settings.

Worker credentials

Workers that run git, gh, or authenticated API calls need a GitHub token. Tokens are not pre-loaded into the container — instead, workers call the mint_credential MCP tool at the start of any authenticated operation and again if they receive a 401 or 403.

mint_credential returns a short-lived token tied to the org's GitHub identity. Add it to any role whose workers need to call git or gh:

mint_credential provider=github
→ { token: "ghs_…", expires_at: "2026-06-11T12:59:00Z" }

The pattern a worker role should follow:

1. Call mint_credential with provider=github before the first git or gh command each activation.
2. Export the result: export GH_TOKEN=<token>.
3. If a command returns 401 or 403, call mint_credential again and re-export — token expiry is expected for long-running work.

This means tokens are always fresh. A single token injected at container start would expire silently after ~1 hour; minting on demand removes that failure mode entirely.

Recovering a stuck worker

Automatic crash recovery

When the worker's agent process crashes, Helix automatically restarts the desktop container without any human action. The system retries up to 3 consecutive times with exponential backoff (15 s, 30 s, 60 s). If the worker completes a successful turn after a restart, the retry count resets.

You do not need to click anything for crash recovery — Helix handles it. The worker will be back online and ready to accept the next event within a minute under normal conditions.

Manual restart

If the worker is hanging rather than crashing — or if automatic recovery has been exhausted — click Restart agent session in the Advanced section at the bottom of the worker detail page.

What the restart does:

1. Stops the current desktop container.
2. Recreates it fresh via the same setup path as a new session — repositories are re-cloned, tools are re-initialised.
3. Resets any prompts that were stuck in a crashed state so the worker can accept new events immediately.

Any in-progress work in the current session will be lost. Work the worker has already committed and pushed to a remote branch is safe — only uncommitted local changes inside the container are discarded.

Use manual restart when:

• The worker's video stream shows a frozen or black screen and never recovers.
• A worker activation is stuck — it accepted an event but has been unresponsive for an unusual length of time with no crash logged.
• You see "Still waiting for setup…" and the worker never progresses past that screen.
• The worker has crashed and restarted 3 times in a row without recovering — automatic recovery is exhausted and the worker will not restart again on its own.

State and memory across activations

Workers persist state between activations using a dedicated branch in their per-worker git repository (helix-specs branch). State is written as Markdown files and committed after each activation. This means:

• State survives process restarts and re-deployments
• State is version-controlled and auditable
• Multiple workers can read each other's public state files

The recommended pattern is a state.md file that the worker updates after each meaningful activation, acting as a running log for the worker's future self.

Conversation history is not persistent state. Because the session is cleared before every re-activation, a worker cannot assume that anything said in a previous activation's conversation is still in context. Any decision, finding, or learnt fact that needs to survive across activations must be written to a file and committed to the helix-specs branch before the activation exits. Do not use the chat history as memory.