Docs / Getting started

Updated July 29, 2026 · ~8 min read

Introduction & setup

Heygents is a control plane for the projects you actually run. It shows the live state of every project in one place, turns an AI review of your real code into a concrete task list, and lets an AI agent do the work while you watch it happen. This page takes you from first sign-in, through installing the agent, to your first project.

What Heygents is

Most tools for managing side projects are either a task board that knows nothing about your code, or a terminal that knows nothing about your priorities. Heygents sits between them. Every project you add gets one workspace that holds:

• Live status - is the site reachable, is the process up, is the port listening, and how is the host doing on CPU, RAM, disk and uptime.
• Plan - the goal, the roadmap, the README and the CLAUDE.md that describe what this project is supposed to become.
• Tasks - a prioritized list produced by a grounded Deep Scan that actually reads the repository, not a generic checklist.
• AI runs - chat with Claude, Codex or Gemini against the real working directory on your own machine, with the output streamed live to the browser and preserved if you close the tab.
• Automations - scheduled, unattended runs that scan, fix or health-check on their own.

The point is not to add process. The point is to stop holding the state of five projects in your head.

Who it is for

Solo developers and small indie makers running a handful of their own projects - a couple of side projects, maybe one or two things with real users. You are a competent developer but not an infrastructure specialist, and you want your projects watched, audited and improved without becoming a DevOps engineer.

Signing in

Opening Heygents while signed out shows the landing page with a sign-in card. There are three ways in, and they all end up at the same account:

• Email and password. Type your email and password and press Continue.
• Continue with Google. The account chooser is forced every time, so you can pick a different Google account than the one your browser is already signed into.
• Continue with GitHub. Here this really is the gate, not just an integration: it signs you in to Heygents. Connecting a GitHub account for repository features is a separate thing, covered in GitHub integration.

A few things worth knowing:

• Heygents is in closed beta and sign-ups are invite-only. If you try to sign in with an email that has not been invited, the card says so rather than creating an account.
• Invite and password-reset links open the app with a "set a password" panel instead of the normal form. Choose a password of at least 8 characters and you are signed in. If the link has expired, the panel says so and you can request a new one.
• "Forgot password?" sends a reset link and is deliberately throttled to one send every 30 seconds. It always shows the same neutral message whether or not that email has an account, so it can never be used to discover who has one.
• Your session lives in the browser and is refreshed silently in the background, so you stay signed in across tabs and restarts until you sign out. If the session cannot be refreshed, the next request drops you back to the sign-in card instead of leaving you on a half-loaded page.
• Sign out lives in the Settings menu on the left nav rail, or in the hamburger menu on phones.

Installing the companion agent (required)

This is the step that makes Heygents do anything. Heygents is a hosted web app; your code is not hosted, it is on your laptop or your own server. The bridge between them is the companion agent: a small background service you install once on the machine your projects live on. Until it is connected, Deep Scans, AI chat, automations, cloning and even browsing for a working directory all have nowhere to run, and the app shows a persistent banner saying so.

The three-minute version

1. In the app, press Cmd-K (or Ctrl-K) and choose Install agent. The same dialog opens from the 🛰 Install agent button in the banner and in every empty state that needs an agent.
2. Click Generate install command. That creates a pairing token for your account and builds a single-line install command around it. Copy it with the copy button.
3. Run that command on the machine your code lives on. On macOS and Linux paste it into a terminal. On Windows, run the PowerShell command shown in the app instead.
4. Go back to the browser. Within a few seconds the banner disappears and the machine shows up as an agent host.

Treat the command as a secret while it is on your clipboard - the pairing token in it is what attaches that machine to your account. If you ever need to start over, generate a new one; the button turns into New token after the first click.

What the installer actually does

• Installs a background service so the agent starts on its own and survives reboots: a launchd agent on macOS, a systemd service on Linux (a system unit if you run it as root, otherwise a user unit), and the equivalent background service on Windows.
• Connects outward. The agent dials Heygents; Heygents never dials your machine. There is no inbound port to open and no firewall or router change to make.
• Runs the AI tools locally. Claude, Codex and Gemini are launched on your machine, in your project's real folder, using the CLI logins already on that machine. It is OAuth-only: no provider API key is ever read, stored or written into the service, so Heygents can only ever spend a subscription you already pay for and can never quietly start billing a metered API.
• Reports host vitals - CPU, RAM, disk and uptime - which is what fills the stats in the header and on Home.

Before you run it

• Node 18 or newer on that machine. The installer stops with a clear error if node is not on the PATH.
• The CLI you intend to use, installed and logged in - claude, codex or gemini. The installer warns about any it cannot find and carries on; jobs for a missing or logged-out tool fail fast rather than falling back to a paid API key.
• On Linux, if you install the agent as your own user rather than as root, enable lingering for that user so the service also starts before you log in. The installer prints the exact command.

Upgrading, and using more than one machine

Re-running the same install command upgrades the agent - it downloads the current agent, rewrites the service definition and restarts it. That is the entire update story; there is nothing else to run.

You can pair as many machines as you like: generate a fresh command for each one and run it there. Each machine appears as its own agent host, and a project's agent host field decides which machine executes that project's work, so a laptop project and a server project can happily live side by side in the same Heygents.

Finding your way around

The app is one full-height shell: a navigation rail down the left, a slim utility header across the top, and the current view filling the rest.

The left nav rail

By default the rail is a narrow icon strip. A collapse/expand toggle at its foot widens it to show text labels next to every button and the full name of each project, and the choice is remembered between visits. From top to bottom the rail holds:

