DOCSEARCHbyAlgolia
Submit Docs

Shotgun

repository·main·Indexed 24 days ago

https://github.com/glebkudr/shotgun_code

A desktop power-tool built with Wails and Vue.js designed to package local codebase context into structured XML-like payloads for LLMs. It features Auto-Context for AI-driven file selection, support for OpenAI, Google Gemini, and OpenRouter, and real-time filesystem monitoring via Watchman to bridge local files with AI models.

Tokens
23.2K
Snippets
23
Records
80
Agent score
83%

What's inside shotgun_code

  1. Understand the Shotgun App Architecture

    main

    Shotgun App is a cross-platform desktop application built using Wails (v2) and Vue.js (v3). It uses a split architecture to leverage the strengths of both Go and web technologies:

    • Backend (Go): Responsible for heavy-duty operations including filesystem access, logic for file/folder exclusion, and the generation of the textual "Shotgun" context. It manages application state, settings, and filesystem watching.
    • Frontend (Vue.js): A Single Page Application (SPA) built with Vite and Tailwind CSS. It provides the user interface for directory selection, file tree manipulation (marking items to exclude), prompt composition, and viewing generated output.
    • Integration (Wails): Acts as the bridge, allowing the Vue.js frontend to call Go functions directly and subscribe to backend events (like progress updates or file changes).

  2. How context generation and progress reporting works

    main

    Context generation is an asynchronous process managed by the ContextGenerator struct in the Go backend.

    1. Triggering: The frontend calls RequestShotgunContextGeneration. This starts a background goroutine to prevent UI freezing.
    2. Estimation: The backend uses countProcessableItems to estimate the total work required.
    3. Generation: generateShotgunOutputWithProgress builds the textual representation (using an XML-like <file path="...">...</file> format).
    4. Feedback Loop:
      • The backend periodically calls emitProgress, which sends the shotgunContextGenerationProgress event to the frontend.
      • The frontend listens for this event via Wails EventsOn to update the progress bar in Step1PrepareContext.vue.
    5. Completion/Error: Upon finishing, the backend emits either shotgunContextGenerated or shotgunContextError to notify the UI of the result or failure.
    6. Constraints: If the generated output exceeds maxOutputSizeBytes, the process returns an ErrContextTooLong error.

  3. Understand the Shotgun Application Workflow

    main

    The application follows a three-step linear workflow coordinated by MainLayout.vue:

    1. Step 1: Prepare Context: The user selects a project folder. The application loads the file structure, starts a Watchman file watcher, and automatically generates the shotgunPromptContext. Users can configure file exclusion via useGitignore, useCustomIgnore, or manual file exclusion in FileTree.vue.
    2. Step 2: Compose Prompt: Uses the generated shotgunPromptContext (as fileListContext), the user's userTask, and rulesContent to build a finalPrompt based on a selected template. The user can edit the task or rules before executing the prompt via an LLM.
    3. Step 3: Prompt History: A persistent step that allows users to view, audit, or copy previously executed prompts, responses, and API payloads. This step is always accessible via navigation even if earlier steps are incomplete.

    Changes to the filesystem detected by Watchman trigger an automatic reload of the file tree and regeneration of the context.

  4. Understand the AI Documentation Architect role

    main

    The promptProjectManager.md defines a specialized AI role: the AI Documentation Architect & Synchronizer.

    Its primary mission is to analyze a project's codebase and existing documentation to generate a git diff that synchronizes the documentation with the actual state of the code.

    Key constraints of this role:

    • Scope: It only modifies files within the architecture/ and tasks/ directories.
    • Output: Its sole output must be a single git diff formatted text. It is strictly forbidden from modifying source code or any files outside the specified documentation directories.
    • Goal: To ensure architecture descriptions (ARCH-*.md) and task trees (TASK-*.md) accurately reflect implemented features and the current system state.

  5. How the Robotic Senior Software Engineer AI processes tasks

    main

    The AI operates as a "Robotic Senior Software Engineer" following a specific mental model to ensure high-quality code generation. It processes input through several stages:

    1. Deconstruction: Analyzing the User Task for explicit requirements and implicit goals.
    2. Impact Analysis: Identifying the exact files, modules, or functions affected.
    3. Risk Assessment: Anticipating edge cases, performance impacts, and security concerns.
    4. Solution Selection: Evaluating paths to find the best balance of simplicity, maintainability, and consistency with existing project patterns.
    5. Planning: Mentally outlining changes before generating the final <shotgunDiff>.

    Code Generation Standards:

    • Simplicity: Prioritize idiomatic, direct solutions and avoid over-engineering.
    • Architecture Respect: Follow existing naming conventions, styles, and structures.
    • Type Safety: Use appropriate type hints/annotations.
    • No New Dependencies: Do not add external libraries unless explicitly requested.
    • Atomicity: Each <hunk> must be a small, logically coherent change.

  6. Understand Shotgun's context output format

    main

    When Shotgun generates a context payload, it uses an XML-like structure to define file boundaries. This format is optimized for LLM parsing and enables accurate multi-file refactoring. Each file is wrapped in a <file> tag with a path attribute:

    <file path="path/to/file.ext">
