# Integrations

**An integration connects hlix to a system your team already runs**, so work arrives and results land where people are already looking. Four exist today, and each has its own page with prerequisites, connect steps, and failure modes.

## Prerequisites

- A hlix workspace, and agency `owner` or `admin` — connecting and revoking an installation is workspace administration
- Administrative access on the other side: a GitHub organization or account, a Linear workspace, or a Slack workspace. Telegram needs no access of its own — a chat joins with a one-time link code

## What each one does

| Integration | Direction | hlix reads | hlix writes back |
| --- | --- | --- | --- |
| [GitHub](/integrations/github/) | outbound | repositories and branches you grant | task branches, commits, pull requests |
| [Linear](/integrations/linear/) | inbound + outbound | the issue that triggered a session | agent activities in the session thread |
| [Slack](/integrations/slack/) | inbound + outbound | DMs and `@mentions` in channels the bot is in | the agent's replies, as Block Kit |
| [Telegram](/integrations/telegram/) | inbound + outbound | messages in a linked chat | the agent's replies in the chat |
**None of these is required:** hlix runs a project end to end with no integration connected at all. A repo-less project keeps its durable state inside its own [Coding Workspace](/concepts/coding-workspace/), merges each task branch there, and makes the result downloadable. GitHub adds an external branch and pull-request surface; it is not where the work happens.

## What is not an integration

Two things that look adjacent and behave differently:

- **Importing a local project** needs no connection at all. The CLI discovers local environment configuration, preserves Git history, encrypts protected files, and creates the project directly in your workspace. Start at [Import a project](/cli/import/).
- **MCP servers** are a project resource, not a workspace integration. A project scan preserves MCP configuration but does not activate it; you import one reviewed server explicitly with `hlix mcp import`. See [Import skills, agents & MCP](/cli/resources/). The [official hlix MCP server](/mcp/) points the other way — it lets a local coding agent operate hlix.

## Building your own

The [OpenAPI 3.1 contract](/api/openapi/) covers direct integrations and reproducible code generation. Above it sit the [TypeScript SDK](/sdk/typescript/) and the source-preview [Python](/sdk/python/) and [Go](/sdk/go/) clients.

## If an integration will not connect

- `403` — ``admin only`` on a revoke, or on any installation write. Connecting and disconnecting is `owner`/`admin` work.
- A callback that redirects back with `?error=…` — the query parameter names the stage that failed. Each page below maps its own values.
- An empty installation list for a user who can see the workspace — client collaborators are denied installation rows entirely, by a database policy rather than by the route.
- `500` — ``Linear OAuth not configured`` / ``GitHub App not configured``, or `503` — ``Slack is not configured on this server``. The deployment is missing that integration's credentials; this is an operator fix, not a user one.
- A chat integration that connects but never answers — the chat agent runs with the *workspace's* identity, not the sender's. Neither Slack nor Telegram maps a platform account to a hlix user; membership of the workspace or chat is the whole authorization.

## Next steps

[GitHub](/integrations/github/)
  [Linear](/integrations/linear/)
  [Slack](/integrations/slack/)
  [Telegram](/integrations/telegram/)
  [Connect your agents](/guides/connect-agents/)