文件内容
README.md
# 🚀 Agent Autonomy Kit
[](https://github.com/reflectt/agent-autonomy-kit)
[](https://opensource.org/licenses/MIT)
[](https://github.com/reflectt)
**Stop waiting for prompts. Keep working.**
Most AI agents sit idle between human messages. This kit turns your agent into a self-directed worker that continuously makes progress on meaningful tasks.
---
## The Problem
Agents waste tokens by waiting:
- Heartbeats check "anything need attention?" and reply `HEARTBEAT_OK`
- Team members sit idle until spawned
- Work stops when the human stops prompting
- Subscription limits (tokens/hour, tokens/day) go unused
## The Solution
A proactive work system:
1. **Task Queue** — Always have work ready to pull
2. **Proactive Heartbeat** — Do work, don't just check for work
3. **Team Coordination** — Agents communicate and hand off tasks
4. **Continuous Operation** — Work until limits hit, then sleep
---
## Core Concepts
### 1. The Task Queue
Instead of waiting for prompts, agents pull from a persistent task queue.
**Location:** `tasks/QUEUE.md` (or GitHub Projects)
```markdown
# Task Queue
## Ready (can be picked up)
- [ ] Research competitor X pricing
- [ ] Write blog post draft on memory systems
- [ ] Review and improve procedure docs
## In Progress
- [ ] @kai: Building autonomy skill
- [ ] @rhythm: Updating process docs
## Blocked
- [ ] Deploy to production (needs: Ryan's approval)
## Done Today
- [x] Memory system shipped
- [x] Team spawning documented
```
**Rules:**
- Any agent can pick up a "Ready" task
- Mark yourself when you start: `@agentname: task`
- Move to Done when complete
- Add new tasks as you discover them
### 2. Proactive Heartbeat
Transform heartbeat from "check for alerts" to "do meaningful work."
**HEARTBEAT.md template:**
```markdown
# Heartbeat Routine
## 1. Check for urgent items (30 seconds)
- Unread messages from human?
- Blocked tasks needing escalation?
- System health issues?
If urgent: handle immediately.
If not: continue to work mode.
## 2. Work Mode (use remaining time)
Pull from task queue:
1. Check `tasks/QUEUE.md` for Ready items
2. Pick the highest-priority task you can do
3. Do meaningful work on it
4. Update status when done or blocked
## 3. Before finishing
- Log what you did to daily memory
- Update task queue
- If task incomplete, note progress for next heartbeat
```
### 3. Team Coordination
Agents communicate through Discord (or configured channel):
- Progress updates
- Handoffs ("@rhythm this is ready for review")
- Blockers ("stuck on X, need help")
- Discoveries ("found interesting thing, adding to queue")
### 4. Token Budget Awareness
Know your limits, use them wisely:
```markdown
## Token Strategy
**Daily budget:** ~X tokens (Claude Max)
**Heartbeat cost:** ~2-5k tokens per run
**Runs available:** ~Y per day
**Priority:**
1. Human requests (always first)
2. Urgent tasks (time-sensitive)
3. High-impact tasks (move needles)
4. Maintenance tasks (improvements)
When approaching limits:
- Wrap up current task
- Write detailed handoff notes
- Sleep until reset
```
---
## Installation
### Git Clone (Recommended)
```bash
# Clone into your skills folder
git clone https://github.com/reflectt/agent-autonomy-kit.git skills/agent-autonomy-kit
```
Then follow the setup steps below.
---
## Setup
### 1. Create the task queue
```bash
mkdir -p tasks
cat > tasks/QUEUE.md << 'EOF'
# Task Queue
## Ready
<!-- Add tasks here that any agent can pick up -->
## In Progress
<!-- Tasks currently being worked on -->
## Blocked
<!-- Tasks waiting on something -->
## Done Today
<!-- Completed tasks (clear daily) -->
EOF
```
### 2. Update HEARTBEAT.md
Replace passive checking with proactive work:
```markdown
# Heartbeat Routine
## Quick Checks (if urgent, handle immediately)
- [ ] Human messages waiting?
- [ ] Critical blockers?
## Work Mode
1. Read `tasks/QUEUE.md`
2. Pick highest-priority Ready task
3. Do the work
4. Update queue and daily memory
5. If time remains, pick another task
## End of Heartbeat
- Log progress to `memory/YYYY-MM-DD.md`
- Post update to team channel if significant
```
### 3. Configure continuous operation
Set heartbeat to run frequently:
```json5
{
agents: {
defaults: {
heartbeat: {
every: "15m", // More frequent = more work done
target: "last",
activeHours: { start: "06:00", end: "23:00" }
}
}
}
}
```
### 4. Set up team channel (optional)
Configure Discord/Slack for team communication:
```json5
{
channels: {
discord: {
// ... existing config ...
groups: {
"team-reflectt": {
policy: "allow",
channels: ["team-chat-channel-id"]
}
}
}
}
}
```
---
## Workflow Example
### Morning (6:00 AM)
1. Heartbeat fires
2. Agent checks: no urgent human messages
3. Agent reads task queue: "Research competitor X pricing"
4. Agent does the research, writes findings
5. Agent updates queue: moves task to Done, adds follow-up tasks discovered
6. Agent posts to team channel: "Competitor research done, see tasks/competitor-analysis.md"
### Throughout the Day
- Heartbeat fires every 15-30 minutes
- Each time: check for urgent → do work → update queue → log progress
- Human messages always get priority
- Team coordinates via channel
### Evening (11:00 PM)
- Last heartbeat of active hours
- Agent wraps up current task
- Writes detailed notes for tomorrow
- Goes dormant until morning
---
## Anti-Patterns
❌ **Passive heartbeats** — "HEARTBEAT_OK" wastes the opportunity to work
❌ **No task queue** — Agents don't know what to work on
❌ **Solo operation** — No coordination means duplicated effort
❌ **Ignoring limits** — Getting rate-limited mid-task loses context
❌ **No handoff notes** — Next session starts from scratch
---
## Metrics to Track
In `memory/metrics.md`:
```markdown
# Autonomy Metrics
## This Week
- Tasks completed: X
- Heartbeats used productively: Y%
- Token utilization: Z%
- Human interventions needed: N
## Patterns
- Most productive hours: morning
- Common blockers: waiting for human approval
- Tasks that work well async: research, writing, code review
```
---
## Related Kits
This kit works best with its companions:
### [Agent Memory Kit](https://github.com/reflectt/agent-memory-kit)
**Required foundation.** Provides the memory system this kit builds on:
- Task progress logged to daily memory (episodic)
- Procedures for common tasks (procedural)
- Learnings added to MEMORY.md (semantic)
- Failures tracked in feedback.md (feedback loops)
### [Agent Team Kit](https://github.com/reflectt/agent-team-kit)
**For multi-agent setups.** Coordinates autonomous agents working together:
- Role-based work distribution
- Self-service task queues
- Team communication patterns
---
## Origin
Created by Team Reflectt after realizing their Claude Max subscription tokens were going unused. The agent would complete a task and wait for the next prompt, leaving hours of potential work on the table.
Now the team works continuously, coordinating via Discord, pulling from a shared task queue, and only sleeping when the token limits are reached.
---
## Cron Jobs for Autonomy
Set up automated reporting and work triggers:
### Daily Progress Report (10 PM)
```bash
openclaw cron add \
--name "Daily Progress Report" \
--cron "0 22 * * *" \
--tz "America/Vancouver" \
--session isolated \
--message "Generate daily progress report. Read tasks/QUEUE.md for completed tasks. Summarize: completed, in progress, blockers, tomorrow's plan."
```
### Morning Kickoff (7 AM)
```bash
openclaw cron add \
--name "Morning Kickoff" \
--cron "0 7 * * *" \
--tz "America/Vancouver" \
--session main \
--system-event "Morning kickoff: Review task queue, pick top priorities, spawn team members for parallel work." \
--wake now
```
### Overnight Work Check (3 AM)
```bash
openclaw cron add \
--name "Overnight Work" \
--cron "0 3 * * *" \
--tz "America/Vancouver" \
--session isolated \
--message "Overnight work session. Pull tasks from queue that don't need human input. Do research, writing, or analysis. Log progress."
```
These run automatically — no human prompt needed.
---
*Idle agents are wasted agents. Keep working.*