content
</file>
    <file path="backend/main.go">
package main
...
</file>

<file path="frontend/src/App.vue">
<template>
...
</template>
</file>

  7. How to format file structure for Shotgun prompts

    main

    When providing project context to the Shotgun AI, the File Structure must follow a specific demarcation pattern so the AI can distinguish between different files.

    Each file's content must be wrapped in the following delimiters:

    *#*#*RELATIVE/PATH/TO/FILE*#*#*begin*#*#* [File Content] *#*#*end*#*#*

    Paths must be relative to the project root and use forward slashes (/).

  8. Understand the `prompt_makePlan` AI Role and Logic

    main

    The prompt_makePlan.md file defines the system prompt for a "Robotic Senior System Architect AI". This AI is designed to take a user's refactoring or design request and transform it into a structured, actionable Markdown plan.

    How the AI Processes Requests

    The AI follows a specific internal logic (which it does not output) to ensure high-quality planning:

    1. Deconstruct Request: Analyzes explicit requirements and implicit goals.
    2. Contextual Comprehension: Analyzes the provided File Structure to understand existing architecture and dependencies.
    3. Scope Definition: Delineates what is in-scope vs. out-of-scope.
    4. Risk Assessment: Identifies technical debt, performance, and security risks.
    5. Assumption Documentation: Makes and documents well-founded assumptions to resolve ambiguities.

    Input Requirements for the Prompt

    To use this prompt effectively, the following sections must be provided:

    • User Task: The core problem or design goal.
    • Guiding Principles: Core operational directives.
    • User Rules: Task-specific constraints (these override Guiding Principles).
    • File Structure: The current state of the project (directory tree and file contents wrapped in <file path="..."> tags).

    Output Characteristics

    The AI's sole and exclusive output is a single Markdown document. It is strictly forbidden from providing preamble, apologies, or conversational text outside the Markdown structure. The output is a plan, not implementation code (though pseudocode is allowed for clarity).

  9. Monitor context generation progress and errors

    main

    The application provides real-time feedback during the context generation process:

    • Progress Reporting: The backend (app.go) emits shotgunContextGenerationProgress events containing { "current": X, "total": Y }. The frontend listens for these to update the progress bar in Step1PrepareContext.vue.
    • Size Limitations: The backend enforces a maxOutputSizeBytes limit (e.g., 10 MB). If the context exceeds this, the process stops and returns an ErrContextTooLong error. This error is sent to the frontend via the shotgunContextError event and displayed in Step1PrepareContext.vue.

  10. Understand the AI Documentation Architect role and logic

    main

    The promptProjectManager defines a specialized AI role designed to maintain a project's documentation system. The AI acts as an 'AI Documentation Architect' that synchronizes the codebase with two primary documentation types: Architecture Documents (ARCH-*.md) and Task Documents (TASK-*.md).

    Core Logic Flow

    1. Analyze Inputs: Processes User Task, User Rules, and the Documentation System Concept.
    2. Codebase Analysis: Parses source code to identify modules, components, and data flows.
    3. Documentation Audit: Compares the codebase against existing architecture/ and tasks/ files to find discrepancies (e.g., outdated descriptions, missing docs, or incorrect depends_on relationships).
    4. Plan & Execute: Generates a git diff to update, create, or delete documentation files to match the 'truth' of the codebase.

    Constraints

    • Documentation Only: The AI is strictly forbidden from modifying source code. It only produces changes for files within architecture/ and tasks/ directories.
    • Minimal Diff: The goal is to produce the smallest valid set of changes required to achieve the user's task.

  11. How asynchronous project context generation works

    main

    To maintain UI responsiveness, shotgunPromptContext is generated asynchronously in a background goroutine on the Go backend.

    • Automatic Triggers: Context is regenerated when the project folder is selected, ignore rules are updated, or filesystem changes are detected by Watchman.
    • Concurrency Management: The system uses debouncing to handle rapid consecutive changes. If a new generation request arrives while a previous one is running, the existing job is cancelled to start the new one.
    • UI Feedback: While generating, Step1PrepareContext.vue displays a progress bar. There is no manual 'Proceed' button because the context is kept up-to-date automatically.

  12. Maintain documentation integrity and YAML standards

    main

    The documentation system relies on strict YAML frontmatter and cross-referencing to maintain a coherent map of the project.

    YAML Requirements

    • Timestamps: Always use {CURRENT_DATE} for updated fields. For new files, set both created and updated to {CURRENT_DATE}.
    • Uniqueness: Every id field must be unique within its type (ARCH or TASK).
    • Task Auditing: New TASK-*.md files must include an entry in the audit_log using {CURRENT_DATE} and the user @AI-DocArchitect.

    Cross-Referencing Rules

    • Architecture (ARCH-*.md): Use the depends_on key to define dependencies. Do not populate referenced_by unless explicitly instructed.
    • Tasks (TASK-*.md): Use arch_refs to link to architecture files and parents/children to define the task hierarchy.
    • Consistency: Ensure status (e.g., done, current) and version (e.g., v1) fields accurately reflect the implementation state.