GitPost Maker

Local-first Python CLI application that automatically turns GitHub development activity into verified social media content.

---

1. Overview

GitPost Maker bridges software development activity and content creation. It inspects your GitHub repositories, analyzes Git commit history and diffs, generates a factually accurate Change Report, builds AI prompts, and produces ready-to-publish social media captions alongside non-AI, developer-focused social graphics generated programmatically with Pillow.

Core Philosophy

Git is the source of truth. The AI provider is never allowed to guess or invent what changed in a repository. Quantitative statistics, diffs, and commit records are extracted strictly from Git first, then transformed into engaging content.

---

2. Features

• GitHub Discovery: Discovers repositories via Scrapling / GitHub API with customizable activity filters.
• Git Analysis: Analyzes commits, changed files (added, modified, deleted, renamed), additions, deletions, and language distributions.
• Previous-State Comparison: Compares the start-of-day repository commit state with the end-of-day commit state.
• Structured Change Report: Generates validated Pydantic JSON reports (comparison.json) and human-readable Markdown (comparison.md).
• Fact-Based AI Captions: Integrates with OpenRouter / OpenAI API with fallback options, producing titles, captions, key changes, summaries, and hashtags.
• Programmatic Pillow Graphics: Renders high-resolution (1080x1080) developer-style PNG graphics (post.png) locally using bundled TTF fonts and code diff syntax views.
• Dated Output Package: Persists all generated assets into timestamped output folders (output/YYYY-MM-DD_HH-MM-SS_repo/).
• Interactive Rich CLI: Clean, interactive terminal interface powered by Typer and Rich.

---

3. Technology Stack

• Python: 3.11+
• GitPython: Local Git history and diff analysis
• Scrapling / HTTPX: Web scraping & GitHub API integration
• Pillow: Programmatic social post graphic creation
• Typer & Rich: Command line interface and formatted terminal output
• Pydantic v2: Data validation & schema serialization
• PyYAML & python-dotenv: Configuration & environment management

---

4. Installation

# Clone repository
git clone https://github.com/your-username/gitpost-maker.git
cd gitpost-maker

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

---

5. Configuration

1. Copy .env.example to .env and set your API keys:

   GITHUB_TOKEN=your_github_personal_access_token
   OPENROUTER_API_KEY=your_openrouter_api_key
   OPENAI_API_KEY=your_openai_api_key

2. Edit config.yaml to adjust preferences:

   github:
     username: "your-github-username"
     scrape_repositories: true
     activity_days: 7
   
   git:
     clone_directory: "./cache/repositories"
     fetch_before_analysis: true
   
   ai:
     provider: "openrouter" # openrouter, openai, or local fallback
     model: "openai/gpt-4o-mini"
   
   graphics:
     width: 1080
     height: 1080
     template: "developer_update"

---

6. Usage & Commands

Interactive Flow

Launch the main interactive workflow:

python main.py

Options & Subcommands

• Specific Date Analysis:

  python main.py --date 2026-09-01
  python main.py --yesterday

• List Discovered Repositories:

  python main.py repos

• Run Analysis Only (No AI):

  python main.py analyze repo-name --date today

• View Active Configuration:

  python main.py config

---

7. Output Directory Structure

Each run creates a timestamped output directory inside ./output:

output/
└── 2026-09-01_23-32-15_file-juggler/
    ├── post.png            # 1080x1080 PNG social graphic
    ├── caption.txt         # Social media caption text
    ├── title.txt           # Post title
    ├── hashtags.txt        # Recommended hashtags
    ├── comparison.json     # Factual structured Pydantic JSON report
    ├── comparison.md       # Human-readable Markdown change report
    ├── diff.patch          # Raw Git diff patch
    ├── diff-preview.txt    # Code diff preview excerpt
    └── prompt.txt          # Full AI prompt sent to provider

---

8. Architecture

                    ┌───────────────┐
                    │    GitHub     │
                    └───────┬───────┘
                            │
                       Scrapling
                            │
                            ▼
                 ┌─────────────────────┐
                 │ Repository Discovery│
                 └──────────┬──────────┘
                            │
                            ▼
                 ┌─────────────────────┐
                 │ Repository Selector │
                 └──────────┬──────────┘
                            │
                            ▼
                 ┌─────────────────────┐
                 │    Git Repository   │
                 └──────────┬──────────┘
                            │
                    Git history/diff
                            │
                            ▼
                 ┌─────────────────────┐
                 │ Change Analysis     │
                 └──────────┬──────────┘
                            │
                            ▼
                 ┌─────────────────────┐
                 │ Structured Report   │
                 └──────────┬──────────┘
                            │
                            ▼
                 ┌─────────────────────┐
                 │ Prompt Generator    │
                 └──────────┬──────────┘
                            │
                            ▼
                 ┌─────────────────────┐
                 │ AI Caption Generator│
                 └──────────┬──────────┘
                            │
                 ┌──────────┴──────────┐
                 ▼                     ▼
        ┌────────────────┐    ┌─────────────────┐
        │ caption.txt    │    │ Pillow Graphics │
        └────────────────┘    └────────┬────────┘
                                       │
                                       ▼
                              ┌─────────────────┐
                              │     post.png    │
                              └─────────────────┘

---

9. License

MIT License. See LICENSE for details.