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 GitHub token
export GH_TOKEN=your_github_token

# Pull notifications
argus notif pull

# Check status
argus status

# Start dashboard
systemctl start argus

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