Docs / Using Heygents

Updated July 29, 2026 · ~8 min read

Automations

Automations are scheduled, autonomous AI runs with no human in the loop. A rule wakes up on its own schedule, opens your project on your own machine through the companion agent, and either audits it for new work or picks up a task and completes it. This page explains every automation kind, how to create and edit schedules, and where to read the results.

What an automation is

Everything you can do by hand in Heygents - run a Deep Scan, hand a task to the AI, check whether a site is up - can also run on a timer. An automation rule stores the instructions once, and Heygents' scheduler fires it whenever it comes due. You do not have to be at the keyboard, and you do not have to keep a browser tab open: runs are detached from the browser and execute on your agent machine, so they survive disconnects, refreshes, and navigation.

Each rule has a kind that is chosen up front and fixed for the life of the rule. When you edit a rule later, the kind is shown as a static label - if you want the other kind, create a new rule. Each kind carries its own colour through its rows and its tab, so a mixed list stays readable at a glance: Scan is sky blue, Fix is violet.

The All / Scan / Fix / Site Health categories

Automations are grouped into categories you switch between with tabs:

• All - the default view. Every rule of both kinds in one list, with a kind tag on each row. This tab offers both + New scan and + New auto-fix.
• Scan - only the scheduled Deep Scan rules that keep your task list fresh. One create button, for a scan.
• Fix - only the auto-fix rules that pick up open tasks and complete them. One create button, for an auto-fix.
• Site Health - the recurring health checks: how often Heygents re-probes each project's site, ports, and process status. This is the uptime and reachability side of automation rather than an AI run.

The top-level Automations page adds a fifth tab, Frequency, where you set how often Heygents re-measures project health and host metrics. Both intervals are server-owned settings, so changing them affects the whole Heygents, not just one project.

Two places to manage rules

Automations live on two screens, split by scope. Each project has its own Automations tab showing the rules that actually reach that project: its own single-project rules, plus any cross-project rules that include it, which appear read-only with a Global tag so you cannot edit a shared rule by accident. Disabled cross-project rules are hidden there entirely.

The Automations entry in the sidebar opens the top-level page. It is a standalone screen with no project header, and it lists only the cross-project rules, grouped by target: all-projects rules first, then multi-project rules.

Scan automations

A Scan rule runs a Deep Scan on a schedule to generate and refresh a project's task list. It uses exactly the same machinery as the manual Deep Scan button, so results land in the same place: the project's AI task list, tagged with the provider that produced them.

When you create a scan rule you choose:

• Areas - which categories to investigate. Leave it empty for a full all-areas deep scan, or tick specific areas to focus the audit.
• Provider and model - Claude, Codex, or Gemini, with an optional model override. Leave the model blank to use the signed-in account's default.
• Instructions - free-text guidance for the run.
• Frequency - how often it fires. New scan rules default to hourly.
• Audit brief - under View / customize, an optional custom brief that fully replaces Heygents' built-in audit instructions for this rule. Load built-in default fetches the current default, scoped to the areas you picked, so you can edit it as a starting point. An empty brief falls back to the default, and the machine-readable output contract is always appended automatically, so a custom brief cannot break task parsing.

A repeat scan is smart about what already exists: it re-checks previously reported tasks against its new findings and marks the genuinely fixed ones as completed, rather than piling duplicates onto your backlog.

Auto-fix automations

A Fix rule picks the single highest-priority matching open task and dispatches the AI in the project's real working directory to complete it. It watches one category, or Any, at or above a minimum urgency of high, medium, or low, and carries a free-text goal prompt plus a provider and optional model.

The important choice is what happens when the run finishes:

• Auto-mark completed (the default) - the task is marked done and labelled as auto-completed.
• Wait for my approval - the task parks in an awaiting approval state with Approve and Reject buttons. Approve marks it completed as a human completion; Reject sends it back to open.

If the run exits with an error, the task returns to open and the failure is recorded. Every finished fix run keeps its full transcript - the AI's notes and every tool it invoked - so the task card gets an AI run button that replays the whole run in a full-screen view, like reading back a chat. That button stays available even after you approve the task later.

Automation runs are given broad permissions so they can work unattended, but the fix prompt explicitly forbids pushing to git, deploying, restarting services, and committing unless you asked for it.

Targeting one project, several, or all

