A professional, modular, reliable, and secure automation toolkit and desktop GUI designed to maintain a consistent GitHub development workflow through structured, legitimate repository updates across multiple projects.
Responsible Automation Principle: The GitHub Activity Assistant is designed for transparent repository maintenance and controlled local automation. It creates legitimate, structured, and auditable repository updates (such as progress notes, changelogs, developer journals, task tracking, and test notes). It does NOT generate random meaningless noise solely to manipulate contribution graphs, and it never automatically pushes commits to GitHub without explicit user action.
- Phase 1 — GitHub Authentication & Foundation: Secure PyGithub connection using Personal Access Tokens, token masking, and repository access validation.
- Phase 2 — Multi-Repository Management: Support for managing multiple GitHub repositories simultaneously (configured for your 4 repositories).
- Phase 3 — Activity Planning & Content Engine: Controlled, truthful Markdown generators for 8 distinct activity types with duplicate prevention and content validation.
- Phase 4 — Git & Commit Engine: Safe subprocess Git execution with dirty working tree protection, diff inspection, automated commit author detection, and local commit creation without pushing.
- Phase 5 — Daily Scheduler & Controlled Automation: Visible foreground scheduler loop, timezone-aware next-run countdowns, interval pacing, duplicate-day protection, and interrupted run recovery.
- Phase 6 — Activity History, Monitoring & Dashboard: Resilient
HistoryStorewith corruption recovery, analyticalStatisticsEngine, terminal dashboard, ASCII activity calendar, and JSON/CSV report exporters. - Phase 7 — Desktop GUI & Final Integration: Modern, responsive PySide6 desktop interface with 8 modular views (Dashboard, Repositories, Activity, Scheduler, History, Logs, Reports, Settings), non-blocking background workers, dark/light themes, and PyInstaller Windows packaging
┌─────────────────────────┐
│ PySide6 GUI App │
│ (Desktop Interface) │
└────────────┬────────────┘
│
┌─────────────┴─────────────┐
│ │
┌──────▼──────┐ ┌──────▼──────┐
│ Phase 6 │ │ Phase 5 │
│ Monitoring │ │ Scheduler │
└──────┬──────┘ └──────┬──────┘
│ │
└─────────────┬─────────────┘
│
┌──────▼──────┐
│ Phase 3 │
│ Activity │
│ Planning │
└──────┬──────┘
│
┌──────▼──────┐
│ Phase 4 │
│ Git/Commit │
│ Engine │
└──────┬──────┘
│
┌─────────▼─────────┐
│ Local Git Repos │
└─────────┬─────────┘
│
┌──────▼──────┐
│ Phase 1 │
│ GitHub API │
└─────────────┘
github-activity-assistant/
│
├── app/
│ ├── __init__.py # Package exports & version (v1.0.0)
│ ├── config.py # Configuration loading, validation & monitoring options
│ ├── github_client.py # PyGithub client & RepositoryInfo data model
│ ├── repository_manager.py # Multi-repository orchestration layer
│ │
│ ├── activity/
│ │ ├── __init__.py # Activity package exports
│ │ ├── models.py # ActivityType enum, ActivityPlan & ValidationResult
│ │ ├── generators.py # Controlled, truthful content generators
│ │ ├── validator.py # Safety validator & credential scanner
│ │ ├── history.py # Local activity audit history manager
│ │ └── planner.py # ActivityPlanner multi-repo distribution engine
│ │
│ ├── git/
│ │ ├── __init__.py # Git package exports
│ │ ├── git_manager.py # Safe subprocess-based Git wrapper
│ │ └── commit_manager.py # Local workspace & commit creation engine
│ │
│ ├── scheduler/
│ │ ├── __init__.py # Scheduler package exports
│ │ ├── state.py # DailyState & SchedulerStateManager
│ │ ├── daily_runner.py # DailyRunner execution coordinator
│ │ └── scheduler.py # ActivityScheduler timer loop & signal handling
│ │
│ ├── logging/
│ │ ├── __init__.py # Logging package exports
│ │ └── activity_logger.py # Rotating file audit logger & secret filter
│ │
│ ├── monitoring/
│ │ ├── __init__.py # Monitoring package exports
│ │ ├── history_store.py # Resilient HistoryStore & ActivityRecord model
│ │ ├── statistics.py # StatisticsEngine metrics & analytics
│ │ ├── reports.py # JSON and CSV ReportGenerator
│ │ └── dashboard.py # TerminalDashboard & live watch loop
│ │
│ ├── gui/
│ │ ├── __init__.py # GUI package exports
│ │ ├── app.py # QApplication lifecycle runner
│ │ ├── main_window.py # MainWindow controller & sidebar navigation
│ │ ├── styles.py # Dark and Light QSS design system
│ │ ├── workers.py # Non-blocking QThread worker threads
│ │ ├── dialogs.py # Confirmation, diff preview, and setup dialogs
│ │ └── widgets/ # Modular page widgets
│ │ ├── dashboard_widget.py
│ │ ├── repositories_widget.py
│ │ ├── activity_widget.py
│ │ ├── scheduler_widget.py
│ │ ├── history_widget.py
│ │ ├── logs_widget.py
│ │ ├── reports_widget.py
│ │ └── settings_widget.py
│ │
│ └── main.py # Dual CLI & Desktop GUI entry point
│
├── build/
│ └── github_activity_assistant.spec # PyInstaller packaging specification
├── repositories/ # Local clones of managed repositories (Git-ignored)
├── data/ # Local activity audit history & state (Git-ignored)
│ ├── activity_history.json
│ └── scheduler_state.json
├── logs/ # Audit logs (Git-ignored)
│ └── assistant.log
├── reports/ # Generated audit reports (Git-ignored)
│
├── .env # Local developer secrets (Git-ignored)
├── .env.example # Template environment configuration
├── .gitignore # Version control ignore rules
├── requirements.txt # Project dependencies
├── README.md # Comprehensive documentation
└── LICENSE # MIT License
- Python: 3.11 or higher
- Git: 2.20 or higher installed and on system PATH
- GitHub Personal Access Token with
reposcope
# Windows PowerShell
cd github-activity-assistant
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txtCopy the template configuration file to .env:
Copy-Item .env.example .envEdit .env to configure your credentials and target repositories:
# GitHub Personal Access Token
GITHUB_TOKEN=ghp_your_actual_personal_access_token_here
# Target Repositories (comma-separated list)
GITHUB_REPOSITORIES=owner/repo1,owner/repo2,owner/repo3,owner/repo4
# Daily Activity Planning Target (1 to 20, default: 5)
DAILY_ACTIVITY_TARGET=5
# Local Repositories Storage Directory (default: ./repositories)
LOCAL_REPOSITORY_PATH=./repositories
# Daily Execution Schedule Time (24-hour HH:MM format, default: 18:00)
SCHEDULE_TIME=18:00
# Local Timezone (IANA timezone identifier, default: Asia/Kolkata)
TIMEZONE=Asia/Kolkata
# Whether automated daily schedule is enabled (true / false)
SCHEDULER_ENABLED=false
# Minimum interval between daily activities in minutes (default: 5)
MIN_ACTIVITY_INTERVAL_MINUTES=5
# Live Dashboard Auto-Refresh Interval in seconds (default: 5)
DASHBOARD_REFRESH_SECONDS=5
# Exported Reports Output Directory (default: ./reports)
REPORT_DIRECTORY=./reportsTo launch the graphical desktop interface:
python -m app.main --gui(Running python -m app.main without CLI flags will also automatically launch the Desktop GUI).
- Dashboard: Real-time progress bar, scheduler status, repository KPI cards, recent activity logs, and a 4-week graphical activity calendar.
- Repositories: Visual cards for configured repositories with branch, visibility, local path, and "Open Folder" explorer shortcut.
- Activity Planning: Plan generation table, diff preview modal, secret validation checks, and manual/dry-run execution buttons.
- Scheduler: Start, Pause, Resume, Stop, and Run Now controls with countdown timer and Dry-Run mode toggle.
- History: Searchable audit log table with date, repository, type, and status filters.
- Logs: Live streaming audit log viewer (
logs/assistant.log) with search and log-level filtering. - Reports: Date range selectors and one-click JSON and CSV report export.
- Settings: Secure configuration editor with masked token protection, timezone selectors, intervals, and dark/light theme switcher.
The assistant retains complete command-line automation and monitoring capabilities:
# 1. View visual terminal dashboard
python -m app.main --dashboard
# 2. Live auto-refreshing dashboard
python -m app.main --dashboard --watch
# 3. View statistical analytical summary
python -m app.main --stats
# 4. View scheduler state and today's progress
python -m app.main --status
# 5. Export JSON / CSV reports
python -m app.main --report --format json
python -m app.main --report --format csv
python -m app.main --report --format json --from 2026-08-01 --to 2026-08-19
# 6. Immediate daily execution
python -m app.main --run-now
python -m app.main --run-now --yes
python -m app.main --run-now --dry-run --yes
python -m app.main --run-now --target 3 --yes
# 7. Start foreground daily scheduler timer
python -m app.main --schedule
# 8. Resume an interrupted run
python -m app.main --resume-run --yesRun the full automated test suite:
$env:QT_QPA_PLATFORM="offscreen"
pytest -vAll 172 unit tests execute in complete isolation using temporary test fixtures, testing GitHub API client mocks, multi-repo management, activity generators, secret detection, Git staging, diff validation, scheduler loops, history persistence, statistics, report exports, and PySide6 GUI components.
To compile a standalone .exe using PyInstaller:
pyinstaller build/github_activity_assistant.specThe resulting executable will be created in dist/GitHubActivityAssistant/GitHubActivityAssistant.exe.
- Zero Destruction: The system strictly forbids destructive Git commands (
git reset --hard,git clean -fd,git push --force). - Secret Protection: Scans all proposed file content for PATs, API keys, passwords, and private keys before staging or committing.
- Credential Masking: Tokens are masked across representations, logs, reports, and UI inputs.
- Working Tree Safety: Commits are only made on clean working trees; existing uncommitted user files are never overwritten.
- Local Commits Only: All commits are created locally in
./repositories/for user inspection and are never automatically pushed. - Audit Trail: Every planned, executed, failed, or dry-run activity is recorded with timestamps and duration in
data/activity_history.jsonwith automatic backup recovery upon corruption.
This project is licensed under the MIT License.