HyperAgent Usage Guide

Complete reference for HyperAgent configuration, features, and commands.

CLI Flags

Flag	Description
--model <name>	LLM model (default: claude-opus-4.6)
--cpu-timeout <ms>	CPU time limit per JS execution (default: 1000)
--wall-timeout <ms>	Wall-clock backstop per execution (default: 5000)
--send-timeout <ms>	Agent inactivity timeout (default: 300000)
--heap-size <MB>	Guest heap size (default: 16)
--scratch-size <MB>	Guest scratch size, includes stack (default: 16)
--profile <name>	Apply resource profile at startup (stackable)
--skill <name>	Invoke skill(s) before the prompt
--auto-approve / --yolo	Auto-approve all interactive prompts
--base-dir <path>	Auto-enable fs-read + fs-write with this directory as their base
--prompt "<text>"	Non-interactive: send prompt, wait for completion, exit
--prompt-file <path>	Read the non-interactive prompt from a file
--show-code	Log generated JS to a timestamped file
--show-timing	Log timing breakdown to a timestamped file
--reasoning-effort [level]	Set reasoning effort (low|medium|high|xhigh, default: high)
--verbose	Stream reasoning + show sandbox tool result bodies
--very-verbose / -vv	Like --verbose plus full result bodies for every tool (audit/registration/…)
--transcript	Record session transcript to ~/.hyperagent/logs/
--tune	Capture LLM decision/reasoning logs to JSONL
--plugins-dir <path>	Custom plugins directory (default: ./plugins)
--list-models	List available models and exit
--resume [id]	Resume a previous session (latest if no ID given)
--skip-suggest	Skip mandatory suggest_approach/API-discovery enforcement
--output-threshold <n>	Large output threshold in bytes (default: 20480)
--debug	Enable debug event/lifecycle logging
--version	Show version and exit
--help	Show help message

Environment Variables

All configuration is also available via environment variables (overridden by CLI flags):

Variable	Default	Description
COPILOT_MODEL	claude-opus-4.6	Model name for the Copilot SDK session
HYPERLIGHT_CPU_TIMEOUT_MS	1000	Max CPU time per JS execution (ms)
HYPERLIGHT_WALL_TIMEOUT_MS	5000	Max wall-clock time per execution (ms)
HYPERAGENT_SEND_TIMEOUT_MS	300000	Agent inactivity timeout (ms)
HYPERLIGHT_HEAP_SIZE_MB	16	Guest heap size (megabytes)
HYPERLIGHT_SCRATCH_SIZE_MB	16	Guest scratch size, includes stack (megabytes)
HYPERLIGHT_INPUT_BUFFER_KB	1040	Input buffer size (kilobytes)
HYPERLIGHT_OUTPUT_BUFFER_KB	1040	Output buffer size (kilobytes)
HYPERAGENT_PROFILE	(none)	Profile name(s) to apply at startup
HYPERAGENT_AUTO_APPROVE	(none)	Set to 1 for auto-approve mode
HYPERAGENT_PROMPT	(none)	Non-interactive prompt text
HYPERAGENT_PROMPT_FILE	(none)	File containing the non-interactive prompt
HYPERAGENT_SKILL	(none)	Skill name(s) to invoke
HYPERAGENT_TUNE	(none)	Set to 1 to capture LLM decision logs
HYPERAGENT_REASONING_EFFORT	(none)	Reasoning effort level (low/medium/high/xhigh)
HYPERAGENT_VERBOSE	(none)	Set to 1 for verbose output mode
HYPERAGENT_VERY_VERBOSE	(none)	Set to 1 for very-verbose output (full body for every tool)
HYPERAGENT_BASE_DIR	(none)	Base directory for fs-read/fs-write plugins (auto-enables both)
HYPERAGENT_LIST_MODELS	(none)	Set to 1 to list models and exit
HYPERAGENT_RESUME_SESSION	(none)	Session ID to resume, or __last__ for latest
HYPERAGENT_PLUGINS_DIR	(none)	Custom plugins directory path
HYPERAGENT_SKIP_SUGGEST	(none)	Set to 1 to disable suggest_approach/API-discovery enforcement
HYPERAGENT_OUTPUT_THRESHOLD_BYTES	20480	Large output threshold in bytes
HYPERAGENT_TIMING_LOG	(none)	Path to timing log file (default: ~/.hyperagent/logs/)
HYPERAGENT_CODE_LOG	(none)	Path to code log file (default: ~/.hyperagent/logs/)
HYPERAGENT_TRANSCRIPT	(none)	Set to 1 to record session transcript
HYPERAGENT_DEBUG	(none)	Set to 1 for debug logging to ~/.hyperagent/logs/

Example:

COPILOT_MODEL=gpt-5.1 HYPERLIGHT_CPU_TIMEOUT_MS=2000 hyperagent

Slash Commands

Toggle options at runtime without restarting. Type / and press Tab for completion.