The project list is covered in detail in Projects & workspace.

The Home dashboard

Home is the default landing page and the answer to "what should I look at first today?". It opens with a time-of-day greeting and three quick-action pills - Ask AI, Add project and Automations - followed by four live mini-stats: number of projects, open tasks, live chats, and the CPU and uptime of your agent host.

Below that sit two cards:

• My Tasks - your projects ranked by how many open tasks each one has, so the noisiest project is at the top.
• Projects - the full list with a health dot per project, its open-task count, and live chat-activity badges, plus a "Create new project" tile.

Everything on Home is wired to real data. Clicking any row opens that project's workspace directly.

The utility header

The slim header stays pinned as any view scrolls, and carries the things you want visible at all times: host stats (CPU, RAM, disk, uptime - each clickable for an explanation and, where relevant, a fix), a Scan pill that force-refreshes host stats, AI usage and task counts, an "Updated ..." freshness readout so you always know how old the numbers are, separate Claude and Codex usage bars, and a Hard refresh button.

When a project workspace is open, the header is tinted with that project's accent colour and shows the project name up front, so you can never lose track of which project you are acting on. On narrow screens the header reflows into two compact rows and the usage bars shrink to a coloured dot and a percentage.

The command palette

Press Cmd-K (or Ctrl-K) anywhere in the app, or click Commands in the rail, to open a keyboard-driven index of every top-level action: jump to any project including hidden ones, start a new chat, toggle the panels or the theme, refresh, and open each settings surface.

It is fully keyboard-operable with the arrow keys, Home, End, Enter and Escape, matches fuzzily so you rarely need the exact wording, and returns focus to wherever you were when you close it. If you learn one shortcut in Heygents, learn this one.

On a phone or tablet

At narrow widths - phones, portrait tablets and landscape phones - the app becomes a phone-style shell: the utility header on top, one full-screen view in the middle, and a bottom tab bar that swaps between Home, Projects, Chat and Detail. The nav rail becomes the Projects tab as a proper scrolling list, and a project switcher pill sits within thumb reach just above the tab bar so the active project is always one tap away.

Two tabs carry green "done" badges: Chat for runs that finished in the background but you have not opened yet, and Tasks for tasks solved in the last 24 hours.

Heygents is also an installable PWA. Add it to your home screen and it runs as its own app, and it can deliver web push notifications even while closed - for example when a run finishes or an agent is waiting for your approval. See Notifications & mobile.

Creating your first project

With an agent connected, use the Add button in the rail's project list, the Add project pill on Home, or the "Create new project" tile. The creation form asks for the minimum needed to make the project real:

1. Name - what you call it. This becomes the project's identity everywhere in the app.
2. Working directory - the path to the code on the agent machine. This is what AI runs and Deep Scans act on, so it matters more than anything else on the form. The folder browser asks your agent to list that machine's filesystem, which is another reason the agent has to be installed first.
3. Runtime location and agent host - where the project runs, and which of your paired machines executes agent work for it.
4. Repository and links - the repo and any live URLs, which also feed the health checks.

Once it exists, the standalone form is done with. Everything else is edited on the project's Info tab, which is always editable and auto-saves as you type - there is no separate edit screen to hunt for.

A good first hour

• Make sure the agent banner is gone. If it is still there, finish installing the agent before anything else - every step below needs it.
• Fill in the Goal on the Plan tab. One honest paragraph about what this project is for. The Deep Scan grounds its suggestions in it, so this is the highest-leverage text in the app.
• Point Readme and CLAUDE.md at the right files if they are not at the default paths.
• Run a Deep Scan from the Tasks tab and read what comes back before acting on any of it.
• Pick one task and hand it to an agent. Watch the run. That is the loop the whole product is built around.

Where to go next

• Projects & workspace - statuses, the Info / Plan / Tasks / Automations tabs, notes and files, health dots.
• Tasks & Deep Scan - how the task list is generated and how to work through it.
• AI chat, runs & terminal - dispatching agents and the in-browser terminal.
• Automations - scheduled scans, fixes and health checks.
• Settings, AI models & API keys - choosing providers and models.

Frequently asked questions

Do I need to install anything to use Heygents?

Yes, one thing: the companion agent, on the machine your code lives on. Heygents itself runs in a browser tab, but your repositories are not in that tab, so nothing real happens until an agent is connected. You generate a one-line install command inside the app, run it on your machine, and it installs a small background service that connects out to Heygents and runs Claude, Codex or Gemini locally in your project folders. Separately, and genuinely optionally, you can install Heygents itself as a progressive web app on your phone, which gives you a home-screen icon with no browser chrome and is what makes web push notifications possible on iPhone and iPad. Chrome and Edge can install it on desktop too.

How many projects should I add?

Add everything you genuinely maintain, including the quiet ones. Projects you have not touched in months are exactly the ones whose status you have lost track of, and you can set them to Paused or hide them so they stay out of your daily view without disappearing.

What happens if I close the tab during an AI run?

The run keeps going. It executes on your own machine under the companion agent and is streamed through Heygents, so the browser tab is only a viewer. Reopen the chat and the output is still there, and if push notifications are enabled you get told the moment it finishes. Navigating away, closing the tab, losing your connection or backgrounding the app on a phone never kills work that is already in progress. Putting the agent machine itself to sleep does, of course, stop it.

Can I use Heygents in light mode?

Yes. The appearance toggle in the Settings menu switches between the dark and light themes, and there is a matching entry in the command palette, so flipping it from either place keeps both in sync and the menu never shows the wrong state. The choice is remembered in your browser and applies immediately with no reload.