Write codebase-aware specs for AI coding agents (Codex, Cursor, Claude Code) so they don't derail.
|
Shotgun is a CLI tool that generates codebase-aware specs for AI coding agents like Cursor, Claude Code, and Lovable. It reads your entire repository, researches how new features should fit your architecture, and produces technical specifications that keep AI agents on track—so they build what you actually want instead of derailing halfway through. Bring your own key (BYOK) or use a Shotgun subscription — $10 for $10 in usage. It includes research on existing patterns, implementation plans that respect your architecture, and task breakdowns ready to export as AGENTS.md files. Each spec is complete enough that your AI agent can work longer and further without losing context or creating conflicts.
|
Shotgun runs via uvx or uv tool install. First, install uv for your platform:
| Platform | Installation Command |
|---|---|
| macOS (Homebrew) |
brew install uv |
| macOS/Linux (curl) |
curl -LsSf https://astral.sh/uv/install.sh | sh |
| Windows (PowerShell) |
powershell -c "irm https://astral.sh/uv/install.ps1 | iex" |
💡 Restart your terminal after installation
| 🚀 Try It Out (Ephemeral) | ⚡ Regular Use (Permanent) |
|---|---|
|
Best for: Testing Shotgun first uvx shotgun-sh@latest No installation needed, runs immediately |
Best for: Daily use uv tool install shotgun-sh Then run anywhere: |
Why uv? It's 10-100x faster than pip and handles binary wheels reliably—no cmake/build tool errors.
When you launch Shotgun, it will guide you through:
| Step | What Happens |
|---|---|
| 1. Codebase Indexing | Builds a searchable graph of your entire repository |
| 2. LLM Setup | Configure OpenAI, Anthropic, or Gemini |
| 3. First Research | Start generating codebase-aware specs |
💡 Pro tip: Run Shotgun in your IDE's terminal for the best experience.
Warning
Upgrading from alpha? Uninstall the old version first:
npm uninstall -g @proofs-io/shotgun @proofs-io/shotgun-server
Click the image above to watch the full demo on YouTube
Shotgun's Terminal UI guides you through 5 specialized modes — from research to export. Each mode has a dedicated AI agent optimized for that phase.
| Already Installed | First Time / Try It Out |
|---|---|
shotgun |
uvx shotgun-sh@latest |
The TUI opens automatically. Press Shift+Tab to switch modes or Ctrl+P for the command palette.
| 🔬 Research Explore & understand |
→ | 📝 Specify Define requirements |
→ | 📋 Plan Create roadmap |
→ | ✅ Tasks Break into steps |
→ | 📤 Export Format for AI |
Each phase builds on the previous one, creating a complete specification ready for AI coding agents.
| Mode | What It Does | Example Prompt | Output |
|---|---|---|---|
| 🔬 Research | Searches codebase + web, identifies patterns | How do we handle authentication in this codebase? |
research.md |
| 📝 Specify | Creates technical specs aware of architecture | Add OAuth2 authentication with refresh token support |
specification.md |
| 📋 Plan | Generates implementation roadmap | Create an implementation plan for the payment system |
plan.md |
| ✅ Tasks | Breaks plans into actionable items | Break down the user dashboard plan into tasks |
tasks.md |
| 📤 Export | Formats for AI coding agents | Export everything to AGENTS.md |
AGENTS.md |
Mode switching: Shift+Tab cycles through modes
Visual status: See current mode and progress at bottom
| Shortcut | Action |
|---|---|
Shift+Tab |
Switch modes |
Ctrl+P |
Open command palette |
Ctrl+C |
Cancel operation |
Escape |
Exit Q&A / stop agent |
Ctrl+U |
View usage stats |
| Do This | Not This |
|---|---|
✅ Research how we handle auth |
❌ Jump straight to building |
✅ Shotgun please ask me questions first |
❌ Assume Shotgun knows your needs |
✅ I'm working on payments, need refunds |
❌ Add refunds (no context) |
| ✅ Follow Research → Specify → Plan → Tasks | ❌ Skip phases |
Result: Your AI coding agent gets complete context—what exists, why, and what to build.
Note: CLI available in docs/CLI.md, but TUI is recommended.
| Feature | Shotgun | Other Tools |
|---|---|---|
| Codebase Understanding | Reads your entire repository before generating specs. Finds existing patterns, dependencies, and architecture. | Require manual context or search each time. No persistent understanding of your codebase structure. |
| Research Phase | Starts with research—discovers what you already have AND what exists externally before writing anything. | Start at specification. Build first, discover problems later. |
| Dedicated Agents Per Mode | Each mode (research, spec, plan, tasks, export) uses a separate specialized agent with prompts tailored specifically for that phase. 100% user-controllable via mode switching. | Single-agent or one-size-fits-all prompts. |
| Structured Workflow | 5-phase journey with checkpoints: Research → Spec → Plan → Tasks → Export | No structure. Just "prompt and hope." |
| Export Formats |
AGENTS.md files ready for Cursor, Claude Code, Windsurf, Lovable—your choice of tool.
|
Locked into specific IDE or coding agent. |
We had to implement payments. Cursor, Claude Code, and Copilot all suggested building a custom payment proxy — 3-4 weeks of development.
⭐ Shotgun's research found LiteLLM Proxy instead—30 minutes to discover, 5 days to deploy, first customer in 14 hours.
80% less dev time. Near-zero technical debt.
- 🚀 Onboarding - New developer? Shotgun maps your entire architecture and generates docs that actually match the code
- 🔧 Refactoring - Understand all dependencies before touching anything. Keep your refactor from becoming a rewrite
- 🌱 Greenfield Projects - Research existing solutions globally before writing line one
- ➕ Adding Features - Know exactly where your feature fits. Prevent duplicate functionality
- 📦 Migration - Map the old, plan the new, track the delta. Break migration into safe stages
📚 Want to see a detailed example? Check out our Case Study showing Shotgun in action on a real-world project.
Q: Does Shotgun collect any stats or data?
A: We only gather minimal, anonymous events (e.g., install, server start, tool call). We don't collect the content itself—only that an event occurred. We use Sentry for error reporting to improve stability.
Q: Does my code leave my computer when indexing?
A: No. When you index your codebase, all indexing happens locally on your machine. The index is stored in ~/.shotgun-sh/codebases/ and never sent to any server. Your code stays on your computer.
Q: Local LLMs?
A: Planned. We'll publish compatibility notes and local provider integrations.
Q: What LLM providers are supported?
A: Currently OpenAI, Anthropic (Claude), and Google Gemini. Local LLM support is on the roadmap.
Q: Can I use Shotgun offline?
A: You need an internet connection for LLM API calls, but your codebase stays local.
Q: How does the code graph work?
A: Shotgun indexes your codebase using tree-sitter for accurate parsing and creates a searchable graph of your code structure, dependencies, and relationships.
Shotgun is open-source and we welcome contributions. Whether you're fixing bugs, proposing features, improving docs, or spreading the word—we'd love to have you as part of the community.
- Bug Report: Found an issue? Create a bug report
- Feature Request: Have an idea to make Shotgun better? Submit a feature request
- Documentation: See something missing in the docs? Request documentation
Not sure where to start? Join our Discord and we'll help you get started!
- Contributing Guide - Setup, workflow, and guidelines
- Git Hooks - Lefthook, trufflehog, and security scanning
- CI/CD - GitHub Actions and automated testing
- Observability - Telemetry, Logfire, and monitoring
- Docker - Container setup and deployment
Research → Specify → Plan → Tasks → Export — Five phases that give AI agents the full picture.
uvx shotgun-sh@latest
License: MIT | Python: 3.11+ | Homepage: shotgun.sh
uv tool uninstall shotgun-sh