drooph0904/post-agent

1. What this repo is

- devpost is a Python CLI package that turns recent Git activity into publication-ready social posts.

- Its core job is to gather local project context, detect which commits are new, ask Claude to draft content, then either post to Reddit and copy a tweet to the clipboard or stop for user review.

2. Primary entrypoint and commands

- devpost/main.py is the command boundary for the whole system.

- The CLI supports operational modes like setup, init, run, status, reset, plus run-time flags such as --dry-run and --force.

- This is the top-level orchestration layer that decides which subsystems participate in each command.

3. Repository-local inputs

- Two local files shape behavior: .env for credentials/configuration and project_context.md for project-specific grounding text.

- project_context.example.md and .env.example show the expected inputs and indicate that the tool is meant to be initialized per project.

4. Commit discovery boundary

- devpost/git_reader.py isolates all interaction with the local Git repository.

- Its role is to fetch commits in the correct time/hash window, depending on whether the run is using post-log state or a forced time-based window.

- This module is the source of truth for “what changed since last post.”

5. Persistent memory between runs

- devpost/post_log.py stores which commits have already been published.

- This is the main stateful boundary in the system and what makes repeated runs idempotent.

- The README describes both hash-based incremental mode and a fallback 24-hour mode, so the log is central to deciding whether there is anything new to publish.

6. Agent orchestration and context injection

- devpost/agent.py is the central coordinator.

- It combines commit data, persisted post-log state, and project context, then feeds that into Claude to generate output.

- The README explicitly calls out context injection, tool orchestration, human-in-the-loop approval, and conditional tool selection as patterns implemented here.

7. Generation and validation

- devpost/tweet_builder.py handles tweet creation and the self-correction loop described in the README.

- This module appears responsible for enforcing output validity before downstream publishing, rather than trusting raw model output.

- That makes it a quality gate between LLM generation and any external side effect.

8. Publishing adapters

- devpost/reddit_poster.py is the external publishing boundary for Reddit.

- The README says the system creates content for 6 subreddits and a tweet, which implies this module adapts one generated content set into multiple Reddit-specific posts.

- Tweet delivery is handled differently: it is copied to the clipboard rather than directly posted, which keeps the Twitter/X step human-mediated.

9. Human review and presentation

- devpost/display.py is the user-facing preview layer.

- It appears to render the generated posts for approval before any external actions occur.

- This creates a clear human-in-the-loop boundary: the agent prepares content, the user approves it, and only then do side effects happen.

10. Configuration and setup

- devpost/config.py centralizes runtime configuration such as API keys, paths, and per-project settings.

- devpost/__init__.py and the packaging files suggest this is distributed as an installable CLI rather than a library.

- Setup/init flows likely create or validate the per-project context and environment needed for later runs.

11. End-to-end data flow

- The typical run is: CLI command → config load → post-log check → Git commit retrieval → project context injection → Claude generation → tweet validation → preview/approval → Reddit publishing + tweet clipboard copy → post-log update.

- The key architectural idea is that external side effects happen only after the content has been grounded in real commits and reviewed by a human.

12. Testing boundaries

- The tests/ folder mirrors the main subsystems: config, git reading, agent flow, post log, tweet building, Reddit posting, and CLI behavior.

- That suggests the codebase is organized around clear seams, with unit tests validating each adapter and orchestration step independently.