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/ directory.Installation
Install the CLI with your package manager of choice:
npm install -g @hyperion/cliTip
Quick Start
Three commands take you from an empty repo to a working swarm:
▋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 --helpCommands
| Command | Description | |
|---|---|---|
| hyperion init | Create a workspace in the current repo | |
| hyperion swarm start | Attach agents and tile their terminals | |
| hyperion task add <goal> | Plan a goal and dispatch it | |
| hyperion agents ls | List agents with live status | |
| hyperion attach <agent> | Take over an agent's terminal | |
| hyperion board | Open the task board | |
| hyperion logs <task> | Stream a task's execution trace | |
| hyperion stop --all | Halt the swarm, keep the worktrees |
Configuration
Everything is configured from a single typed file at the workspace root:
// 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
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
API
Everything the CLI does is available programmatically through the SDK:
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 2hyperion swarm start --agents 4 --model claude-fable-5hyperion logs 04 --followFAQ
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.