argus/docs/SKILL.md

name	description
argus	GitHub/Forgejo community awareness tool. TRIGGERS: notifications, community triage, PR reviews, issue tracking, escalations, watch repos. Use when managing GitHub/Forgejo notifications, logging community actions, tracking escalations, or setting up community monitoring.

Argus Skill

CLI tool for GitHub/Forgejo community awareness — tracking notifications, logging activity, managing escalations.

Installation (For Agents)

If argus is not installed, run these steps:

Step 1: Install Argus

git clone https://forgejo.tail593e12.ts.net/Zeus/argus.git /opt/argus
cd /opt/argus && ./scripts/install.sh
ln -sf ~/.local/bin/datasette /usr/local/bin/datasette 2>/dev/null || true

Step 2: Create Forgejo Token

You need your Forgejo password. Check your git config:

grep -o 'https://[^:]*:[^@]*@' ~/.openclaw/workspace/.git/config | head -1

Then create a token with notification scope:

# Replace YOURNAME and YOURPASSWORD
curl -s -X POST "https://forgejo.tail593e12.ts.net/api/v1/users/YOURNAME/tokens" \
  -u "YOURNAME:YOURPASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"name":"argus","scopes":["read:notification","read:repository","write:repository"]}' | jq -r '.sha1'

Step 3: Configure Tea

mkdir -p ~/.config/tea
cat > ~/.config/tea/config.yml << EOF
logins:
  - name: olymp
    url: https://forgejo.tail593e12.ts.net
    token: TOKEN_FROM_STEP_2
    default: true
    user: YOURNAME
EOF

Step 4: Watch Repos & Test

# Watch repos you care about
argus repo watch owner/repo

# Test notification pull
argus notif pull --backend tea

# Check status
argus status

Step 5: Add to HEARTBEAT.md

Add this block to your HEARTBEAT.md:

### Argus Community Awareness (Daily)
1. **Check status**: `argus status`
2. **Pull notifications**: `argus notif pull`
3. **Review pending**: `argus notif list --pending --limit 5`
4. **Triage**: For each pending notification:
   - If actionable: `argus notif act <id> <action> "<detail>"`
   - If not relevant: `argus notif dismiss <id> "<reason>"`
5. **Audit stale**: `argus notif audit --stale-hours 48`
6. **Log activity**: Record significant actions with `argus activity log`
7. **Check escalations**: `argus escalate list --status open`

Step 6: Start Service (Optional)

systemctl enable --now argus

Dashboard: http://localhost:8100

---

Daily Usage

Once installed, use these commands:

Status

argus version           # Show version
argus status            # Summary: pending, activity, escalations

Repositories

argus repo list                    # List watched repos
argus repo watch <owner/repo>      # Subscribe to repo
argus repo unwatch <owner/repo>    # Unsubscribe from repo

Notifications

argus notif pull [--backend gh|tea]  # Fetch notifications
argus notif list [--pending]         # List notifications
argus notif act <id> <action>        # Mark as acted
argus notif dismiss <id> [reason]    # Dismiss
argus notif audit [--stale-hours]    # Auto-escalate stale

Activity Logging

argus activity log <action> <detail> [--issue ID]
argus activity list [--limit N]

Escalations

argus escalate create --category CAT --title "..."
argus escalate list [--status open]
argus escalate ack <id>
argus escalate resolve <id> --by WHO --resolution "..."

Environment Variables

Variable	Default	Description
ARGUS_DB	~/.argus/argus.db	Database path
ARGUS_PORT	8100	Dashboard port (datasette on port+1)
ARGUS_BACKEND	gh	Backend: gh (GitHub) or tea (Forgejo)

Triage Workflow

1. Pull: argus notif pull
2. Review: argus notif list --pending
3. For each notification:
   • Check the issue/PR (URL provided)
   • If actionable: argus notif act <id> reviewed "Added comment"
   • If not relevant: argus notif dismiss <id> "Not my area"
4. Audit: argus notif audit (escalates stale items)
5. Log: argus activity log triage "Processed 5 notifications"

---

Cron Jobs (Automated Auditing)

Set up cron jobs to automatically audit stale notifications twice daily.

Step 1: Add Cron Jobs

Use the OpenClaw cron tool to add these jobs:

Morning Audit (11:00 CET):

{
  "name": "argus-audit-morning",
  "schedule": {"kind": "cron", "expr": "0 10 * * *", "tz": "Europe/Berlin"},
  "payload": {
    "kind": "agentTurn",
    "message": "Run notification audit: ARGUS_BACKEND=tea argus notif audit --stale-hours 6. If escalations created, summarize them briefly."
  },
  "sessionTarget": "isolated",
  "delivery": {"mode": "announce"}
}

Afternoon Audit (15:00 CET):

{
  "name": "argus-audit-afternoon", 
  "schedule": {"kind": "cron", "expr": "0 14 * * *", "tz": "Europe/Berlin"},
  "payload": {
    "kind": "agentTurn",
    "message": "Run notification audit: ARGUS_BACKEND=tea argus notif audit --stale-hours 6. If escalations created, summarize them briefly."
  },
  "sessionTarget": "isolated",
  "delivery": {"mode": "announce"}
}

Step 2: Verify Cron Jobs

Check that the jobs are registered:

# Via cron tool
cron list

Expected output should show argus-audit-morning and argus-audit-afternoon.

What the Audit Does

• Checks all pending notifications older than 6 hours
• Creates escalations for stale items
• Reports summary back to your channel

Adjust --stale-hours based on your responsiveness requirements.