Generate Codebase-Aware AI Specs for Claude Code & Cursor – Shotgun CLI

Shotgun CLI is an open-source command-line tool for spec-driven development with AI coding agents such as Cursor, Claude Code, Codex, Antigravity, Windsurf, and Lovable.

It reads your codebase, turns a feature idea into a code-aware plan, and exports structured instructions that your AI coding agent can follow before it starts editing files.

If you use an AI coding agent like Cursor, Claude Code, Codex, or Lovable, you have probably seen code that looks plausible but misses the real project constraints. It may ignore an existing pattern, rebuild something already in the repo, or turn one feature request into a change that is too large to review.

Shotgun CLI handles the planning step before code generation. It indexes your repository, helps shape the requirement, maps the work into stages, and exports instructions that are easier to review before an AI agent edits code.

The useful part is the codebase context. Shotgun is a CLI and TUI for preparing specs, PR-style task plans, and agent-ready files. It is free and MIT licensed, but model calls still require OpenAI, Anthropic, Gemini, or Shotgun credits.

Features

• Codebase-aware specs: Shotgun reads your repository before it writes a plan, so the output can reflect existing files, dependencies, patterns, and architecture.
• Spec-driven development: It turns a feature idea into requirements, architecture notes, staged tasks, and exportable instructions for AI coding agents.
• Planning and Drafting modes: Planning mode asks for confirmation at checkpoints. Drafting mode runs the plan with fewer interruptions when you already trust the direction.
• Router-led planning flow: The TUI moves a request through research, specification, planning, task breakdown, and export phases.
• AI coding agent exports: Shotgun can prepare files and instructions for Cursor, Claude Code, Codex, Windsurf, Lovable, and similar agent-based coding tools.
• Local codebase indexing: Code indexing happens on your machine and stores its index under ~/.shotgun-sh/codebases/.
• Model provider setup: You can connect OpenAI, Anthropic, or Google Gemini. Shotgun also offers usage credits.
• Workspace sharing: Paid Shotgun plans can publish specs to a workspace for team review while your local .shotgun/ files stay unchanged.

Use Cases

• Adding features: Map a feature to the existing codebase before asking an AI agent to edit files.
• Refactoring: Inspect dependencies and plan smaller stages before changing shared code.
• Greenfield projects: Research architecture choices and turn an early idea into a buildable plan.
• Onboarding: Generate docs and implementation notes that match the actual repository.
• Migration planning: Compare the current system with the target state, then break the work into stages for your AI coding agent.

How to Use It

1. Install the prerequisites for your operating system. Shotgun uses uv for installation and supports Python 3.11 through 3.13. On Windows, use PowerShell and a regular x64 Windows PC.

2. On macOS, install uv with Homebrew or the Astral installer, then run Shotgun:

brew install uv
uvx shotgun-sh@latest

3. On Linux, install uv with the Astral shell installer, then run Shotgun:

curl -LsSf https://astral.sh/uv/install.sh | sh
uvx shotgun-sh@latest

4. On Windows, open PowerShell, install uv, update your PATH if needed, and run Shotgun with Python 3.12:

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
$env:Path = "C:\Users\$env:USERNAME\.local\bin;$env:Path"
uvx --python 3.12 shotgun-sh@latest

5. Launch Shotgun inside your project directory. The TUI guides you through codebase indexing, LLM setup, and your first planning request.

uvx shotgun-sh@latest

6. Use Planning mode when you want checkpoints before agents run steps that may affect files. Switch to Drafting mode when the plan is clear and you want Shotgun to run the full process in one pass.

7. Export the resulting spec or task plan to your AI coding agent. Shotgun can prepare output for tools such as Cursor, Claude Code, Windsurf, Lovable, and AGENTS.md-based workflows.

Pros

• Better agent instructions: The output gives your coding agent a clearer plan before it starts changing files.
• Repository context: Shotgun indexes the local codebase and can refer to existing structure instead of relying only on your prompt.
• More reviewable work: The staged plan breaks large AI coding changes into smaller steps.
• Private code indexing: The code index stays on your machine. LLM calls still require a model provider or Shotgun credits.
• Broad agent fit: Shotgun is built around common AI coding workflows, including Cursor, Claude Code, Codex, Windsurf, Lovable, and Antigravity.

Cons

• LLM access is still required: You need OpenAI, Anthropic, Gemini, or Shotgun credits for model calls.
• Local LLM support is not ready yet: The project lists local provider support as planned.
• Windows setup has extra steps: Windows users should run PowerShell, use x64 Windows, and may need the Visual C++ redistributable for code indexing.
• Workspace sharing is paid: Sharing specs to a team workspace is available on paid Shotgun plans.

Related Resources

• Cursor IDE: AI-powered code editor that can use structured specs exported from Shotgun.
• Claude Code documentation: Anthropic’s command-line coding agent, useful when you want to pass Shotgun’s planning output into a terminal coding workflow.
• Lovable platform: AI app builder that can use clearer component and architecture instructions from a spec.
• uv installation docs: The package manager used in Shotgun’s current install flow.
• Context7: Documentation lookup service for current library docs when you configure a Context7 API key.
• AI-powered CLI Tools: More free and open-source AI CLI tools on ScriptByAI.
• The Ultimate Claude Code Resource List: Agents, Skills, Plugins & More

FAQs

Q: Is Shotgun CLI free and open source?
A: Yes. Shotgun CLI is an open-source project with an MIT license. Model usage still needs your own OpenAI, Anthropic, or Gemini key, or Shotgun credits.

Q: How do I install Shotgun CLI?
A: The current install path uses uvx shotgun-sh@latest. macOS and Linux users can install uv first, then run that command. Windows users should run the PowerShell install steps and use uvx --python 3.12 shotgun-sh@latest.

Q: Does my code leave my computer when Shotgun indexes a repository?
A: No. Codebase indexing happens locally, and the index is stored under ~/.shotgun-sh/codebases/. LLM API calls still require an internet connection unless future local model support changes that setup.

Q: What AI coding tools does Shotgun work with?
A: Shotgun works with AI coding agents such as Cursor, Claude Code, Codex, Antigravity, Windsurf, and Lovable. It prepares specs and instructions for agent-based coding workflows.

Q: What are Planning and Drafting modes?
A: Planning mode shows steps and asks for confirmation before running agents that may affect files. Drafting mode runs the full plan with fewer prompts when you already know what you want Shotgun to do.

Q: Can teams collaborate on specifications created with Shotgun?
A: Yes, but workspace sharing is a paid Shotgun feature. It publishes a versioned snapshot of a spec to a workspace while your local .shotgun/ files stay unchanged.

Q: Does Shotgun collect analytics?
A: Shotgun gathers minimal anonymous events such as installs, server starts, and tool calls. It does not collect prompt or code content. PostHog is used for analytics and error reporting.

Last Updated: June 30, 2026