文档Docs
心跳——Agent 自己醒来看一眼Heartbeat — the Agent checks in by itself
空闲一段时间后，Agent J 会叫醒你的主 Agent，看看后台任务和你的待办；只有需要你的时候才出声。多久看一次、看什么，一句话就能改。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.
Agent 只在有人跟它说话时才干活。后台任务半夜失败了、活干到一半停了，不问就没人知道。所以 Agent J 会自己叫醒主 Agent： 空闲满一段时间（默认 60 分钟），电脑就给它发一次心跳，它看一圈，只有需要你的事才发到手机上。
Claude Code、Codex、OpenCode 都一样，共享模式和独立模式都有。心跳由你电脑上的 Agent J 发出，不靠云端，也不靠某个 AI 工具自带的功能，所以电脑重启、程序崩溃以后，中途挂掉的活也能接着干。
心跳时会发生什么
- 空闲满了设定的时间：你没发消息，Agent 没在干活，电脑前也没人打字。
- Agent J 给主 Agent 发一条以
〔Agent J 心跳〕开头的消息，带上心跳提示的短哈希。 - Agent 按心跳提示去看：后台的子 Agent、headless 任务和定时任务，最新的运行报告，你的待办和它答应过的事，中途挂掉的活。
- 一切正常就不出声（手机上没有新页面，也没有提醒）；有事要告诉你，手机上会收到一条简短消息，标着心跳检查。
心跳不会打断你：Agent 正在干活、你的消息在排队、有审批卡片没处理、正在压缩、已经全部停下，或者在夜间升级时段（03:00–05:00），它都会等。你和 Agent 一聊天，下一次心跳就自动往后推。
每天固定时间唤醒
除了空闲满了才醒，还可以让 Agent 每天到点醒一次，比如每天早上 7:30 先看一圈，等你起床就能看到结果。时间按你电脑上的本地时间算。
到点时如果 Agent 正忙、或者在夜间升级时段，它照样会等，但当天一定补上，不会拖到第二天。电脑在那个时间关着、开机时已经过了一个多小时，这一天就跳过，第二天照常。电脑重启不会让同一天醒两次；到点前后刚好有一次空闲心跳的话，就算作当天这一次，不会连着醒两回。每天定时唤醒跟着心跳的总开关走：agentj heartbeat off 以后它也不再醒。
一句话就能改
跟 Agent 说一句，它会执行命令并回你「记下了」：
| 你说 | Agent 执行 |
|---|---|
| 「以后每 30 分钟看一次」 | agentj heartbeat set 30m（5 分钟到 24 小时：45m、2h、1d） |
| 「别再定时叫醒了」 | agentj heartbeat off（恢复用 on） |
| 「每天早上 7:30 叫醒你看一眼」 | agentj heartbeat daily 07:30（关掉用 agentj heartbeat daily off） |
| 「心跳的时候顺便盯着备份任务」 | 改心跳提示 |
| 「心跳现在怎么设置的」 | agentj heartbeat status |
手机上：设置 → 心跳，有同样的开关。「空闲多久后醒来」是一个下拉框，从 30 分钟到 24 小时；选「自定义…」可以自己填 5 到 1440 分钟。打开「每天固定时间唤醒」再选几点，就多一次每天定时的心跳。改好马上生效。
心跳提示
Agent 醒来做什么，写在你电脑上的一份短文档里：
~/.config/agentj/heartbeat.mdAgent J 第一次启动时会写好一份默认的。你或 Agent 都可以改（agentj heartbeat prompt show、agentj heartbeat prompt edit、agentj heartbeat prompt reset）。没改过的提示，Agent 不用每次重读：每次心跳都带着它的哈希，只有改过、电脑重启或者压缩以后，才会附上全文。不要在里面写密码或 key——看起来像密钥的内容 Agent J 会拒收。
额度管家：额度别浪费
订阅制的 AI 工具通常按 7 天给一份周额度，平均每天约 14.3%。只要查得到额度，Agent J 就有义务提醒你：心跳时它会按固定规则看一眼各个 AI 工具的周额度和 5 小时额度，有该说的就告诉你，并结合你的工作流和待办建议 1–3 件可以多派的大活。
| 情况 | Agent 会说 |
|---|---|
| 用得比均分线慢了一天以上 | 额度会浪费，可以多派点活 |
| 到了后半周（只剩 3 天以内），剩得还多 | 主动建议派大活 |
| 登记过的额外 reset 7 天内过期 | 尽早提醒；这周加大工作量，额度一见底就用掉它 |
| 额度见底，又还有 reset | 提醒你现在就按 reset |
| 周额度用到 90% 以上，又没有 reset | 提醒你；别的 AI 账号还有余量就点名 |
| 5 小时额度用到 80% | 大活随时可能被服务器直接终止；别的 AI 账号还有余量，就建议新活交给它 |
同一类提醒每天最多一次（5 小时预警每个 5 小时窗口一次），晨报里也会带上。能查到什么：Claude Code 读它自己给状态栏的额度数据（需要 agentj config claude-statusline on），Codex 读它自己会话记录里的额度数据，OpenCode 取决于背后的服务商，多半查不到。查不到的就标查不到，不猜。各家的额外 reset 都不在本地，你告诉 Agent 一声（我还有一次 reset，20 号过期），它会用 agentj quota reset add claude --expires 2026-10-20 记下来。
自己看：agentj quota。不想听额度提醒：跟 Agent 说别提醒额度了（agentj quota off，恢复用 on）。
额度告警时把新任务交给别的 AI 账号。 电脑上登录了不止一个 AI（比如 Claude Code 和 Codex）时，当前这个的 5 小时额度到 80% 或周额度到 90%，新开始的定时任务 / 工作流会先跟另一个额度还宽裕的 AI 握一次手（发一句问候、要它真回话）。能用的话：默认在手机上问你是否改用另一个 AI 来做，你同意才切，不同意就原来的 AI 接着干；在 设置 → 额度告警时把新任务交给其他 AI 账号 打开后就不问了，直接切，任务结果里写一句改用了谁。我们正在说话的这个主对话不会被切走（要换主对话的 AI 用 /switch-harness）；工作流限定了可用的 AI 时，只在它允许的几个 AI 里换。
额度用完了，到点自动接着做。 对话或工作流因为 AI 账号额度用完而停下时，Agent J 会记下它，等这个 AI 自己报的重置时间一到，自动发一句「继续」把没做完的做完——只续一次。手机聊天页上方会出现一条横条「额度用完，预计 HH:MM 自动继续」，点 ✕ 就取消。到点前你自己发了消息、按了全部停下，或者 Agent 正忙，这句「继续」就不发了。工作流在打开上面那个开关、又有别的 AI 额度宽裕时，会马上改用它接着跑；我们正在说话的主对话不会被切走，但你自己换了 AI（/switch-harness）之后它会立刻接着做。AI 没给重置时间、只是瞬时限流、或者是余额不足的，不会自动继续，手机上会说清楚。Agent 也能看和取消：agentj quota resume。
费用
每次心跳都会用掉一次模型调用。 订阅制会用掉一点额度，按量付费的 key 会花一点钱。间隔调长（比如 agentj heartbeat set 4h）或者 agentj heartbeat off 就更省。
AI 工具自己也有定时器的话
Claude Code 可以自己安排唤醒（比如 /loop）。两者可以同时用：Agent J 的心跳是兜底，任何 AI 工具都有，工具关掉再打开以后照样会来。
后台活结束就汇报
后台活结束时，Agent J 会主动叫醒主 Agent，默认开启。主 Agent 正忙就等这一轮结束；一分钟内接连结束的活合并汇报。Agent 先读实际报告与证据，再用一两句话告诉你结果，报告缺失也会说明并追查。
这条完成提示不依赖心跳，agentj heartbeat off 不会关闭它。要关闭，告诉 Agent 后台活结束不用叫醒它，它执行 agentj config set background_done.enabled false；恢复用 true。Claude Code、Codex 和 OpenCode 都适用。
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
- Nothing has happened for the interval: no message from you, no turn, no typing at the computer.
- Agent J sends the main Agent one message starting with
〔Agent J 心跳〕("Agent J heartbeat") and the heartbeat prompt's short hash. - 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.
- 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.mdAgent 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.