instaPostsForge

Built for photographers whose best shots stay stuck in the gallery.

One photo a day to Instagram, straight from a Google Drive folder or a Cloudflare R2 bucket, picked and captioned by AI agents (Claude, OpenAI, Gemini or Ollama Cloud), posted by GitHub Actions.

See the project page → · Use it yourself: setup guide →

Idea by Sritaj Kumar Patel · built with Claude

---

Why

Most photographers have a drive full of shots worth sharing and no time to share them. Posting well every day is a chore: pick a photo, avoid repeating last week, write something good, choose hashtags, remember to do it at the right time. instaPostsForge does that for you.

Drop your handpicked photos into a Google Drive folder, or a Cloudflare R2 bucket if you prefer. Every evening a GitHub Actions job picks one (or a small set from one outing), writes a short caption and hashtags with Claude (or OpenAI, Gemini or Ollama Cloud, if you prefer), checks everything in code, and posts it through the official Instagram API. It never asks for your Instagram password: you grant it an access token that you can revoke at any time. No server and no laptop needed.

The phone version is Postaday, which runs the same workflow on Android.

What it does

📁 Your photo folder	Put handpicked photos in one Google Drive folder or Cloudflare R2 bucket. Each new photo is described once and remembered.
🤖 AI picks and writes	Five AI agents describe each photo, choose today's, write the caption and hashtags, and review the post. Claude by default; OpenAI, Gemini or Ollama Cloud with one variable.
🖼️ Multi-photo posts	Some days it posts 2 to 5 photos from one outing or place as a carousel, all of one shape.
🛡️ Code has the last word	Every AI answer is checked by plain code against Instagram's limits and your content rules before anything is posted.
🙏 Writes with care	Short captions (at most 150 characters), playbooks per category and mood, and reverent captions for deities and festivals.
⏰ Posts on a schedule	Every day at your time on GitHub Actions, with check, plan and preview modes to look first.
✅ Never twice	Posted photos are recorded by their file ID and a visual fingerprint, and are never posted again.
💸 Know the cost	Every AI call is logged with its tokens and estimated cost, and each run saves a token audit report.
🔒 Safe in a public repo	Secrets live only in GitHub secrets, GPS is never saved, and published JPEGs carry no EXIF.

---

How it works

A day with instaPostsForge

flowchart LR
    A[📁 Drive folder or R2 bucket] --> B[Analyst<br/>describes new photos]
    B --> C[Planner<br/>picks today's photo or set]
    C --> D{Content rules<br/>in code}
    D -->|passes| E[Caption writer]
    D -->|fails| R[Random eligible photo]
    R --> E
    E --> F[Hashtag strategist]
    F --> G[Reviewer]
    G -->|faults the caption or tags| E
    G -->|approved| I[Prepare JPEG]
    G -->|false claim, bad quote<br/>or safety issue| X[Skip the day]
    I --> J[Stage on the media branch]
    J --> K[Instagram API]
    K -->|media ID| L[Record as posted]

This is the beginning of the README. Read the rest at the original. Read the full README ↗