poorcoder

A collection of lightweight Bash scripts to enhance your coding workflow with AI assistance. These tools bridge the gap between web-based AI interfaces and your terminal, allowing you to leverage subscription-based LLMs (like Claude.ai or Grok) without disrupting your development process.

Overview

This repository contains four main tools:

1. context - Extracts code context from your project to send to an LLM
2. apply-md - Applies code changes from LLM's markdown response
3. git-context - Generates git context for AI-assisted commit messages
4. autocommit - Automatically creates AI-generated commit messages using git-context

Workflow

Here's how poorcoder fits into your development workflow:

Why poorcoder?

Unlike IDE-integrated solutions (Cursor, aider, Claude Code, etc.), poorcoder is designed to work with your existing web-based LLM subscriptions (~$20-30/month) while maintaining your terminal workflow.

Key benefits:

• Is more cost-effective than dedicated API usage (which can cost $100-500/month for heavy use)
• Leverages the polished UX of web/mobile LLM interfaces
• Preserves your terminal-based development workflow
• Follows Unix philosophy (small tools doing one thing well)

Installation

Standard Installation

Simply clone this repository and make the scripts executable:

git clone https://github.com/vgrichina/poorcoder.git
cd poorcoder
chmod +x context apply-md git-context autocommit

You can either use the scripts directly from this folder or add them to your PATH for global access.

Project-Specific Installation (Recommended)

For heavy usage, copy the scripts and prompts directory directly into your project:

# Clone the repository
git clone https://github.com/vgrichina/poorcoder.git
# Copy essential files to your project
cp poorcoder/{context,apply-md,git-context,autocommit} /path/to/your/project/
cp -r poorcoder/prompts /path/to/your/project/
# Make scripts executable
chmod +x /path/to/your/project/{context,apply-md,git-context,autocommit}

This approach lets you customize both the scripts and prompts for your specific project workflow. You can also create custom aliases or wrapper scripts, for example:

# Create a simple autocommit script
echo '#!/bin/bash
git commit -am "$(./git-context | llm -m openrouter/anthropic/claude-3.5-haiku)" -e' > autocommit
chmod +x autocommit

Scripts

Here's a detailed overview of each script in poorcoder:

1. context - Code Context Generator

Extracts relevant code context from your project to send to a web-based LLM.

# Basic usage with specific files
./context file1.js file2.js

# Copy context directly to clipboard (macOS)
./context --include="src/*.js" --exclude="*.test.js" | pbcopy

# Using direct patterns as arguments
./context "src/*.js" "README.md" | pbcopy

# Including git information
./context --include="src/*.js" --git | pbcopy

See full documentation for context

2. apply-md - Markdown Code Applier

Extracts code blocks from markdown (typically LLM responses) and applies changes to your filesystem.

# Basic usage with markdown input
cat response.md | ./apply-md

# Paste LLM response from clipboard (macOS)
pbpaste | ./apply-md --dry-run --verbose

# Apply changes and create missing files
pbpaste | ./apply-md --create-missing

See full documentation for apply-md

3. git-context - Git Context Generator

Generates git-related context to help LLMs create meaningful commit messages.

# Basic usage
./git-context

# Generate context, then use with API-based LLM via CLI tool
git commit -am "$(./git-context | llm -m openrouter/anthropic/claude-3.5-haiku)" -e

See full documentation for git-context

4. autocommit - Automated AI Commit Message Generator

Automatically creates commits with AI-generated commit messages using git-context.

# Basic usage - commits all changes with an AI-generated message
./autocommit

# The script opens an editor to allow you to review/edit the message before finalizing

The autocommit script is a simple wrapper that:

1. Uses git-context to gather information about your changes
2. Passes that context to an LLM via the llm CLI tool
3. Uses the generated message for a git commit
4. Opens your editor to let you review/edit the message before finalizing

This script requires the llm CLI tool to be installed and configured with an appropriate LLM model.

Component Interaction

