---
title: Heartbeat — the Agent checks in by itself
nav: Heartbeat
summary: After a quiet spell Agent J wakes your main Agent to look at background work and your to-dos; it only speaks up when something needs you. Change how often and what it checks in one sentence.
order: 35
---
# Heartbeat — the Agent checks in by itself

An Agent only works when someone talks to it. If a background job fails at night or a task stops half-way, nobody notices
until you ask. Agent J therefore wakes your main Agent by itself: **after a quiet spell (default 60 minutes) the computer
sends it a heartbeat**, it looks around, and it only messages you when something needs you.

This works the same with Claude Code, Codex and OpenCode, in shared and independent mode. It comes from Agent J on your
computer, not from the cloud and not from a feature of one AI tool, so it also picks up work after a crash or a restart.

## What happens at a heartbeat

1. Nothing has happened for the interval: no message from you, no turn, no typing at the computer.
2. Agent J sends the main Agent one message starting with `〔Agent J 心跳〕` ("Agent J heartbeat") and the heartbeat
   prompt's short hash.
3. The Agent follows the heartbeat prompt: background sub-Agents, headless jobs and scheduled tasks, the newest run
   reports, your to-dos and anything it promised, work that died half-way.
4. All fine → it stays silent (no page, no notification). Something to tell you → a short message on the phone, labelled
   **Heartbeat check**.

A heartbeat never interrupts: it waits while the Agent works, while a message of yours is queued, while an approval card
is open, during a compaction, while everything is stopped, and in the nightly upgrade window (03:00–05:00). Talking to
the Agent simply moves the next heartbeat back.

## A fixed time every day

Besides waking after a quiet spell, the Agent can also wake once a day at a set time — say 7:30 every morning, so the
round is done by the time you get up. The time is your computer's local time.

If the Agent is busy at that moment, or it falls in the nightly upgrade window, the beat waits as usual but still happens
the same day, never the next. If the computer was off then and Agent J started more than an hour after it, that day is
skipped and the next day works as normal. A restart never gives you two daily beats on one day, and an idle beat that
happens right at that time counts as the day's beat, so you never get two in a row. The daily time follows the main
switch: after `agentj heartbeat off` it stays quiet too.

## Change it in one sentence

Tell the Agent, it runs the command and says "noted":

| You say | The Agent runs |
|---|---|
| "Check every 30 minutes from now on" | `agentj heartbeat set 30m` (5 minutes to 24 hours: `45m`, `2h`, `1d`) |
| "Stop waking up on a timer" | `agentj heartbeat off` (`on` to resume) |
| "Wake me up every morning at 7:30" | `agentj heartbeat daily 07:30` (`agentj heartbeat daily off` to stop) |
| "On each heartbeat also watch the backup job" | edits the heartbeat prompt |
| "How is the heartbeat set?" | `agentj heartbeat status` |

On the phone: **Settings → Heartbeat** has the same switch. "Wake up after being idle for" is a drop-down from 30 minutes
to 24 hours; "Custom…" lets you type 5 to 1440 minutes. Turn on "Also wake up every day at" and pick a time for one extra
beat a day. Changes apply at once.

## The heartbeat prompt

What the Agent does when it wakes is a short note on your computer:

```
~/.config/agentj/heartbeat.md
```

Agent J writes a default on first start. You or the Agent can change it (`agentj heartbeat prompt show`,
`agentj heartbeat prompt edit`, `agentj heartbeat prompt reset`). The Agent does not re-read an unchanged note every
time: each heartbeat carries the note's hash, and the full text comes along only when it changed, after a restart and
after a compaction. Never put a password or key in it — Agent J refuses text that looks like one.

## The quota steward: don't waste your quota

Subscription AI tools usually give a weekly quota over 7 days — about 14.3% a day on average. **Whenever the quota can be read, Agent J has a duty to tell you**: on a heartbeat it checks each AI tool's weekly and 5-hour quota by fixed rules, tells you what matters and, from your workflows and to-dos, suggests 1–3 big jobs you could hand over.

| Situation | The Agent says |
|---|---|
| More than a day behind the even pace | The quota will go to waste — give me more work |
| Second half of the week (3 days or less left) with plenty left | Proposes big jobs |
| An extra reset you recorded expires within 7 days | Says so early; more work this week, use the reset as soon as the quota runs out |
| Quota used up and a reset still available | Press the reset now |
| Weekly quota 90% or more used, no reset left | Warns you; names another AI account that still has room |
| The 5-hour window 80% used | A big job may be stopped by the server at any moment; if another AI account has room, suggests new work goes there |

Each kind of reminder comes at most once a day (the 5-hour warning once per 5-hour window); the morning brief carries it too. What can be read: Claude Code's own status-line quota data (needs `agentj config claude-statusline on`), Codex's own session logs, and OpenCode depending on the provider behind it — usually nothing. What cannot be read is shown as unknown, never guessed. No tool keeps extra resets locally: tell the Agent (I have one reset left, it expires on the 20th) and it records it with `agentj quota reset add claude --expires 2026-10-20`.

See it yourself: `agentj quota`. No quota reminders: tell the Agent stop the quota reminders (`agentj quota off`, `on` to resume).

**Hand new tasks to another AI account when quota runs low.** With more than one AI signed in on the computer (say Claude Code and Codex), once the current one's 5-hour quota reaches 80% or its weekly quota 90%, a newly starting scheduled task / workflow first does a handshake with another AI that still has room (a greeting it must really answer). If that works, by default your phone asks whether another AI should do this one and it only moves if you say yes — otherwise the same AI carries on. Turn on **Settings → Hand new tasks to another AI account when quota runs low** and it no longer asks: it moves, and the task's result says which AI ran it. The conversation you are having never moves (for that, `/switch-harness`); a workflow configured to use certain AI tools only moves among those tools.

**Out of quota? It picks up again by itself.** When a conversation or a workflow stops because the AI account's usage limit is used up, Agent J marks it and, once the reset time that AI reported has passed, sends one 「continue」 so the unfinished work gets done — once only. The chat shows a thin bar 「Quota used up · continues automatically at HH:MM」; tap ✕ to cancel. If you send a message yourself first, press Stop everything, or the Agent is busy, the 「continue」 is not sent. With the switch above on and another AI that still has room, a workflow carries on there at once; the conversation we are having never moves, but after you switch its AI yourself (`/switch-harness`) it continues at once. No reset time given, a momentary rate limit or an empty balance: nothing continues by itself, and the phone says so. The Agent can list and cancel them too: `agentj quota resume`.

## Cost

**Every heartbeat is one model call.** On a subscription it uses a little of your quota; with a pay-per-use key it costs
a little money. A longer interval (for example `agentj heartbeat set 4h`) or `agentj heartbeat off` costs less.

## If your AI tool has its own timer

Claude Code can schedule its own wake-ups (for example `/loop`). Both can run together: the Agent J heartbeat is the
safety net that works on every AI tool and still fires after the tool itself was closed and reopened.

## Report as background work ends

Agent J wakes the main Agent when background work ends; this is on by default. A busy Agent waits until its current turn finishes. Jobs ending within the same minute are grouped into a report. The Agent reads the actual reports and evidence first, then tells you the result in one or two sentences; it also says when a report is missing and investigates.

Completion notices work independently of the heartbeat: `agentj heartbeat off` leaves them on. Say “stop waking for completed background work” and the Agent runs `agentj config set background_done.enabled false`; use `true` to restore them. This works with Claude Code, Codex and OpenCode.