gobbler CLAUDE.md

CLAUDE.md

This file provides guidance to AI coding agents that read CLAUDE.md when working with code in this repository.

Project Overview

Gobbler is a universal content conversion tool that transforms YouTube videos, web pages, documents, and audio files into clean markdown with YAML frontmatter. It provides a CLI-first experience plus AI agent Skills that call the CLI.

Common Commands

# Install dependencies
uv sync

# Start Docker services (Crawl4AI, Docling)
make start-docker

# Run tests
make test                           # Unit tests
make test-unit                      # Unit tests only
make test-integration               # Integration tests
make test-all                       # Unit + integration + end-to-end tests
uv run pytest tests/unit/test_youtube_converter.py -v  # Single test file
uv run pytest tests/unit/test_youtube_converter.py::test_function -v  # Single test

# Code quality
uv run ruff check src/ --fix        # Lint + auto-fix
uv run ruff format src/             # Format code
uv run mypy src/                    # Type check
uv run bandit -c pyproject.toml -r src/  # Security scan
uv run pre-commit run --all-files   # All checks at once

# Check CLI
uv run gobbler --version
uv run gobbler status --json

Architecture

Source Layout (src/)

• gobbler_core/ - Shared converters, config, providers, and utilities used by the CLI

  • converters/ - YouTube, audio, document, webpage conversion logic
  • providers/ - Backend service clients
  • utils/ - Shared utilities

• gobbler_cli/ - Typer-based CLI interface

  • commands/ - Command implementations (batch, browser, convert, notebooklm, etc.)
  • main.py - CLI entry point

• gobbler_relay/ - WebSocket bridge to browser extension (port 4625)

  • relay.py - WebSocket server for bidirectional browser communication
  • client.py - Client for sending commands to extension

• gobbler_queue/ - SQLite-backed background job queue

  • worker.py - Polling worker that executes structured command arguments
  • manager.py - Job management and progress tracking
  • models.py - Job data models