argus/README.md

Argus 👁️

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

Named after Argus Panoptes, the all-seeing giant of Greek mythology.

Features

• Notification triage — Pull, act, or dismiss GitHub notifications
• Activity logging — Track community actions
• Escalation management — Flag and track issues needing attention
• Dashboard — Visual overview via Datasette + static HTML
• Systemd service — Run in background

Quick Start

# Install
./scripts/install.sh

# Initialize database
argus init

# Set up authentication (choose one)
gh auth login                    # GitHub
export ARGUS_BACKEND=tea         # Forgejo (needs tea token with read:notification)

# Pull notifications
argus notif pull

# Check status
argus status

# Start dashboard
systemctl enable --now argus

Agent Integration

For AI agents using OpenClaw, add this to your HEARTBEAT.md for periodic community awareness:

### 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`

The install script outputs this block — just copy it to your HEARTBEAT.md.

Commands

Core

Command	Description
argus init	Create database
argus version	Show version
argus status	Summary overview

Notifications

Command	Description
argus notif pull [--backend gh|tea]	Fetch from GitHub/Forgejo
argus notif list [--pending]	List notifications
argus notif act <id> <action>	Mark as acted
argus notif dismiss <id> [reason]	Dismiss
argus notif audit	Auto-escalate stale

Activity

Command	Description
argus activity log <action> <detail>	Log action
argus activity list	Show recent

Escalations

Command	Description
argus escalate create --category --title	Create
argus escalate list [--status]	List
argus escalate ack <id>	Acknowledge
argus escalate resolve <id> --by --resolution	Resolve

Service

Command	Description
argus serve	Start Datasette + dashboard

Configuration

Environment variables:

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

Architecture

┌─────────────────────────────────────────────────┐
│                    argus CLI                     │
│  notif pull | activity log | escalate | serve   │
└─────────────────┬───────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────┐
│              ~/.argus/argus.db                  │
│   repos | issues | notifications | activity    │
└─────────────────┬───────────────────────────────┘
                  │
        ┌─────────┴─────────┐
        ▼                   ▼
┌───────────────┐   ┌───────────────┐
│   Dashboard   │   │   Datasette   │
│  :PORT (HTML) │   │ :PORT+1 (API) │
└───────────────┘   └───────────────┘

Default: Dashboard on 8100, Datasette on 8101. Set ARGUS_PORT to change base port.

Installation

Prerequisites

• Python 3.9+
• pip
• gh CLI (for GitHub integration)

Install

git clone https://forgejo.tail593e12.ts.net/Zeus/argus.git /opt/argus
cd /opt/argus && ./scripts/install.sh

Uninstall

/opt/argus/scripts/uninstall.sh

Systemd Service

systemctl enable argus   # Start on boot
systemctl start argus    # Start now
systemctl status argus   # Check status
journalctl -u argus -f   # View logs

License

MIT

Author

Zeus @ Olymp