Complete reference for HyperAgent configuration, features, and commands.
| 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 |
Auto-approve all interactive prompts |
--prompt "<text>" |
Non-interactive: send prompt, wait for completion, exit |
--show-code |
Log generated JS to a timestamped file |
--show-timing |
Log timing breakdown to a timestamped file |
--show-reasoning [level] |
Set reasoning effort (low|medium|high|xhigh, default: high) |
--verbose |
Verbose output mode (scrolling reasoning, turn details) |
--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) |
--debug |
Enable debug event/lifecycle logging |
--version |
Show version and exit |
--help |
Show help message |
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 |
64 |
Input buffer size (kilobytes) |
HYPERLIGHT_OUTPUT_BUFFER_KB |
64 |
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_SKILL |
(none) | Skill name(s) to invoke |
HYPERAGENT_TUNE |
(none) | Set to 1 to capture LLM decision logs |
HYPERAGENT_SHOW_REASONING |
(none) | Reasoning effort level (low/medium/high/xhigh) |
HYPERAGENT_VERBOSE |
(none) | Set to 1 for verbose output mode |
HYPERAGENT_PLUGINS_DIR |
(none) | Custom plugins directory path |
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 hyperagentToggle 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) |
/config |
Show current configuration (model, timeouts, buffers, plugins) |
/help |
List available commands |
/exit |
Exit the agent (or just type exit) |
The agent registers custom tools that the LLM can call. All SDK built-in tools (bash, grep, edit, etc.) are blocked by the tool gating layer.
| Tool | Purpose |
|---|---|
register_handler |
Register named JavaScript handler code in the sandbox |
execute_javascript |
Execute a registered handler with optional event data |
delete_handler |
Remove a handler from the sandbox |
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 |
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) |
sandbox_help |
On-demand guidance: patterns, state, binary I/O, fetch, debugging |
ask_user |
Ask the user structured questions (free-form or multiple choice) |
llm_thought |
(tune mode only) Log structured reasoning for prompt engineering |
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.
| Profile | Heap | CPU | Wall | Plugins | Use case |
|---|---|---|---|---|---|
default |
16MB | 1000ms | 5s | (none) | Math, algorithms, data transforms |
file-builder |
64MB | 3000ms | 10s | fs-write | ZIP, PPTX, CSV, image generation |
web-research |
32MB | 2000ms | 30s | 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 — takes max of each limit, union of plugins
hyperagent --profile "web-research heavy-compute"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"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
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) |
Builtin ES modules available to handler code via import { fn } from "ha:<name>":
| Module | Description |
|---|---|
str-bytes |
String↔binary conversion, uint LE encoding, array concat |
crc32 |
CRC-32 checksum for ZIP/PNG |
base64 |
Base64 encode/decode |
xml-escape |
XML escaping + element builder |
deflate |
DEFLATE compression (RFC 1951) |
shared-state |
Cross-handler key-value store (auto-preserved across recompiles) |
zip-format |
ZIP archive builder (DEFLATE compressed) |
ooxml-core |
EMU conversions, 5 themes, Content_Types, rels XML |
pptx |
PowerPoint builder — 7 layouts, 13 shapes, notes, transitions, images |
pptx-charts |
Bar, pie/donut, line, area, combo charts (editable in PowerPoint) |
pptx-tables |
Styled tables, key-value lists, comparisons, timelines |
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.
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)
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>.
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.logTranscripts are written as ANSI-coloured .log files during the session,
then auto-stripped to clean .txt on exit.
Combine --prompt, --auto-approve, and --skill for fully autonomous
operation — no interactive prompts, no human in the loop:
# 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_userquestions select the first option- Config changes are applied without confirmation
- Module registration proceeds without review
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.
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/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>.