Docs / Using Heygents

Updated July 29, 2026 · ~9 min read

AI chat, runs & terminal

The chat panel is where Heygents stops being a dashboard and starts being a place you work. Every message you send launches a real Claude Code, Codex or Gemini run inside your project's actual folder - and a real terminal sits one tab away.

The dock

On a desktop screen, a project workspace is two columns: the project detail on the left and the dock on the right. The dock holds the conversation with the AI and the in-browser terminal for that project, and it is resizable, so you can give it as much or as little room as the moment needs.

Its header carries an Open wide toggle that expands the chat across the whole main region, hiding the detail pane while the left navigation rail stays visible. A second click restores the card width. The bar above the composer shows the project's working directory - the folder every run actually executes in - and clicking that path opens a small file browser rooted there, where you can navigate folders, preview files and edit text files in place.

On phones and small tablets the layout becomes a bottom tab bar and the dock is the Chat tab, full screen. Asking a question or running a terminal command switches you there automatically.

Hub AI: the maximised chat

Hub AI is a link in the left navigation rail that opens straight into the maximised chat. When you want to sit and work with the AI rather than glance at it, that is the entry point: full width, no detail pane, the conversation and composer and nothing else.

Claude Code, Codex and Gemini runs

The composer has a single unified selector pinned to the left of its toolbar. It shows the active provider logo, model name and, for Claude and Codex, the mode icon and effort dots. One click opens a popover covering everything at once:

• Provider - Claude, Codex or Gemini. Switching is always your explicit choice; Heygents never silently reroutes a conversation to another provider.
• Model - the model for that provider, remembered per provider in your browser.
• Agent mode (Claude and Codex) - Manual asks before each edit, Edit automatically applies edits itself, Plan explores read-only and proposes a plan, and Auto approves safe actions while holding risky ones.
• Reasoning effort (Claude and Codex) - Low, Medium or High thinking budget.

Existing conversations stay on the provider they started with so their sessions remain resumable, and switching provider starts a fresh conversation rather than mixing incompatible sessions. Gemini has no mode or effort, so its popover shows provider and model alone.

With Claude selected, typing / in the composer opens an autocomplete of every available skill, with a tooltip explaining each one. Files can be attached to your next message from the + menu, by pasting, or by dragging and dropping them anywhere over the conversation panel.

Streaming output

Answers stream in as they are produced, along with the tool calls the agent makes, so you can watch it read files, run commands and edit code rather than waiting on a silent spinner. Fenced code blocks render with a Copy button and, for shell commands, a Run in terminal button that types the command straight into the project's terminal. Each response also has a hover Copy button, and the chat header has a button that copies the entire conversation as a plain-text transcript.

The Canvas action on a code block opens it side by side with the conversation. HTML and SVG render as live sandboxed previews; anything else shows as source. Clicking a project-file link in a response opens that file in the canvas too, and every canvas artifact has a download action.

Crucially, runs are detached from your browser. The work happens on your own machine under the companion agent and is streamed through Heygents, so navigating away, closing the tab, losing your connection or backgrounding the app on a phone does not kill the run - it continues, its result is saved, and the app reattaches when you come back.

Approvals and interactive questions

Claude turns run through the Claude Agent SDK rather than a one-shot command, so a turn can pause mid-run and ask you something, exactly like Claude Code in a terminal. Two kinds of prompt appear: a multiple-choice question, and a tool-permission Allow / Deny. Answer it and the run continues from where it paused.

The prompt docks above the composer instead of covering the conversation, because a live run is not read-only: you can type at any point during a run. A message sent while the agent is working is queued and opens the next turn; a message sent while it is parked on a question also releases that prompt. The chat input stays visible and usable in every mode.

An approval prompt also triggers a notification: an audible cue that can repeat on an interval until you respond, and a push notification to your phone if you have enabled it.

Stop

Every running turn can be stopped from the chat controls. A manual Stop is treated as deliberate: it ends the run without marking the chat as finished-unseen or failed, so you do not get a badge chasing you about something you chose to cancel. Only the currently active chat drives the Send and Stop controls.

Run status badges

Because several conversations can stream at once, Heygents shows status wherever projects are listed. Each project row can carry up to three chips, each shown only when its count is non-zero:

