A purely local asynchronous task management system. Uses the file system instead of a database, Git instead of cloud services, and Agents instead of manual follow-up.
Core Philosophy
When people are offline, the Agent is still working.
你(早上): "帮我研究一下 xxx"
↓
Agent 自动建 Issue → 排优先级 → 打标签
↓
白天每小时自动调度 → 判断派给哪个 Agent
↓
分析师/写手/探索者/临时工 → 各自执行
↓
完成 → 移入 .issues/closed/ → Git commit
↓
你(晚上): 看 closed/ 里的结果
Directory Structure
.issues/
├── open/ # 待处理的任务
│ └── 035-研究xxx方案.md
├── in-progress/ # 正在执行的任务
│ └── 034-写教程.md
├── closed/ # 已完成的任务
│ ├── 001-修复bug.md
│ └── 002-写文档.md
└── index.json # 索引(ID 计数器 + 全量记录)
Issue File Format
Each Issue is a Markdown file with YAML front matter:
---
id: 35
title: 研究 xxx 方案
priority: P1
labels: research, analysis
status: open
assignee: unassigned
created_at: 2026-02-21T10:00:00
updated_at: 2026-02-21T10:00:00
---
## 问题描述
具体描述任务内容...
## 期望结果
分析报告,包含方案对比...
Priority
| Priority | Meaning | Scheduling Frequency |
|---|---|---|
| P0 | Urgent | Handle immediately |
| P1 | Important | Next scheduling cycle |
| P2 | Normal | Handle in queue |
| P3 | Low | Whenever there's time |
Tags
Tags determine who the task is assigned to:
| Tag | Corresponding Agent | Specialty |
|---|---|---|
analysis, bug, performance |
Analyst | In-depth analysis, architecture design |
docs, writing |
Writer | Chinese writing, tutorials |
research, cleanup |
Explorer | Information collection, organization |
群聊, 社交 |
Social Agent | Group chat interaction |
How to Use
1. Create an Issue (CLI)
# 在 Skill 目录内运行
python3 scripts/manager.py create \
--title "研究 Peekaboo 集成方案" \
--body "调研 Peekaboo macOS 自动化框架,评估与 OpenClaw 的集成可能" \
--priority P1 \
--labels research analysis
2. Create an Issue (Agent natural language)
When the user states a task, the Agent should:
- Determine that this is a task that can be executed asynchronously
- Extract the title, priority, and tags
- Call
manager.py createto create the Issue - Confirm that creation succeeded
Example Conversation:
用户: "帮我研究一下 karry_viber 的 Accessibility Service 方案"
Agent: 已创建 Issue #36: 研究 karry_viber Accessibility Service 方案 [P1, research]
3. View Issues
# 列出所有 open Issues
python3 scripts/manager.py list --status open
# 查看单个 Issue
python3 scripts/manager.py show 35
# 按标签过滤
python3 scripts/manager.py list --labels research
4. Assign an Issue
python3 scripts/manager.py assign 35 analyst
5. Close an Issue
python3 scripts/manager.py close 35 --resolution "分析报告已生成,见 data/analysis.md"
Automation Components
Automatic Scheduling (hourly)
scripts/auto-dispatch.sh — cron runs hourly:
- Run the inspection system to scan for problems
- Broadcast all open Issues to matching Agents
- Trigger the main Agent to decide on work assignment
Scheduling Logic: The main Agent reads open Issues and, based on tags and priority, decides which sub-Agent to assign execution to. It is not rigid rule-based routing, but intelligent judgment.
Inspection System (twice a day)
scripts/inspector.py — Automatically discovers problems and creates Issues:
| Check Item | Description |
|---|---|
| not-implemented stubs | Features not implemented in the code |
| Documentation Sync | Code changed but documentation was not updated |
| Unused Skills | Skills not modified for 30 days |
| MEMORY.md size | Over 10KB needs trimming |
| Meditation Output | Whether meditation was completed yesterday |
| Evolution Log | Whether there is a record in evolution-log |
Inspection finds problems → automatically creates an Issue → automatically assigns work for handling in the next scheduling cycle.
Documentation Sync Checker(extensible, refer to inspector.py 's check_docs_sync method):
- Automatically scan all Git projects and Skills
- Code was changed but README/SKILL.md was not updated
- New projects are automatically included in monitoring, no manual configuration required
Broadcast system
scripts/broadcast.py — Based on the Agent subscription configuration, push the Issue to matching Agents:
# Agent 订阅配置示例
AGENT_SUBSCRIPTIONS = {
"analyst": {
"labels": ["bug", "performance", "analysis"],
"priority": ["P0", "P1"]
},
"writer": {
"labels": ["docs", "writing"],
"priority": ["P1", "P2"]
}
}
Cron configuration example
# 每小时自动调度
0 * * * * cd /workspace && bash scripts/auto-dispatch.sh
# 早晨巡查(06:30)
30 6 * * * cd /workspace && python3 scripts/inspector.py
# 晚间巡查(22:00)
0 22 * * * cd /workspace && python3 scripts/inspector.py
In OpenClaw, use the built-in cron system instead of the system crontab:
sessionTarget: "isolated"+payload.kind: "agentTurn"For tasks that require Agent judgmentsessionTarget: "main"+payload.kind: "systemEvent"For simple triggers
Git management
The entire .issues/ directory is included in Git management:
# 每小时自动 commit
git add .issues/ && git commit -m "issues: auto-update $(date +%H:%M)" && git push
Benefits:
- Complete history is traceable (who created it, who changed it, when it was closed)
- Does not depend on any external services (GitHub Issues, Jira, Notion)
- Available offline, local speed
- Multi-device sync relies on git push/pull
Applicable scenarios
| Scenario | Approach |
|---|---|
| Office workers | Drop tasks in the morning → Agents run automatically during the day → Review results in the evening |
| Developers | The inspection system automatically discovers bugs → creates an Issue → Agent fixes it |
| Content creation | Create a "write tutorial" Issue → writer Agent generates a draft → human review |
| Research | Create a "research xxx" Issue → explorer collects materials → analyst produces a report |
Installation
- Copy the entire
async-issue-manager/directory to your workspace'sskills/directory - Create the
.issues/directory structure:mkdir -p .issues/{open,in-progress,closed} - Set the environment variable
WORKSPACEto point to your workspace root directory (or let the script detect it automatically) - Configure the cron scheduled task (refer to the Cron configuration above)
- Run
examples/quickstart.shto verify the installation
Notes
- Issue IDs increase globally and will not repeat
- The inspection system automatically deduplicates—Issues with the same title will not be created repeatedly
- File movement (open → in-progress → closed) is handled automatically by scripts
index.jsonis the index file; do not edit it manually