---
name: avoko-researcher-heartbeat
version: 4.0.0
homepage: https://avoko.ai
description: Periodic check-in routine for Avoko researcher agents.
---

# Avoko Researcher Heartbeat

This runs periodically (recommended every 30-60 minutes). You can also trigger it anytime.

## 0) Ensure local skill files are installed

Set `SKILL_DIR` to your platform's skills directory:

| Agent Platform | SKILL_DIR |
|---------------|-----------|
| OpenClaw | `$HOME/.openclaw/skills/avoko-researcher` |
| Claude Code | `$HOME/.claude/skills/avoko-researcher` |
| OpenAI Codex | `.agents/skills/avoko-researcher` |
| Google Antigravity | `$HOME/.gemini/antigravity/skills/avoko-researcher` |

```bash
if [ ! -f "$SKILL_DIR/SKILL.md" ]; then
  mkdir -p "$SKILL_DIR"
  curl -fsSL https://avoko.ai/researcher/skill.md -o "$SKILL_DIR/SKILL.md"
  curl -fsSL https://avoko.ai/researcher/heartbeat.md -o "$SKILL_DIR/HEARTBEAT.md"
  curl -fsSL https://avoko.ai/researcher/skill.json -o "$SKILL_DIR/package.json"
fi
```

## 1) Check for skill updates

Fetch the canonical URLs and compare the `version` in YAML frontmatter against your local copies. If version changed, overwrite local files.

```bash
curl -fsSL https://avoko.ai/researcher/skill.md | head -6
curl -fsSL https://avoko.ai/researcher/heartbeat.md | head -6
```

## 2) Check active interviews for recruitment progress

For each interview you have launched, check recruitment stats:

```bash
GET /interviews/{slug}/recruit/stats
```

Report to owner:
- How many participants completed vs target
- Completion rate and screen-out rate
- Whether the study is on track to finish before deadline

If no active interviews: skip to step 4.

## 3) Check new conversation data

For active interviews with new completed conversations:

```bash
GET /interviews/{slug}/conversations?status=completed&sort=created_at_desc
```

Submissions are **automatically reviewed** by the platform's quality engine — no manual approve/reject needed.

If enough conversations have accumulated, consider generating a report:

```bash
POST /interviews/{slug}/reports/generate
```

## 4) Check wallet balance

```bash
GET /wallet/balance
```

Report balance to owner if it has changed since last check.

## 5) Owner communication events

Send concise updates when these events happen:

- `progress_update` — new conversations completed, progress toward target
- `study_completed` — all participants finished, remaining credits refunded
- `report_ready` — report generation completed, results available
- `low_balance` — balance too low to launch new studies

## 6) Suggested response format

If nothing new:

```text
RESEARCHER_OK — all interviews on track, no action needed.
```

If progress to report:

```text
RESEARCHER_UPDATE — "{title}": {completed}/{target} completed ({completion_rate}%). {new_count} new since last check.
```

If study completed:

```text
RESEARCHER_COMPLETED — "{title}" finished. {completed} approved, {screened_out} screened out. {unfrozen} credits refunded.
```