The following diagram shows how the different components of poorcoder interact with each other and with external systems:

flowchart TB
    subgraph "Terminal Environment"
        context["context\n(Extract Code Context)"]
        applymd["apply-md\n(Apply Code Changes)"]
        gitcontext["git-context\n(Generate Git Info)"]
        autocommit["autocommit\n(AI Commit Messages)"]
        clipboard[("Clipboard\n(pbcopy/pbpaste)")]
        files[("Project Files")]
        git[("Git Repository")]
    end
    
    subgraph "Web Environment"
        llm["Web LLM\n(Claude.ai, Grok, etc.)"]
    end
    
    subgraph "Optional CLI"
        llmcli["LLM CLI Tool\n(e.g., llm, sgpt)"]
    end
    
    %% Connections for Web Workflow
    context -->|"Extract context"| files
    context -->|"Copy to clipboard"| clipboard
    clipboard -->|"Paste context"| llm
    llm -->|"Generate code"| clipboard
    clipboard -->|"Paste response"| applymd
    applymd -->|"Update files"| files
    
    %% Connections for Git workflow
    gitcontext -->|"Extract changes"| git
    gitcontext -->|"Generate context"| llmcli
    llmcli -->|"Generate message"| git
    
    %% Autocommit workflow
    autocommit -->|"Uses"| gitcontext
    autocommit -->|"Uses"| llmcli
    autocommit -->|"Commits to"| git
    
    %% Direct CLI workflow
    context -.->|"Direct pipe"| llmcli
    llmcli -.->|"Direct pipe"| applymd
    
    %% Styling
    classDef tool fill:#4b6584,stroke:#333,stroke-width:1px,color:white
    classDef storage fill:#f5cd79,stroke:#333,stroke-width:1px
    classDef external fill:#6a89cc,stroke:#333,stroke-width:1px,color:white
    classDef cli fill:#78e08f,stroke:#333,stroke-width:1px
    
    class context,applymd,gitcontext,autocommit tool
    class files,clipboard,git storage
    class llm external
    class llmcli cli

Loading

Usage Workflows

Dual Modality Approach

poorcoder supports two primary workflows:

1. Web UI LLM + Terminal

Ideal for complex interactions and leveraging your LLM subscription:

# 1. Generate context and copy to clipboard
./context --include="src/components/*.js" | pbcopy

# 2. Paste into web UI (Claude.ai, Grok, etc.), ask for changes

# 3. Copy response and apply changes
pbpaste | ./apply-md --create-missing

2. All-Terminal with CLI LLM

For quick operations or automation using LLM CLI tools:

# Generate commit message using LLM CLI
git commit -am "$(./git-context | llm -m openrouter/anthropic/claude-3.5-haiku)" -e

# Or use the autocommit script for a simpler workflow
./autocommit

# Fix a small issue directly in terminal
./context --include="src/buggy-file.js" | llm "Fix the null reference bug" | ./apply-md

Scenario: Bug Fix in a Complex Project

1. Gather relevant context:

   ./context --include="src/utils/validation.js" --include="src/components/Form.js" | pbcopy

2. Paste into Claude.ai or Grok with your request: "There's a bug where form validation fails when empty strings are submitted. Fix it while maintaining our validation approach."

3. Copy the AI's response and apply changes:

   pbpaste | ./apply-md --dry-run  # Preview changes
   pbpaste | ./apply-md            # Apply changes

4. Generate a commit message using autocommit:

   ./autocommit  # Automatically generates commit message and opens editor

Integration with Other Tools

poorcoder works with various tools to create a seamless workflow:

• Web LLMs: Claude.ai, ChatGPT, Grok, etc.
• LLM CLI tools: llm, sgpt, chatgpt-cli, etc.
• Clipboard utilities: pbcopy/pbpaste (macOS), xclip (Linux)
• Version control: git

Contributing

Contributions are welcome! Feel free to submit a pull request or open an issue to suggest improvements.

License

The Unlicense (public domain)