# Shotgun
A Python CLI tool for research, planning, and task management powered by AI agents.
## Features
- **Research**: Perform research with agentic loops
- **Planning**: Generate structured plans for achieving goals
- **Tasks**: Generate prioritized task lists with agentic approaches
## Installation
### From PyPI (Recommended)
```bash
pip install shotgun-sh
```
### From Source
```bash
git clone https://github.com/shotgun-sh/shotgun.git
cd shotgun
uv sync --all-extras
```
After installation from source, you can use either method:
**Method 1: Direct command (after uv sync)**
```bash
shotgun --help
```
**Method 2: Via uv run**
```bash
uv run shotgun --help
```
If installed from PyPI, simply use:
```bash
shotgun --help
```
### Virtual Environment Setup (Optional)
If you prefer using a local virtual environment:
```bash
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
uv sync --all-extras
shotgun --help
```
## Usage
### Using Direct Commands (after uv sync)
```bash
# Research a topic
shotgun research "What is quantum computing?"
# Generate a plan
shotgun plan "Build a web application"
shotgun plan "build me a house"
# Generate tasks for a project
shotgun tasks "Create a machine learning model"
```
### Using uv run
```bash
# Research a topic
uv run shotgun research "What is quantum computing?"
# Generate a plan
uv run shotgun plan "Build a web application"
# Generate tasks for a project
uv run shotgun tasks "Create a machine learning model"
```
## Auto-Updates
Shotgun automatically checks for updates to keep you on the latest version.
### How it works
- Checks for updates on startup (runs in background, non-blocking)
- Caches results for 24 hours to minimize API calls
- Shows notification after command execution if an update is available
- Never auto-updates development versions
### Update Commands
```bash
# Check for available updates
shotgun update --check
# Install available updates
shotgun update
# Force update (even for dev versions with confirmation)
shotgun update --force
```
### Disable Update Checks
```bash
# Disable for a single command
shotgun --no-update-check research "topic"
```
### Installation Methods
The update command automatically detects and uses the appropriate method:
- **pipx**: `pipx upgrade shotgun-sh`
- **pip**: `pip install --upgrade shotgun-sh`
- **venv**: Updates within the virtual environment
## Development Setup
### Requirements
- **Python 3.11+** (3.13 recommended)
- **uv** - Fast Python package installer and resolver
- **actionlint** (optional) - For GitHub Actions workflow validation
### Quick Start
1. **Clone and setup**:
```bash
git clone https://github.com/shotgun-sh/shotgun.git
cd shotgun
```
2. **Install uv** (if not already installed):
```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Or via brew
brew install uv
```
3. **Install dependencies**:
```bash
uv sync --all-extras
```
4. **Install git hooks**:
```bash
uv run lefthook install
```
5. **Verify setup**:
```bash
uv run shotgun --version
```
### Development Commands
```bash
# Run the CLI
uv run shotgun --help
# Run the TUI
uv run tui
# Run tests
uv run pytest
# Run tests with coverage
uv run pytest --cov=src --cov-report=term-missing --cov-report=html
# Run linting
uv run ruff check .
# Run formatting
uv run ruff format .
# Run type checking
uv run mypy src/
# Run all pre-commit hooks manually
uv run lefthook run pre-commit
```
### Code Coverage
To analyze test coverage and identify areas that need testing:
```bash
# Run tests with coverage analysis
uv run pytest --cov=src --cov-report=term-missing --cov-report=html
```
This will:
- Display coverage summary in the terminal
- Generate a detailed HTML coverage report
**Viewing the coverage report:**
Open `htmlcov/index.html` in your browser to see:
- Overall coverage percentage
- File-by-file coverage breakdown
- Line-by-line coverage highlighting
- Missing coverage areas
The coverage configuration is in `pyproject.toml` and will automatically run when you use `uv run pytest`.
### Git Hooks (Lefthook)
This project uses [lefthook](https://github.com/evilmartians/lefthook) for git hooks. The hooks automatically run:
- **ruff** - Python linting with auto-fix
- **ruff-format** - Code formatting
- **mypy** - Type checking
- **commitizen** - Commit message validation
- **actionlint** - GitHub Actions workflow validation (if installed)
#### Installing actionlint (recommended)
```bash
# macOS
brew install actionlint
# Linux/macOS (direct download)
curl -sSfL https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash | bash
# Go install
go install github.com/rhysd/actionlint/cmd/actionlint@latest
```
### Python Version Management
The project supports **Python 3.11+**. The `.python-version` file specifies Python 3.11 to ensure development against the minimum supported version.
If using **pyenv**:
```bash
pyenv install 3.11
```
If using **uv** (recommended):
```bash
uv python install 3.11
uv sync --python 3.11
```
### Commit Message Convention
This project enforces **Conventional Commits** specification. All commit messages must follow this format:
```
<type>[optional scope]: <description>
```
**Required commit types:**
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation changes
- `style`: Code formatting changes
- `refactor`: Code restructuring without feature changes
- `perf`: Performance improvements
- `test`: Adding or updating tests
- `build`: Build system changes
- `ci`: CI/CD changes
- `chore`: Maintenance tasks
- `revert`: Reverting previous commits
**Examples:**
```bash
feat: add user authentication system
fix: resolve memory leak in data processing
docs: update API documentation
refactor: simplify user validation logic
```
**For interactive commit creation:**
```bash
uv run cz commit
```
### Contributing
1. Fork the repository
2. Create a feature branch: `git checkout -b feat/feature-name`
3. Make your changes
4. Run the pre-commit hooks: `uv run lefthook run pre-commit`
5. Commit with conventional format: `git commit -m "feat: add new feature"`
6. Push to your fork: `git push origin feat/feature-name`
7. Create a Pull Request with conventional title format
### CI/CD
GitHub Actions automatically:
- Runs on pull requests and pushes to main
- Tests with Python 3.11
- Validates code with ruff, ruff-format, and mypy
- Ensures all checks pass before merge
## Observability & Telemetry
Shotgun includes built-in observability with Sentry for error tracking and Logfire for logging and tracing. Both services track users anonymously using a UUID generated on first run.
### Anonymous User Tracking
Each user gets a unique anonymous ID stored in their config:
```bash
# Get your anonymous user ID
shotgun config get-user-id
```
This ID is automatically included in:
- **Sentry**: Error reports and exceptions
- **Logfire**: All logs, traces, and spans
### Logfire Queries
Logfire uses SQL for querying logs. Here are helpful queries for debugging and analysis:
#### Find all logs for a specific user
```sql
SELECT * FROM records
WHERE attributes->>'user_id' = 'your-user-id-here'
ORDER BY timestamp DESC;
```
#### Track user actions
```sql
SELECT
timestamp,
span_name,
message,
attributes
FROM records
WHERE attributes->>'user_id' = 'your-user-id-here'
AND span_name LIKE '%research%'
ORDER BY timestamp DESC;
```
#### Find slow operations for a user
```sql
SELECT
span_name,
duration_ms,
attributes
FROM records
WHERE attributes->>'user_id' = 'your-user-id-here'
AND duration_ms > 1000
ORDER BY duration_ms DESC;
```
#### Find errors for a user
```sql
SELECT * FROM records
WHERE attributes->>'user_id' = 'your-user-id-here'
AND level = 'error'
ORDER BY timestamp DESC;
```
#### Analyze user's AI provider usage
```sql
SELECT
attributes->>'provider' as provider,
COUNT(*) as usage_count,
AVG(duration_ms) as avg_duration
FROM records
WHERE attributes->>'user_id' = 'your-user-id-here'
AND attributes->>'provider' IS NOT NULL
GROUP BY provider;
```
#### Track feature usage by user
```sql
SELECT
span_name,
COUNT(*) as usage_count
FROM records
WHERE attributes->>'user_id' = 'your-user-id-here'
AND span_name IN ('research', 'plan', 'tasks')
GROUP BY span_name
ORDER BY usage_count DESC;
```
### Setting Up Observability (Optional)
For local development with Logfire:
```bash
# Set environment variables
export LOGFIRE_ENABLED=true
export LOGFIRE_TOKEN=your-logfire-token
# Run shotgun - will now send logs to Logfire
shotgun research "topic"
```
For Sentry (automatically configured in production builds):
```bash
# Set for local development
export SENTRY_DSN=your-sentry-dsn
```
### Privacy
- **No PII collected**: Only anonymous UUIDs are used for identification
- **Opt-in for development**: Telemetry requires explicit environment variables
- **Automatic in production**: Production builds include telemetry for error tracking
## Support
Join our discord https://discord.gg/5RmY6J2N7s
Raw data
{
"_id": null,
"home_page": null,
"name": "shotgun-sh",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "agent, ai, cli, llm, planning, productivity, pydantic-ai, research, task-management",
"author": null,
"author_email": "\"Proofs.io\" <hello@proofs.io>",
"download_url": "https://files.pythonhosted.org/packages/c2/ba/c4ce43553fbeeee044aa4335f4fc63bf44b69b15a404fb3dde8077658d8f/shotgun_sh-0.2.3.tar.gz",
"platform": null,
"description": "# Shotgun\n\nA Python CLI tool for research, planning, and task management powered by AI agents.\n\n## Features\n\n- **Research**: Perform research with agentic loops\n- **Planning**: Generate structured plans for achieving goals\n- **Tasks**: Generate prioritized task lists with agentic approaches\n\n## Installation\n\n### From PyPI (Recommended)\n\n```bash\npip install shotgun-sh\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/shotgun-sh/shotgun.git\ncd shotgun\nuv sync --all-extras\n```\n\nAfter installation from source, you can use either method:\n\n**Method 1: Direct command (after uv sync)**\n```bash\nshotgun --help\n```\n\n**Method 2: Via uv run**\n```bash\nuv run shotgun --help\n```\n\nIf installed from PyPI, simply use:\n```bash\nshotgun --help\n```\n\n### Virtual Environment Setup (Optional)\n\nIf you prefer using a local virtual environment:\n\n```bash\nuv venv\nsource .venv/bin/activate # On Windows: .venv\\Scripts\\activate\nuv sync --all-extras\nshotgun --help\n```\n\n## Usage\n\n### Using Direct Commands (after uv sync)\n\n```bash\n# Research a topic\nshotgun research \"What is quantum computing?\"\n\n# Generate a plan\nshotgun plan \"Build a web application\"\nshotgun plan \"build me a house\"\n\n# Generate tasks for a project\nshotgun tasks \"Create a machine learning model\"\n```\n\n### Using uv run\n\n```bash\n# Research a topic\nuv run shotgun research \"What is quantum computing?\"\n\n# Generate a plan\nuv run shotgun plan \"Build a web application\"\n\n# Generate tasks for a project\nuv run shotgun tasks \"Create a machine learning model\"\n```\n\n## Auto-Updates\n\nShotgun automatically checks for updates to keep you on the latest version.\n\n### How it works\n\n- Checks for updates on startup (runs in background, non-blocking)\n- Caches results for 24 hours to minimize API calls\n- Shows notification after command execution if an update is available\n- Never auto-updates development versions\n\n### Update Commands\n\n```bash\n# Check for available updates\nshotgun update --check\n\n# Install available updates\nshotgun update\n\n# Force update (even for dev versions with confirmation)\nshotgun update --force\n```\n\n### Disable Update Checks\n\n```bash\n# Disable for a single command\nshotgun --no-update-check research \"topic\"\n```\n\n### Installation Methods\n\nThe update command automatically detects and uses the appropriate method:\n- **pipx**: `pipx upgrade shotgun-sh`\n- **pip**: `pip install --upgrade shotgun-sh`\n- **venv**: Updates within the virtual environment\n\n## Development Setup\n\n### Requirements\n\n- **Python 3.11+** (3.13 recommended)\n- **uv** - Fast Python package installer and resolver\n- **actionlint** (optional) - For GitHub Actions workflow validation\n\n### Quick Start\n\n1. **Clone and setup**:\n ```bash\n git clone https://github.com/shotgun-sh/shotgun.git\n cd shotgun\n ```\n\n2. **Install uv** (if not already installed):\n ```bash\n # macOS/Linux\n curl -LsSf https://astral.sh/uv/install.sh | sh\n \n # Or via brew\n brew install uv\n ```\n\n3. **Install dependencies**:\n ```bash\n uv sync --all-extras\n ```\n\n4. **Install git hooks**:\n ```bash\n uv run lefthook install\n ```\n\n5. **Verify setup**:\n ```bash\n uv run shotgun --version\n ```\n\n### Development Commands\n\n```bash\n# Run the CLI\nuv run shotgun --help\n\n# Run the TUI\nuv run tui\n\n# Run tests\nuv run pytest\n\n# Run tests with coverage\nuv run pytest --cov=src --cov-report=term-missing --cov-report=html\n\n# Run linting\nuv run ruff check .\n\n# Run formatting\nuv run ruff format .\n\n# Run type checking\nuv run mypy src/\n\n# Run all pre-commit hooks manually\nuv run lefthook run pre-commit\n```\n\n### Code Coverage\n\nTo analyze test coverage and identify areas that need testing:\n\n```bash\n# Run tests with coverage analysis\nuv run pytest --cov=src --cov-report=term-missing --cov-report=html\n```\n\nThis will:\n- Display coverage summary in the terminal\n- Generate a detailed HTML coverage report\n\n**Viewing the coverage report:**\nOpen `htmlcov/index.html` in your browser to see:\n- Overall coverage percentage\n- File-by-file coverage breakdown \n- Line-by-line coverage highlighting\n- Missing coverage areas\n\nThe coverage configuration is in `pyproject.toml` and will automatically run when you use `uv run pytest`.\n\n### Git Hooks (Lefthook)\n\nThis project uses [lefthook](https://github.com/evilmartians/lefthook) for git hooks. The hooks automatically run:\n\n- **ruff** - Python linting with auto-fix\n- **ruff-format** - Code formatting \n- **mypy** - Type checking\n- **commitizen** - Commit message validation\n- **actionlint** - GitHub Actions workflow validation (if installed)\n\n#### Installing actionlint (recommended)\n\n```bash\n# macOS\nbrew install actionlint\n\n# Linux/macOS (direct download)\ncurl -sSfL https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash | bash\n\n# Go install\ngo install github.com/rhysd/actionlint/cmd/actionlint@latest\n```\n\n\n### Python Version Management\n\nThe project supports **Python 3.11+**. The `.python-version` file specifies Python 3.11 to ensure development against the minimum supported version.\n\nIf using **pyenv**:\n```bash\npyenv install 3.11\n```\n\nIf using **uv** (recommended):\n```bash\nuv python install 3.11\nuv sync --python 3.11\n```\n\n### Commit Message Convention\n\nThis project enforces **Conventional Commits** specification. All commit messages must follow this format:\n\n```\n<type>[optional scope]: <description>\n```\n\n**Required commit types:**\n- `feat`: New feature\n- `fix`: Bug fix\n- `docs`: Documentation changes\n- `style`: Code formatting changes\n- `refactor`: Code restructuring without feature changes\n- `perf`: Performance improvements\n- `test`: Adding or updating tests\n- `build`: Build system changes\n- `ci`: CI/CD changes\n- `chore`: Maintenance tasks\n- `revert`: Reverting previous commits\n\n**Examples:**\n```bash\nfeat: add user authentication system\nfix: resolve memory leak in data processing\ndocs: update API documentation\nrefactor: simplify user validation logic\n```\n\n**For interactive commit creation:**\n```bash\nuv run cz commit\n```\n\n### Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feat/feature-name`\n3. Make your changes\n4. Run the pre-commit hooks: `uv run lefthook run pre-commit`\n5. Commit with conventional format: `git commit -m \"feat: add new feature\"`\n6. Push to your fork: `git push origin feat/feature-name`\n7. Create a Pull Request with conventional title format\n\n### CI/CD\n\nGitHub Actions automatically:\n- Runs on pull requests and pushes to main\n- Tests with Python 3.11\n- Validates code with ruff, ruff-format, and mypy\n- Ensures all checks pass before merge\n\n## Observability & Telemetry\n\nShotgun includes built-in observability with Sentry for error tracking and Logfire for logging and tracing. Both services track users anonymously using a UUID generated on first run.\n\n### Anonymous User Tracking\n\nEach user gets a unique anonymous ID stored in their config:\n```bash\n# Get your anonymous user ID\nshotgun config get-user-id\n```\n\nThis ID is automatically included in:\n- **Sentry**: Error reports and exceptions\n- **Logfire**: All logs, traces, and spans\n\n### Logfire Queries\n\nLogfire uses SQL for querying logs. Here are helpful queries for debugging and analysis:\n\n#### Find all logs for a specific user\n```sql\nSELECT * FROM records\nWHERE attributes->>'user_id' = 'your-user-id-here'\nORDER BY timestamp DESC;\n```\n\n#### Track user actions\n```sql\nSELECT\n timestamp,\n span_name,\n message,\n attributes\nFROM records\nWHERE attributes->>'user_id' = 'your-user-id-here'\n AND span_name LIKE '%research%'\nORDER BY timestamp DESC;\n```\n\n#### Find slow operations for a user\n```sql\nSELECT\n span_name,\n duration_ms,\n attributes\nFROM records\nWHERE attributes->>'user_id' = 'your-user-id-here'\n AND duration_ms > 1000\nORDER BY duration_ms DESC;\n```\n\n#### Find errors for a user\n```sql\nSELECT * FROM records\nWHERE attributes->>'user_id' = 'your-user-id-here'\n AND level = 'error'\nORDER BY timestamp DESC;\n```\n\n#### Analyze user's AI provider usage\n```sql\nSELECT\n attributes->>'provider' as provider,\n COUNT(*) as usage_count,\n AVG(duration_ms) as avg_duration\nFROM records\nWHERE attributes->>'user_id' = 'your-user-id-here'\n AND attributes->>'provider' IS NOT NULL\nGROUP BY provider;\n```\n\n#### Track feature usage by user\n```sql\nSELECT\n span_name,\n COUNT(*) as usage_count\nFROM records\nWHERE attributes->>'user_id' = 'your-user-id-here'\n AND span_name IN ('research', 'plan', 'tasks')\nGROUP BY span_name\nORDER BY usage_count DESC;\n```\n\n### Setting Up Observability (Optional)\n\nFor local development with Logfire:\n```bash\n# Set environment variables\nexport LOGFIRE_ENABLED=true\nexport LOGFIRE_TOKEN=your-logfire-token\n\n# Run shotgun - will now send logs to Logfire\nshotgun research \"topic\"\n```\n\nFor Sentry (automatically configured in production builds):\n```bash\n# Set for local development\nexport SENTRY_DSN=your-sentry-dsn\n```\n\n### Privacy\n\n- **No PII collected**: Only anonymous UUIDs are used for identification\n- **Opt-in for development**: Telemetry requires explicit environment variables\n- **Automatic in production**: Production builds include telemetry for error tracking\n\n## Support\n\nJoin our discord https://discord.gg/5RmY6J2N7s\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "AI-powered research, planning, and task management CLI tool",
"version": "0.2.3",
"project_urls": {
"Discord": "https://discord.gg/5RmY6J2N7s",
"Homepage": "https://shotgun.sh/",
"Issues": "https://github.com/shotgun-sh/shotgun-alpha/issues",
"Repository": "https://github.com/shotgun-sh/shotgun"
},
"split_keywords": [
"agent",
" ai",
" cli",
" llm",
" planning",
" productivity",
" pydantic-ai",
" research",
" task-management"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9140ad8f2d052afaff08ac62c281ffcf8c3003e11d645626472a85419c0c63e3",
"md5": "540a2992ba64525d2a620a9269527239",
"sha256": "7278377da582d871974f9e5437d3eef0351e75f14f5ec7d8a69740ab38b35706"
},
"downloads": -1,
"filename": "shotgun_sh-0.2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "540a2992ba64525d2a620a9269527239",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 241124,
"upload_time": "2025-10-10T19:58:34",
"upload_time_iso_8601": "2025-10-10T19:58:34.300347Z",
"url": "https://files.pythonhosted.org/packages/91/40/ad8f2d052afaff08ac62c281ffcf8c3003e11d645626472a85419c0c63e3/shotgun_sh-0.2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c2bac4ce43553fbeeee044aa4335f4fc63bf44b69b15a404fb3dde8077658d8f",
"md5": "6c7a6b37e4af0a39e5df5da8d7ead423",
"sha256": "f363616be805a57e51f1145456db6da786cae14158c1d71820fb2d7cd5c50018"
},
"downloads": -1,
"filename": "shotgun_sh-0.2.3.tar.gz",
"has_sig": false,
"md5_digest": "6c7a6b37e4af0a39e5df5da8d7ead423",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 170364,
"upload_time": "2025-10-10T19:58:35",
"upload_time_iso_8601": "2025-10-10T19:58:35.466763Z",
"url": "https://files.pythonhosted.org/packages/c2/ba/c4ce43553fbeeee044aa4335f4fc63bf44b69b15a404fb3dde8077658d8f/shotgun_sh-0.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-10 19:58:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "shotgun-sh",
"github_project": "shotgun-alpha",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "shotgun-sh"
}
JSON
