How abhishekmishragithub/codestory works
Project type and purpose
• This is a Python-based CLI tool (“codestory”) that generates clear, concise commit messages (and PR descriptions) by:
• Inspecting the user’s Git repository state (diffs, staged changes)
• Calling out to an LLM (configurable model) to draft messages
• Formatting the LLM output according to preset commit/PR templates (with optional emojis or detailed descriptions)
File structure
• Top-level files
• pyproject.toml / setup.py / requirements.txt – packaging / dependencies
• .env.example / config.py – environment / configuration management
• codestory/ package
• cli.py – entry point for the codestory command
• config.py – loads user preferences (model, flags, emojis)
• git_utils.py – gathers diffs, staged files, repo metadata
• llm_utils.py – handles API calls to the chosen LLM (e.g., OpenAI, Gemini)
• commit_formats.py – defines message/PR templates and applies styling
• debug_script.py – a self-serve debugging tool or dev sandbox
• tests/ – unit tests for git_utils and commit_formats modules
• thoughts/ – internal design notes
README for additional insights
• The “Architecture/Workflow” section shows a flowchart:
• User invokes CLI → config is loaded → git utilities collect context → LLM is called → formatted output is returned
• Environment variables and model selection can be overridden via CLI flags
a. Main components
1. CLI Layer
– codestory/cli.py
– Argument parsing (model, include-description, emoji flags)
2. Configuration Loader
– codestory/config.py
– Environment variables / .env file / defaults
3. Git Utility
– codestory/git_utils.py
– Staged changes, diffs, repo metadata
4. LLM Integration
– codestory/llm_utils.py
– API client, request/response handling, rate limiting
5. Message Formatter
– codestory/commit_formats.py
– Templates, emojis, detailed descriptions
6. Debug Module (optional)
– codestory/debug_script.py
– Local testing of flows without actual Git repo or API calls
7. External Services
– Git CLI / local repo
– LLM Provider API (OpenAI, Gemini, etc.)
b. Relationships & interactions
• User → CLI Layer
• CLI Layer → Configuration Loader → returns settings
• CLI Layer → Git Utility → retrieves diff/context
• CLI Layer → LLM Integration (with settings + context) → gets raw message
• CLI Layer → Message Formatter → final commit/PR text
• CLI Layer → Output (stdout or direct Git commit)
• Optional: Debug Module can bypass Git/LLM calls and work with canned data
c. Architectural patterns / design principles
– Single Responsibility: each module has a distinct role (config, git, LLM, formatting)
– Dependency Injection: CLI passes config into downstream modules
– Extensibility: supports multiple models, toggles (description, emoji)
– Testability: clear separation allows unit testing of git_utils and formatting
d. Key technologies / libraries
– Python 3.x, click or argparse (in cli.py)
– python-dotenv or built-in os.environ (config.py)
– subprocess or GitPython (git_utils.py)
– requests / official SDK (llm_utils.py)
– pytest (tests/)