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. This is the only kind currently available.
• Human workers — real people who receive escalations and send instructions. Support for hiring human workers is under development.

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. Workers are stateless between activations; persistent state is stored in a designated state file in the helix-specs branch.

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, 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. Every role — new or existing — automatically includes a set of baseline read tools: subscribe, read_events, managers, reports, worker_log, and mint_credential. These are injected at role creation and backfilled on existing roles at API start, so a role specification never needs to list them explicitly.

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 is included in every worker's baseline tools and returns a short-lived token tied to the org's GitHub identity:

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.

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.