Managing Periodic Agent Tasks with HEARTBEAT.md

I often find myself worrying if my automated processes are actually doing what they should be. It is frustrating to manually refresh logs or check statuses every few minutes just to make sure nothing has stalled. I want a way to let the system handle those periodic check-ins for me so I can focus on writing code.

Using a heartbeat file helps solve this. It gives you a simple way to control how an agent checks its tasks without messing with complex configuration menus.

What You’ll Need

• A HEARTBEAT.md file in your project directory.
• An active agent configured to read this file.

Quick Start

You can manage your heartbeat settings in less than five minutes by editing a single file.

1. To skip heartbeat API calls: Keep your HEARTBEAT.md file empty. You can also include comments starting with # if you want to keep the file but avoid triggering the API.
2. To enable periodic checks: List the tasks you want the agent to perform directly in the file.

HEARTBEAT.md

# Keep this file empty (or with only comments) to skip heartbeat API calls.

# Add tasks below when you want the agent to check something periodically.
Check the status of the background worker
Verify that the latest logs are processed

Troubleshooting

The agent is making unwanted heartbeat API calls. Check your HEARTBEAT.md file. If there is any text that is not a comment, the agent will attempt to process it. To stop these calls, delete all task text or turn them into comments.

The agent is not performing periodic checks. Ensure that your tasks are written clearly below the comments in the HEARTBEAT.md file. If the file is empty, the agent will skip the heartbeat process entirely.

If you have more questions about setting this up, check out the AI Setup Assistant.

What’s Next

• Agent Configuration Guide
• Task Automation Basics