Command	Effect
/show-code	Toggle inline display of generated JavaScript
/show-timing	Toggle execution timing breakdown
/debug	Toggle debug event logging
/timeout cpu <ms>	Override CPU timeout for subsequent calls
/timeout wall <ms>	Override wall-clock timeout for subsequent calls
/timeout send <ms>	Override agent inactivity timeout
/timeout reset	Reset all timeouts to defaults
/buffer input <kb>	Override input buffer size (kilobytes)
/buffer output <kb>	Override output buffer size (kilobytes)
/buffer reset	Reset buffer sizes to defaults
/transcript	Toggle session transcript recording on/off
/models	List available models with capability icons
/model <name>	Switch to a different model (preserves conversation)
/new	Start a fresh session (blank context, same model)
/sessions	List saved sessions with summaries
/resume [id]	Resume a previous session (latest if no ID)
/plugin list	List discovered plugins with state, risk, and approval status
/plugin enable <name> [k=v]	Audit, configure, and enable a plugin (inline config supported)
/plugin disable <name>	Disable an enabled plugin
/plugin approve <name>	Approve a plugin (persists until source changes or unapproved)
/plugin unapprove <name>	Remove plugin approval
/plugin audit <name>	Force re-audit a plugin (after source changes)
/profile list	List available resource profiles
/profile apply <name> ...	Apply profile limits and request required plugins
/mcp list	List configured MCP servers
/mcp enable <name>	Approve and connect an MCP server
/config	Show current configuration (model, timeouts, buffers, plugins)
/help	List available commands
/exit	Exit the agent (or just type exit)

LLM Tools

The agent registers custom tools that the LLM can call. Most SDK built-in tools (grep, edit, etc.) are blocked by the tool gating layer. The SDK's bash tool is also blocked — execute_bash is Hyperagent's own sandboxed bash interpreter.

Tool	Purpose
register_handler	Register named JavaScript handler code in the sandbox
execute_javascript	Execute a registered handler with optional event data
execute_bash	Run bash commands in a sandboxed pure-JS interpreter (just-bash)
delete_handler	Remove a handler from the sandbox
get_handler_source	Retrieve handler source for inspection or editing
edit_handler	Surgically edit an existing handler
list_handlers	List registered handlers with line counts
reset_sandbox	Clear sandbox state, keep handlers registered
configure_sandbox	Change resource limits at runtime (heap, scratch, timeouts, buffers)
register_module	Create a reusable ES module (persisted to ~/.hyperagent/modules/)
list_modules	List available modules (system + user)
module_info	Get module exports, JSDoc, and metadata
delete_module	Delete a user-created module
write_output	Write text content through the fs-write plugin
read_input	Read text content through the fs-read plugin
read_output	Read content previously written as output
manage_plugin	Enable/disable plugins with configuration
list_plugins	Discover available plugins
plugin_info	Detailed plugin information and config schema
apply_profile	Apply named resource profiles (limits + plugins in one step)
list_mcp_servers	List configured MCP servers and connection status
mcp_server_info	Inspect MCP server tools and generated declarations
manage_mcp	Connect or disconnect MCP servers
sandbox_help	On-demand guidance: patterns, state, binary I/O, fetch, debugging
report_intent	Protocol tool used by the model to signal intent
ask_user	Ask the user structured questions (free-form or multiple choice)
llm_thought	(tune mode only) Log structured reasoning for prompt engineering

Profiles

Profiles bundle resource limits and plugin requirements into named presets. Profiles are additive — stacking multiple takes the max of each limit and the union of all plugins when applied during a session.

CLI --profile applies CPU, wall-clock, heap, and scratch limits at startup. It does not silently enable plugins, and input/output buffer profile limits are only applied at runtime. During a run, use /profile apply or let the LLM call apply_profile to request the profile's plugin requirements.

Profile	Heap	CPU	Wall	Plugins	Use case
default	16MB	1000ms	5s	(none)	Math, algorithms, data transforms
file-builder	128MB	15000ms	60s	fs-write	ZIP, PPTX, PDF, CSV, image generation
web-research	64MB	2000ms	120s	fetch, fs-write	API calls, web scraping, data pipelines
heavy-compute	64MB	10000ms	15s	(none)	Large datasets, crypto, simulations

# Single profile
hyperagent --profile file-builder

# Stacked at startup — takes max of each limit
hyperagent --profile "web-research heavy-compute"

Skills

Skills inject domain expertise into the conversation. A skill is a markdown file (skills/<name>/SKILL.md) with YAML frontmatter specifying metadata and allowed tools, followed by structured guidance for the LLM.

---
name: pptx-expert
description: Expert at building professional PowerPoint presentations
allowed-tools:
  - register_handler
  - execute_javascript
---
# PowerPoint Presentation Expert
You are an expert at building professional, polished PowerPoint presentations...

# Interactive — load the skill and start a conversation
hyperagent --skill pptx-expert

# Autonomous — skill + prompt + auto-approve
hyperagent --skill pptx-expert --auto-approve \
  --prompt "Build a 10-slide deck on cloud architecture"

Shared State & Persistence

