shotgun - Moses Yebei

The Problem

AI coding agents often lose context when asked to implement multi‑file features, producing large, unfocused pull requests that require extensive manual cleanup. Shotgun attempts to keep the agent on‑track by ingesting the whole repository, planning a staged rollout, and emitting precise, file‑by‑file instructions.

What This Does

The core logic lives under src/shotgun/. The CLI entry point src/shotgun/main.py parses commands and hands off to the run routine in src/shotgun/cli/run.py, which orchestrates the autopilot pipeline (src/shotgun/agents/autopilot/*). Specs are modelled in src/shotgun/agents/config/models.py and turned into concrete actions by the router (src/shotgun/agents/router/router.py).

File‑system and code‑base interactions are encapsulated in src/shotgun/codebase/core/manager.py and the various tool modules (e.g., src/shotgun/agents/tools/codebase/*). Test suites in test/ validate each component, while the evals/ package provides deterministic evaluation of generated PRs.

How It Is Wired

Execution starts at src/shotgun/main.py:109 (main). It creates a ConfigManager (called 108 times) and then invokes run (src/shotgun/cli/run.py:28), which reaches 351 functions. The most‑used internal symbols are:

exists – referenced from 128 locations.
ConfigManager – 108 callers.
track_event – 52 callers.

run eventually calls ParallelExecutor (42 callers) to launch stages. Each stage is rendered by src/shotgun/tui/app.py (the TUI entry point) and ultimately triggers filesystem writes via write_report (e.g., main → write_report → Path.parent.mkdir).

The codebase manager (src/shotgun/codebase/core/manager.py) performs the heaviest external work: it reads/writes files, talks to the Neo4j database, and runs cryptographic helpers (46 functions, 3 classes, called from 21 files). The router (src/shotgun/agents/router/router.py) is a hub: 24 modules import it, making it a high‑blast‑radius component.

Import cycles are present in 13 modules, notably evals/models.py, src/shotgun/tui/app.py, and src/shotgun/agents/config/models.py. These cycles increase cognitive load and risk of subtle breakage when refactoring. Deep nesting (max depth 8) appears in src/shotgun/tui/app.py and several agent modules, further complicating maintenance.

How To Use It

# Clone the repository
git clone https://github.com/moses-y/shotgun
cd shotgun

# Install Python dependencies (requires Python 3.11+)
uv sync   # uv reads pyproject.toml; alternatively: pip install -r <(uv pip compile)

# Optional: build the Docker image (uses Dockerfile)
docker build -t shotgun:latest .

# Run the CLI (the primary entry point)
python -m shotgun.main --help

Configuration defaults are provided in .env.example; copy it to .env and adjust any required keys (e.g., API tokens for LLM providers). The TUI can be launched with python -m shotgun.tui.app.

Real‑World Use

A development team using Cursor can invoke Shotgun to generate a feature spec. Shotgun reads the repo, produces a staged plan, and writes a series of PR branches (git checkout -b feature-stage‑1, …). Each PR contains only the files the AI is instructed to modify, dramatically reducing review overhead and preventing accidental deletions.

Code Health & Issues

HIGH – Pin third‑party GitHub Actions to commit SHAs (.github/workflows/*).
HIGH – Remove continue-on-error from correctness‑gate steps (.github/workflows/installation-tests.yml).
HIGH – Stop baking secrets into the Docker image (Dockerfile ARG SHOTGUN_POSTHOG_API_KEY).
MEDIUM – Declare least‑privilege GITHUB_TOKEN permissions (.github/workflows/installation-tests.yml).
MEDIUM – Pin the base image by digest (Dockerfile python:3.13-slim).
MEDIUM – Add a dependency‑vulnerability scan to CI (.github/workflows).
MEDIUM – Supply a timeout for outbound requests calls (identified in Dockerfile).
MEDIUM – Set persist-credentials: false on checkout steps (.github/workflows/deploy.yml).
LOW – Define timeout-minutes on workflow jobs (.github/workflows/deploy.yml).

Additional static findings include 13 import cycles, deep nesting in several modules, duplicated code blocks across the evals/ package, and a few files that open resources without context managers.

The Bottom Line

Shotgun provides a concrete, spec‑driven workflow that can tame AI‑generated code changes, and its modular design (CLI, autopilot, router, codebase manager) is well‑instrumented with tests. However, the codebase suffers from import cycles, deep nesting, and several high‑severity CI/security issues that should be addressed before production use. Teams comfortable with Python and containerized deployments will find the tool usable after the listed hygiene fixes.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

616 files

Python533
Markdown25
YAML7
JSON2
TOML1
HTML1

DjangoFlaskDockerTransformersNeo4j

Module dependencies

The 10 most depended-upon modules of 533, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_evals_models["models"] n1_src_shotgun_agents_models["models"] n2_src_shotgun_agents_common["common"] n3_agents_tools_codebase_models["models"] n4_src_shotgun_tui_app["app"] n5__history_token_counting_base["base"] n6_gun_agents_tools_mcp_servers["mcp_servers"] n7_shotgun_agents_config_models["models"] n8_s_tools_markdown_tools_utils["utils"] n9_nversation_history_constants["constants"] n2_src_shotgun_agents_common --> n1_src_shotgun_agents_models n1_src_shotgun_agents_models --> n7_shotgun_agents_config_models classDef cyc stroke:#ef4444,stroke-width:2px; class n0_evals_models,n4_src_shotgun_tui_app,n7_shotgun_agents_config_models cyc;

Findings

LowDependencies declared without a lockfile - non-reproducible builds pyproject.toml

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high3

medium5

low1

Pin third-party GitHub Actions to a commit SHAhigh8 occurrences

.github/workflows

astral-sh/setup-uv@v7, softprops/action-gh-release@v2, docker/setup-qemu-action@v4, docker/setup-buildx-action@v4

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Remove continue-on-error from steps that gate correctnesshigh

.github/workflows/installation-tests.yml

line 26 on a correctness step

A failing test suite reports a green check, which is precisely the path this audit exists to close.

Fix: Delete continue-on-error, or move a genuinely advisory step into a separate non-required job.

Stop passing the secret as a build argument or image envhigh

Dockerfile

ARG SHOTGUN_POSTHOG_API_KEY with a baked value

ARG and ENV values are recorded in the image layers, so the credential is readable with docker history by anyone who can pull the image, and deleting the file in a later layer does not remove it.

Fix: Mount it at build time with --mount=type=secret, or inject it at run time.

Declare least-privilege permissions for GITHUB_TOKENmedium

.github/workflows/installation-tests.yml

1 workflow(s) declare no permissions, 1 of them reference secrets

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Pin the container base image by digestmedium

Dockerfile

python:3.13-slim

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Give the outbound request a timeoutmedium

Dockerfile

1 outbound call(s) with no timeout

requests has no default timeout, so a peer that accepts the connection and then says nothing holds the worker forever, and with a small worker pool a single slow dependency takes the whole service down without anything appearing to fail.

Fix: Pass timeout= on every call, or use a session with one configured.

Set persist-credentials: false on checkoutmedium

.github/workflows/deploy.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow2 occurrences

.github/workflows/deploy.yml

2 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.