Every rule targets a single project, a hand-picked set of projects, or all projects. An all-projects rule fans out to every project that has a working directory and is neither hidden nor paused. A multi-project rule fans out to exactly the projects you chose, including paused or hidden ones, because you picked them deliberately.

Where you create the rule decides its scope. A rule for exactly one project is created from that project's own Automations tab. The multi-project and all-projects pickers live on the top-level Automations page; picking no projects there collapses to all projects, and picking one collapses to a single-project rule. If you later narrow a cross-project rule down to a single project, it becomes project-scoped and leaves the global page - Heygents tells you which project's Automations tab it moved to, so it never silently disappears.

Schedules, queueing, and quiet hours

The scheduler checks once a minute for rules that have come due. Frequencies can be as short as 5 minutes and as long as a week; new scan and fix rules both default to hourly.

When a rule fires, it expands into one job per target project and feeds a small serial queue - one scan and one fix at a time - so a global rule never launches a swarm of AI processes at once. The rule only reschedules once its entire fan-out has drained.

Scheduled scans also respect daytime hours: they dispatch between 08:00 and 21:59 Israel time, and a scan that becomes due overnight is deferred to the next morning window. Manual Run now ignores that restriction entirely, and ignores the enabled flag too, so you can always trigger a rule on demand.

Creating, editing, pausing, and deleting

Use the create button on the tab that matches the kind you want, or either button from the All tab. The form asks for the target, the provider, the schedule, and the kind-specific options described above, plus an Enabled toggle.

On each rule row you can enable or pause it with its toggle, edit it, delete it, or hit Run now. Pausing keeps the rule and its history intact and simply stops it firing; re-enabling re-arms the schedule from that moment.

Results and history

Every rule row shows its last run: when it happened and whether it succeeded. Expand the row for the full log - Heygents keeps the most recent 30 terminal runs per rule.

• Scan rules expand into a Previous scans log with each run's time and outcome, including the real reason for any failure rather than a generic error.
• Fix rules expand into a Tasks already fixed list, flattened across single-project and fan-out runs, and including tasks currently parked awaiting your approval.

Beyond the rule rows, results show up where you already work: new and updated tasks appear in the project's task list, fixed tasks flip to completed with their AI run transcript attached, and the project view keeps its own collapsible Scan history panel covering both manual and scheduled scans.

If Heygents restarts mid-run, the run is not lost from view. Interrupted scans are recorded as a visible, retryable interrupted state rather than vanishing, and the scheduler simply re-fires each rule when it next comes due.

Site Health and check frequency

The Site Health category covers the non-AI side of automation: Heygents periodically probes each project's website reachability, listening ports, and process status, and it samples host CPU, memory, disk, and uptime. Those readings power the status indicators across the dashboard.

Cadence is a setting rather than a fixed timer. Project health and host metrics each have their own interval, editable from the Frequency tab or alongside the Site Health settings, and both are clamped to sane bounds. You can also force an immediate re-measure at any time from the header's Scan button, or run a scoped Scan now for a single project from its own view. Note that these health checks are plain probes - they launch no AI agent and cost nothing.

Frequently asked questions

Can I change a scan rule into a fix rule?

No. The kind is fixed when the rule is created and is shown as a static label when you edit it, so if you want the other kind you create a new rule and delete the old one. Each kind carries its own colour through its rows and its tab - sky blue for Scan, violet for Fix - so a mixed list stays readable.

Will an automation push code or deploy?

No. Automation runs are given broad permissions so they can work unattended, but the fix prompt explicitly forbids pushing to git, deploying, restarting services, and committing unless you asked for it. Work that is meant to ship arrives as a pull request instead, and merging is always a human decision you make yourself.

Why did my scheduled scan not run overnight?

Scheduled scans respect daytime hours: they dispatch between 08:00 and 21:59 Israel time, and a scan that becomes due overnight is deferred to the next morning window. Manual Run now ignores that restriction entirely, and ignores the enabled flag too, so you can always trigger a rule on demand without waiting for its next schedule.

What happens if I close the browser mid-run?

Nothing. Automation runs are detached from your browser and keep going on your machine under the companion agent, and the results are waiting for you when you come back. If Heygents restarts mid-run, interrupted scans are recorded as a visible, retryable interrupted state rather than vanishing, and the scheduler simply re-fires each rule when it next comes due.