g-draft ✦ AI-Powered Git Assistant

g-draft is a hybrid CLI + TUI developer tool that turbocharges your Git workflows using high-performance AI. It automates the "boring" parts of version control—like writing commit messages and PR descriptions—while providing expert-level security and performance audits before you even push your code.

🚀 Quick Usage

gdraft works as both a standalone CLI and an interactive TUI.

Interactive TUI (Recommended)

gdraft tui

CLI Mode

gdraft commit --copy   # Generate commit message & copy to clipboard
gdraft pr --copy       # Generate PR description & copy to clipboard
gdraft review          # Run AI code review on current changes

📚 Documentation

✨ Key Features

🤖 AI-Powered Workflow

  • Conventional Commits: Automatically generates structured, present-tense commit messages (≤ 72 chars) from your staged changes.
  • Context-Aware PRs: Generates detailed Pull Request descriptions. Automatically detects and fills your project's .github/pull_request_template.md.
  • Expert Code Review: Performs rigorous audits using internalized Skills for Security, Performance, and Clean Code.
  • Action-Aware Prompts: The AI is explicitly aware of the current task (commit vs. review), enabling targeted custom instructions like "For commits, include issue-ID".

🏎️ Instant Generations (Sub-2s)

  • Persistent Background Agent: Launches and warms up the AI process immediately on startup. No more waiting for "cold starts."
  • Zero Round-Trip Handshake: Uses pipelined ACP (Agent Client Protocol) to start processing prompts instantly.
  • Model Routing: Automatically routes tasks to the fastest models (like gemini-3-flash) for instant commit messages.
  • Parallel Data Loading: Fetches git diffs and prepares the AI pipeline concurrently.

🖥️ High-Performance TUI

  • Interactive Dashboard: A centralized hub to manage your branch status and AI actions.
  • Real-Time Reasoning: See the agent's "thoughts" and tool calls stream with a natural typing effect as they happen.
  • Auto-Scrolling Progress: The AGENT PROGRESS box automatically stays pinned to the latest reasoning steps.
  • Accept & Commit: Review AI suggestions, edit them manually in the TUI, and commit directly with one keystroke.
  • Browser-Standard Scrolling: Smooth scrollable areas with a visual scrollbar and full Vim Keybindings (j/k, g/G, ctrl+d/ctrl+u).

💾 Smart Data & Persistence

  • Global Storage: All logs and cache are moved out of your workspace and stored in ~/.gdraft/ to keep your repositories clean.
  • Project-Aware Cache: Returning to a screen? Your last generation is instantly loaded from the cache.
  • Staleness Detection: Automatically detects if your code has changed since the last AI generation and prompts for a refresh.
  • Audit Logs: Full prompt/response history stored as structured JSON in ~/.gdraft/projects/[id]/logs.

🚀 Installation

From NPM (Recommended)

Install gdraft globally:

npm install -g gdraft

Local Development Setup

g-draft uses pnpm for package management.

  1. Clone & Install:

    git clone https://github.com/Bobbyjsx/g-draft.git
cd g-draft
pnpm install

  2. Development: Run the TypeScript source directly:

    pnpm dev -- tui    # Launch the TUI
pnpm dev -- commit # CLI mode

  3. Build:

    pnpm build

🔌 AI Provider Setup

g-draft acts as an orchestrator for your local AI CLIs. Ensure at least one is installed and authenticated:

Verify detection:

gdraft providers

⚙️ Configuration

g-draft uses a hybrid configuration model:

  • Global Config: Managed via gdraft config set ... (stored in system config).
  • Project Config: Create a .gdraft.json in your repository for project-specific overrides.
{
  "baseBranch": "main",
  "provider": "claude"
}

⌨️ TUI Shortcuts

| Key | Action | | :--- | :--- | | ↑/↓ or j/k | Scroll content / Navigate menu | | Enter | Select / Save | | a | Accept & Commit (Commit Screen) | | e | Edit AI Output | | c | Copy to Clipboard | | r | Retry / Regenerate | | Esc | Back to Dashboard | | q | Quit |

📄 License

MIT © Bobbyjsx