Shotgun: Spec Generation for AI Coding Agents, Reviewed From the Repository
Spec Driven Development 🤠 Write codebase-aware specs for AI coding agents so they don't derail.
At a glance
- What is it?
- Shotgun is a Python CLI that indexes a repository, then walks a Research, Specify, Plan, Tasks, Export pipeline to produce staged, file-by-file specs for agents like Cursor and Claude Code. The premise is sound; the execution model, the LLM dependency and the indexing caveats are where adoption decisions actually get made.
- Who is it for?
- Adopt Shotgun if your team already runs Cursor, Claude Code, Codex or similar agents on multi-file features and keeps losing them halfway through, and you accept that spec quality is bounded by the LLM you configure in step two of onboarding. Skip it if you want a deterministic, offline planner, or if you cannot index the repository because the Windows code-indexing path needs the VC++ redistributable and Python 3.14 is unsupported.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 106 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The failure mode Shotgun is built around
The README states the problem in its own words: AI agents are good at small tasks but derail on big features, forgetting context, rebuilding what already exists, and going off-spec partway through. That is a workflow complaint, not a model complaint. The target user is an engineer who already has an agent in the loop and has watched it produce a large pull request that nobody wants to review. Shotgun's answer is to move the planning out of the agent session and into a separate CLI that reads the repository first, then emits a plan split into staged PRs with file-by-file instructions. The audience is narrow by design: people who run Cursor, Claude Code, Antigravity or Codex and want the agent to receive a bounded task instead of an open-ended feature request.
The Router pipeline: five sub-agents you do not select
The mechanism visible in the README is a Router that delegates to specialized sub-agents in a fixed order: Research, Specify, Plan, Tasks, Export. Research explores and understands the codebase, Specify defines requirements, Plan creates a roadmap, Tasks breaks that into steps, and Export formats the result for an AI agent. The documentation is explicit that you do not pick or manage these sub-agents; the Router handles them. The only execution controls exposed to the user are Planning and Drafting. In Planning, which is the default, Shotgun proposes an execution plan, shows each step, and asks for confirmation before running agents that change files. It also surfaces cascaded updates when one change affects other documents, and lets you confirm or skip them. Drafting runs the whole plan without intermediate prompts, with progress tracked internally but no per-step confirmation. Switching between the two is Shift+Tab, and the command palette opens with a forward slash.
Installation and the indexing step that gates everything
The install path is uv, not pip. On macOS the README offers brew install uv or the curl script from astral.sh, then uvx shotgun-sh@latest. Linux uses the same curl script and the same uvx command. Windows is the awkward platform: you set the execution policy with Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force, install uv through the PowerShell script, fix PATH, and then run uvx --python 3.12 shotgun-sh@latest. The supported matrix is Windows x64 with Python 3.11 to 3.13; 32-bit Python and Python 3.14 and above are listed as not supported because wheels are not available. Code indexing on Windows is optional and requires the Visual C++ redistributable, installed through a Start-BitsTransfer of vc_redist.x64.exe run as Administrator. The README also insists on PowerShell rather than Command Prompt or a VS Developer shell. On first launch the CLI walks through three steps: codebase indexing, which builds a searchable graph of the repository; LLM setup for OpenAI, Anthropic or Gemini; and a first research run. Note the ordering. Nothing useful happens until indexing succeeds and a model provider is configured.
Where the design creates real constraints
Two constraints follow directly from the material. First, the tool is a client for someone else's model. The README mentions BYOK or Shotgun credits at ten dollars per ten dollars of usage, and it publishes separate uptime monitors for the LLM proxy and the API. That means spec generation is a network operation against a third party, and the quality of the Research step depends on the provider you configure. A weak or cheap model produces a weak spec, and Shotgun has no visible fallback for that. Second, the codebase graph is built locally during onboarding, but the README does not describe an incremental re-index policy, staleness handling, or what happens when the graph no longer matches the working tree. If you generate specs against a stale index, the file-by-file instructions will point at code that has moved. Treat index freshness as an open question to test, not a documented guarantee. The Windows indexing caveat is the third constraint: on that platform the graph is optional, which undercuts the codebase-aware premise if you skip the redistributable.
Planning versus Drafting is the only meaningful dial
The two modes solve different problems and the README's own use-case column is honest about it. Planning is for control and visibility, with checkpoints and the ability to refine the plan before execution. Drafting is for speed when you already trust the plan. What is missing is any description of how the plan is revised once you reject a step, or whether a rejected step cascades back into the Specify stage. The README notes that cascaded updates are confirmed or skipped, which implies the dependency graph between documents exists, but not how it is computed. For a tool whose entire value proposition is keeping an agent on spec, the revision semantics matter more than the mode toggle. Until that is documented, the practical approach is to stay in Planning mode and treat Drafting as something you earn after watching the plan succeed a few times on the same repository.
How this differs from asking the agent to plan
The obvious alternative is the agent's own planning mode, which Cursor, Claude Code and Codex all ship. The difference in approach is where the context comes from. An agent plans inside a session, using whatever it has read so far, and its plan lives in that conversation. Shotgun plans outside the session, after building a persistent searchable graph of the repository, and exports the result as a document the agent then follows. That buys you a plan you can diff, review and hand to a different agent, and it separates the expensive repository reading from the code-writing step. It costs you a second tool, a second model configuration and a second failure surface. If your features are small enough that a session-scoped plan survives to the end, the agent's built-in planner is simpler and has no install step. Shotgun earns its place when the feature is large enough that context loss is the dominant failure.
Maintenance, licence and what to verify first
The project is MIT licensed, which permits commercial use and modification, though the README does not discuss what happens to generated specs or whether the hosted proxy and credits system carry separate terms. That distinction matters if you route through Shotgun credits rather than your own API key: the CLI is open source, the proxy is a service. On maintenance, the release history shows 0.13.0 in April 2026 preceded by two dev releases, with the repository last pushed in June 2026, so the project is active but still pre-1.0. Pre-1.0 means the Router stages, the TUI shortcuts and the configuration surface can change between minor versions, and your spec-generation workflow may need adjusting on upgrade. The install path through uvx shotgun-sh@latest always pulls the newest release, which is convenient and also means you get breaking changes without asking. Pin the version in any scripted or CI use. Before adopting, verify three things against your own repository: that indexing completes on your platform and Python version, that the Research stage produces a spec that names files you recognise, and that the exported format is something your agent actually consumes without manual editing.
Editorial conclusion
Adopt Shotgun if your team already runs Cursor, Claude Code, Codex or similar agents on multi-file features and keeps losing them halfway through, and you accept that spec quality is bounded by the LLM you configure in step two of onboarding. Skip it if you want a deterministic, offline planner, or if you cannot index the repository because the Windows code-indexing path needs the VC++ redistributable and Python 3.14 is unsupported. Before committing, run uvx shotgun-sh@latest against one real repository and read the generated spec for a feature you already shipped: that is the only test that tells you whether the Router's Research step actually understood your code.
Community notes