• running (orange) - a live run right now.
• done (green) - a run that completed successfully and has not been looked at yet.
• failed (red) - an unexpected error or interruption you have not seen yet.

Opening the chat clears either terminal marker. The collapsed icon rail has no room for three chips, so it merges them into one badge coloured by the most urgent status; the expanded rail and the mobile project switcher show the full breakdown. The same colour language runs through the tab strip, History, notifications and the active-chat banner, with blue added for "waiting for your input".

The active chat always shows a state banner: Ready with quick next actions, Processing with a pulsing live status and a paused composer to prevent duplicate sends, or Connection lost / Execution paused / Error with a Retry or Resume action when a stream drops.

Chats, tabs and history

Conversations live in a browser-style tab strip above the log. Every chat with any history appears there - running, finished, or finished and viewed - and only empty drafts and chats you explicitly close are kept off it. Tabs are ordered newest first so a chat that just replied floats to the front, and you can drag them into any order you like; your arrangement is remembered per project across reloads.

History lists every chat regardless of whether its tab is open, and its search matches both chat titles and conversation content, including messages, attachment names and tool rows. A closed chat returns to the strip the moment you reopen it.

New chats are auto-named with a short three or four word subject rather than your entire first prompt, unless you rename the chat yourself. Opening a project lands you on a fresh New chat rather than the last conversation - unless something is actively running, which opens first so live work stays visible. Unsent drafts are kept per chat, so switching between conversations never destroys text you typed but did not send.

When a turn finishes, a row of quick-action pills appears under the last response for one-tap follow-ups, including one that registers the next step directly on the project's task list. Chat text can be scaled between 80% and 160%, and a direction button cycles the conversation between Auto, RTL and LTR.

The in-browser terminal

Beside the chat, the dock holds a real interactive terminal for the project, running in the project's working directory. It is a genuine shell, not a command box: interactive programs, long-running processes and the AI CLIs themselves all work. Anything you can do over SSH in that folder you can do here, from the same browser tab as the conversation.

The terminal is also the target of the Run in terminal buttons on shell code blocks and on the health popovers, which copy a command and type it in for you - so a suggested fix goes from a chat message to a running command in one click.

Where your code runs: the companion agent

Heygents is a browser tab, and your repositories are not in that tab. Your code stays on your own computer, and Heygents never copies it anywhere - which also means it cannot reach that computer by itself.

The answer is the companion agent: a small program you install on that machine with a single command, and it is a required setup step, not an optional extra. It connects outbound to Heygents - no inbound ports, no firewall changes - and runs the AI CLI locally, in the project's real folder, using the CLI logins already on that machine. Its output streams back through the normal run pipeline, so the chat behaves as if everything were happening in the tab.

Working this way brings a few extra affordances. The working-directory Browse button browses that machine's filesystem by asking the project's agent, an optional Agent host field lets you say which machine to use when you have more than one, and the working-directory bar shows a connection chip: green for a connected agent, red for none. The terminal works the same way, relayed through the agent into the project's real folder.

Frequently asked questions

Can I run more than one chat at a time?

Yes. Each turn is a detached run, so you can start a new chat or open another from history while one is still working, and the chat you leave keeps streaming with its answer waiting when you return. Conversations live in a browser-style tab strip ordered newest first, and each project row shows running, done and failed counts.

What happens if I close the browser mid-run?

The run continues on your machine under the companion agent and the result is saved. Reopening Heygents reattaches to any live run and reloads the history, including after a phone has been backgrounded or has lost its connection. Backgrounding the app is treated as a temporary disconnection rather than a cancellation, and a notification tells you the moment the run finishes.

Do I need an API key?

No. Runs use the CLI logins already on the machine, which means they draw on your existing subscription rather than a metered key. Provider API keys are actively stripped from those spawns, so Heygents can never quietly start billing a metered API behind your back. The keys vault in Settings stores credentials for explicit, user-initiated uses instead.

Why did my chat get renamed?

New chats are auto-titled with a short three or four word generated subject after your first message, rather than using your entire prompt. Renaming a chat yourself locks the title, and a chat started from a task card is named after the task and is never auto-summarised. Unsent drafts are kept per chat, so switching conversations never loses text.