Getting Started

Hyperion is an agentic workspace: a terminal multiplexer, an AI agent swarm, and a live task board fused into one surface. You describe outcomes; agents plan, code, test, and ship them in parallel while you supervise.

Note

Hyperion runs entirely on your machine. A workspace lives inside your repository in a .hyperion/ directory.

Installation

Install the CLI with your package manager of choice:

npm install -g @hyperion/cli

Tip

Prefer the desktop app? Grab a signed build for Windows, macOS, or Linux on the download page — the CLI is bundled.

Quick Start

Three commands take you from an empty repo to a working swarm:

quick startshell

CLI

The hyperion binary is the front door to everything — workspaces, agents, tasks, and the board all have first-class commands. Every command supports --json for scripting.

hyperion --help

Commands

CommandDescription
hyperion initCreate a workspace in the current repo
hyperion swarm startAttach agents and tile their terminals
hyperion task add <goal>Plan a goal and dispatch it
hyperion agents lsList agents with live status
hyperion attach <agent>Take over an agent's terminal
hyperion boardOpen the task board
hyperion logs <task>Stream a task's execution trace
hyperion stop --allHalt the swarm, keep the worktrees

Configuration

Everything is configured from a single typed file at the workspace root:

hyperion.config.tstypescript
// hyperion.config.ts
import { defineConfig } from "@hyperion/core";

export default defineConfig({
  agents: {
    max: 6,               // concurrent agents
    model: "claude-fable-5",
    memory: true,         // persist context across sessions
  },
  terminals: {
    grid: [4, 4],         // up to 16 panes
    shell: "zsh",
  },
  git: {
    worktrees: true,      // isolate each agent on its own worktree
    autoPr: true,         // open a PR when a task completes
  },
  board: {
    columns: ["Backlog", "In Progress", "Review", "Done"],
  },
});

Warning

Raising agents.max above your machine's core count will slow the swarm down, not speed it up — agents are CPU-bound while running your tests.

Agents

An agent is a model, a terminal, and a git worktree bound together. Agents plan goals into task graphs, code against isolated branches, test their own output, and review each other's diffs before anything reaches you.

Agent memory persists conventions and decisions across sessions, so the second week is faster than the first.

Workspaces

A workspace tiles terminals, editors, previews, and the board into one adaptive canvas. Layouts are saved per-project and restore exactly — pane sizes, scroll positions, running shells.

Task Board

The kanban board is the swarm's source of truth. Cards move themselves as agents progress; drag a card onto an agent to dispatch it, or drag it back to Backlog to halt work.

Tip

Cards accept plain-language goals. "Make the settings page not feel slow" is a valid task — planning turns it into concrete sub-tasks.

API

Everything the CLI does is available programmatically through the SDK:

swarm.tstypescript
import { Hyperion } from "@hyperion/sdk";

const hq = new Hyperion();

// Plan a goal into a dependency-aware task graph
const plan = await hq.plan("add rate limiting to the API");

// Dispatch it to the swarm and stream progress
const run = hq.dispatch(plan, { agents: 3 });

for await (const event of run.events()) {
  console.log(event.agent, event.status, event.file);
}

const pr = await run.result(); // → { url: "…/pull/219" }

Examples

Common one-liners to steal:

hyperion task add "upgrade to react 19" --agents 2
hyperion swarm start --agents 4 --model claude-fable-5
hyperion logs 04 --follow

FAQ

No. Agents execute locally in your terminals and worktrees. Only the model calls you configure leave the machine — never your repository, unless you push it.

Yes. Every agent works in a real terminal pane — attach to it, pause it, type into its shell, or reassign the task from the board at any point.

The default cap is 6 concurrent agents, configurable in hyperion.config.ts. The terminal grid tiles up to 16 panes.

Any provider with an OpenAI-compatible or Anthropic API. Set the model per-workspace or per-agent in the configuration file.