Handlers share data via ha:shared-state — an in-sandbox key-value store. ha:shared-state is automatically preserved across all sandbox recompiles. No manual save/restore steps are needed.

1. Research handler stores data in shared-state
2. register_handler("builder")  ← recompile (shared-state auto-preserved)
3. execute_javascript("builder") ← builder sees all shared-state data

User Modules

The LLM can create reusable ES modules at runtime via register_module. User modules are persisted to ~/.hyperagent/modules/ and survive across sessions. They're importable via import { fn } from "ha:<name>".

Tool	Action
register_module	Create or update a module (name, source, author, description)
list_modules	List all modules — system + user, with size and mutability
module_info	Exports + JSDoc; optionally query one function by name
delete_module	Delete a user module (system modules are immutable)

System Modules

Builtin ES modules available to handler code via import { fn } from "ha:<name>":

Module	Description
shared-state	Cross-handler state preserved across sandbox recompiles
ziplib	Native DEFLATE compression/decompression
zip-format	ZIP archive builder for document formats
doc-core	Shared document themes, colour validation, and input guards
ooxml-core	Shared OOXML units, colours, themes, content types, and rels
pptx	PowerPoint presentation generation
pptx-charts	Editable PowerPoint charts
pptx-tables	PowerPoint tables, comparisons, and timeline helpers
xlsx	Excel workbook generation with sheets, pivots, charts, and styles
pdf	PDF document generation
pdf-charts	PDF chart rendering
markdown	Markdown to HTML or plain text conversion
html	HTML text and link extraction
image	PNG/JPEG/GIF/BMP dimension reading
base64	Base64 encode/decode for binary data
str-bytes	String and byte conversion utilities
crc32	CRC-32 checksums for ZIP/PNG/gzip
xml-escape	XML escaping and simple element building

Model Management

Switch models mid-conversation with /model <name> — the conversation history is preserved via the SDK's resumeSession API.

You: /models
  🤖 Available models (17):
     claude-opus-4.6 ← current 👁️🧠
     gpt-5.1 👁️🧠
     gpt-4.1 👁️
     ...

     👁️ = vision  🧠 = reasoning effort

You: /model gpt-5.1
  🔄 Model switched: claude-opus-4.6 → gpt-5.1
     Conversation history preserved.

Infinite Sessions

Context compaction is enabled by default. When the context window fills up, the SDK automatically summarises older context in the background so conversations can continue indefinitely without hitting token limits.

• Background compaction triggers at 80% context usage
• Blocking compaction triggers at 95% (pauses briefly to compact)

Session Management

Sessions are persisted by the SDK. You can list, resume, and create new sessions without losing previous conversations.

You: /sessions
  📋 Sessions (3):
     a1b2c3d4e5f6…
       Modified: 25/02/2026, 12:30:00 — Fibonacci calculation and sorting demo
     f7e8d9c0b1a2… ← current
       Modified: 25/02/2026, 12:45:00 — Data processing pipeline

You: /resume a1b2
  ⏮️  Resumed session: a1b2c3d4e5f6…
     Model: claude-opus-4.6

Resume from the CLI with --resume (latest session) or --resume <id>.

Session Transcript

Record the full session (input, output, tool calls) to a file:

# Via CLI flag
hyperagent --transcript

# Via slash command during a session
You: /transcript
  📄 Transcript started: ~/.hyperagent/logs/hyperagent-20260225-123456.log

Transcripts are written as ANSI-coloured .log files during the session, then auto-stripped to clean .txt on exit.

Non-Interactive / Scripted Mode

Combine --prompt, --auto-approve, and --skill for fully autonomous operation — no interactive prompts, no human in the loop. Treat this as yolo mode for trusted prompts only:

# Autonomous PPTX generation
hyperagent --auto-approve --skill pptx-expert \
  --profile "web-research file-builder" \
  --prompt "Build a deck comparing AWS, Azure, and GCP pricing"

# Simple computation — no plugins needed
hyperagent --auto-approve \
  --prompt "Calculate the first 100 prime numbers and return them as JSON"

In auto-approve mode:

• Plugin enables are approved automatically
• ask_user questions select the first option
• Config changes are applied without confirmation
• Module registration proceeds without review

Command Suggestions

After each LLM response, HyperAgent scans the output for actionable slash commands (e.g. "/plugin enable fetch allowedDomains=api.github.com") and presents them as one-keystroke suggestions. Accept with a single keypress instead of typing the full command.

Tuning Mode

When --tune is enabled, an additional llm_thought tool becomes available. The LLM can log structured reasoning data (decisions, concerns, constraints, rejected alternatives) to a JSONL file. This is useful for prompt engineering and improving the system message guidance.

hyperagent --tune --transcript
# Decision logs written to ~/.hyperagent/tune-logs/

Keep-Alive Timeout

The agent uses a custom keep-alive mechanism that resets the inactivity timer on every session event (tool start, tool complete, message deltas). This means long-running tool chains stay alive as long as events keep flowing — the timeout only fires if the agent truly goes silent.

Default: 300s. Override with --send-timeout <ms> or /timeout send <ms>.