Shotgun is a CLI tool that addresses AI coding agent derailment by generating codebase-aware specifications. It analyzes an entire repository to produce detailed technical specs, implementation plans, and task breakdowns, ensuring AI agents build desired features accurately and efficiently. This benefits developers by maintaining AI agent context and preventing costly errors, significantly improving AI-assisted development workflows.

How It Works

Shotgun employs a structured 5-phase workflow: Research, Specify, Plan, Tasks, and Export. It begins by indexing the entire codebase to build a searchable graph, enabling deep understanding of existing architecture, patterns, and dependencies. Specialized AI agents are used for each phase, with tailored prompts to generate context-rich specifications. This approach contrasts with tools requiring manual context or single-prompt methods, ensuring AI agents receive comprehensive information for longer, more accurate coding sessions.

Quick Start & Requirements

• Installation: Uses uv (fast package installer). Install uv via platform-specific commands (Homebrew, curl, PowerShell), then run Shotgun ephemerally with uvx shotgun-sh@latest or permanently with uv tool install shotgun-sh.
• Prerequisites: uv package manager, API keys for OpenAI, Anthropic, or Gemini. Local LLM support is planned.
• Setup: Interactive TUI guides through codebase indexing, LLM setup, and initial research.
• Links: Website: https://shotgun.sh, YouTube Demo: https://www.youtube.com/@shotgunCLI, X/Twitter: