/ docs

Chat + agent

How turns, tools, approvals, rewind, and sessions fit together.

▶

Chat + agent — walkthrough

Video walkthrough coming soon.

Chat + agent — walkthrough

Anatomy of a turn

A "turn" starts when you press Enter in the chat input. The IDE runs roughly this loop:

Build the system prompt (active profile + steering rules + pinned context + active editor + skills).
Resolve @ mentions — @file.ts gets its contents inlined; @symbol gets the declaration; @workspace gets a workspace summary; @selection gets the current editor selection.
Send messages to the configured provider with your tool schema.
Stream the reply. If the model requests a tool call, either auto-approve (for read-only tools in hypex.autoApproveTools) or surface an approval card.
Execute the tool, append the result, loop back to step 3 until the model stops requesting tools. Max 20 iterations per turn.
Post-turn: persist the session, auto-title it if it's still "New chat", bump server usage counter if signed in.

Slash commands

Type / at the start of the chat input — a filterable dropdown pops up with fuzzy match (prefix → substring → subsequence). ↑/↓ to navigate, Enter / Tab to insert, Esc to close.

/artifact <description> — build a rendered artifact (HTML / SVG / Mermaid / React) preview panel
/plan <goal> — agent proposes a plan, zero tool calls (pairs with Plan Mode toggle)
/help — cheatsheet of every slash command, tool, @ mention, current mode/profile/provider
/explain — describe the active file
/tests — generate tests for the active file
/commit — draft a commit message from the current diff
/fix — auto-fix diagnostics in the active file
/refactor <instruction> — refactor the selection
/docs — add / update JSDoc / docstrings in the active file
/review — review the active file for bugs + style
/clear — archive current chat + start a new session
/save <name> — save the current prompt to .hypex/prompts/
/run <cmd> — run a shell command through the agent

Context mentions

Mention	What it does
`@<filename>`	Inlines the file's contents as context
`@<symbol>`	Inlines the symbol's body (function / class / interface)
`@workspace`	Generates a tree summary of the workspace
`@selection`	Uses the current editor selection

The popup searches files AND workspace symbols in parallel and merges the results.

Run mode — Approve · Auto · Plan

The status bar has a single badge that cycles through three run modes on click:

$(shield) Approve (default) — modifying tools prompt for approval, safe tools auto-approve.
$(rocket) Auto — hypex.agent.fullAutoMode on. Every tool runs without asking. Good for long agent runs on local models. First enable shows a modal warning.
$(checklist) Plan — hypex.agent.planMode on. Mutating tools (write_file / edit_file / run_command / desktop_* / artifact_create / MCP) are hard-blocked — the agent can only read files, grep, browse the web, and produce a written plan. Read-only tools stay available so it can inspect before proposing.

Commands: Hypex: Toggle Plan Mode, Hypex: Toggle Full Auto Mode, Hypex: Cycle Run Mode.

Approval model (Approve mode)

Every tool call that could modify your machine (write_file, edit_file, run_command, update_memory, desktop_*, artifact_create) renders as an approval card. Click Allow / Deny / Always allow.

Always allow persists to hypex.autoApproveTools. For high-risk tools (shell, file write, memory, desktop) it requires a modal confirm before persisting — a misclick shouldn't grant perpetual shell access.

Full tool list + approval defaults on Tools + approval.

Artifacts

When the agent calls artifact_create (e.g. from /artifact cyberpunk YouTube clone), a preview panel opens beside the editor with three tabs:

Preview — sandboxed iframe (html / svg) or rendered React (jsx / tsx via esbuild-wasm) or mermaid diagram.
Code — syntax-highlighted source (highlight.js github-dark-dimmed).
Versions — every v1.html, v2.html… saved to .hypex/artifacts/<id>/. Click to rollback.

Toolbar: Copy source · Download as file · Open external in the system browser · Refresh iframe · Share (public short URL via worker) · Fullscreen.

Rewind ↶

The ↶ button in the chat header:

Aborts any in-flight stream
Pops the last assistant reply + preceding user message from the session
Restores the user text back into the input so you can edit and resend

Disabled if the session has no messages yet.

Sessions

Multi-session — each chat has its own history, model selection, and checkpoint thread. Click the session pill in the chat header to list / switch / rename / delete. Ctrl+Alt+N creates a new session.

Sessions auto-title themselves after the first turn from a 3-5 word summary of your first message. Default title is "New chat".

Export: Hypex: Export Current Session writes a markdown transcript. Import: Hypex: Import Session… accepts either Hypex's own export format or a Claude Code CLI .jsonl transcript.

Checkpoints

Every batch of modifying tool calls is snapshotted to .hypex/checkpoints (git-backed) before it runs. If the agent trashes your code, Ctrl+Alt+Z rolls back to the last checkpoint. Hypex: Show Checkpoint Timeline lists every snapshot.

Profiles + auto-switching

13 built-in profiles: Default, Systems, Local, Free-tier, Architect, Debugger, Tester, Refactor, Explainer, Security research, Research, Kernel-mode, Game research. Each has its own system prompt and optional auto-trigger regex. Set hypex.agent.mode = "auto" to pick the profile per message; the chat log drops a subtle chip when the switch fires.

Deep dive: Agent profiles.

The chat header at a glance

Provider pill — current provider · model. Click to swap.
Profile pill — active profile name. Click to swap.
Account pill — "Sign in" or your name. Click to open /account.
Session pill — current chat title. Click to open the session popup.
↶ rewind · 🗑 new chat · ⚙ settings · ⛶ maximize