{"repo": "block/diffweave-ai", "files": {"AGENTS.md": {"1140ed05faac7e6234d90447b780d219fa176e94": {"t": 1785674437.5596352, "n": 6137, "h": "e04061209859b536", "c": "# AGENTS.md — DiffWeave AI\n\nThis file is a quick-start guide for AI coding assistants (Claude Code, etc.) working on this project.\n\n---\n\n## Project Overview\n\n**DiffWeave AI** is a CLI tool that automatically generates Git commit messages and pull request descriptions using LLMs. It analyzes staged diffs and produces descriptive messages in either Conventional Commits or natural language style.\n\n- **Package name:** `diffweave-ai` (PyPI) / `diffweave` (Python package)\n- **Version:** 1.2.2\n- **Entry point:** `diffweave:app` → `diffweave/cli.py`\n- **Current branch:** `zfarmer/dev` (main branch is `main`)\n\n---\n\n## Tech Stack\n\n| Concern | Tool |\n|---|---|\n| Language | Python 3.9+ (target 3.12) |\n| CLI framework | [cyclopts](https://github.com/BrainStone/cyclopts) (migrated from typer) |\n| LLM client | `openai` SDK (supports custom HTTP endpoints) |\n| Git operations | `gitpython` |\n| Interactive TUI | `beaupy` (multi-select, prompts) |\n| Clipboard | `copykitten` |\n| Config format | YAML via `pyyaml` |\n| Package manager | `uv` (lock file: `uv.lock`) |\n| Build system | `hatchling` |\n| Linter/formatter | `ruff` (line-length=120, double quotes) |\n| Tests | `pytest` + `pytest-asyncio`, `pytest-cov`, `pytest-mock` |\n| Docs | `mkdocs` + `mkdocs-material` |\n| Task runner | `just` (see `justfile`) |\n\n---\n\n## Key Development Commands\n\n```bash\njust format        # ruff format (alias: just fmt)\njust test          # pytest with coverage (all tests)\njust test tests/test_cli.py  # run specific test file\njust commit        # run diffweave-ai locally (uv run diffweave-ai)\njust docs          # build mkdocs and open site/index.html\n\nuv run diffweave-ai          # run the tool from local checkout\nuvx diffweave-ai             # run as isolated tool (published version)\n```\n\n---\n\n## Project Structure\n\n```\ndiffweave/\n├── __init__.py          # Package exports: run_cmd, ai, repo, app\n├── cli.py               # All CLI command definitions (206 lines)\n├── ai.py                # LLM config, model management, message generation (204 lines)\n├── repo.py              # Git operations and diff generation (218 lines)\n├── utils.py             # run_cmd() shell helper with rich formatting (70 lines)\n└── prompts/\n    ├── prompt.md        # Conventional Commits style system prompt\n    ├── simple.md        # Natural language style system prompt\n    └── pull_request.md  # PR description generation prompt\n\ntests/\n├── conftest.py          # Fixtures: patch_openai, new_repo, config_file, populated_config\n├── test_cli.py          # CLI command integration tests\n├── test_repo.py         # Repository operations tests\n├── test_ai.py           # LLM interaction tests\n├── test_run_cmd.py      # Shell command execution tests\n├── test_config.py       # (placeholder, empty)\n└── test_unix_commands.py\n\ndocs/\n├── index.md             # CLI reference guide\n└── installation.md      # Setup and configuration guide\n\npyproject.toml           # Dependencies and ruff/mypy config\njustfile                 # Task automation\nmkdocs.yml               # Docs build config\n```\n\n---\n\n## CLI Commands\n\n```bash\n# Default: generate a commit message (interactive)\ndiffweave-ai [-m MODEL] [-s] [--dry-run] [--non-interactive] [-v] [-w] [-c CONFIG]\n\n# Model management\ndiffweave-ai add-model [-m MODEL] [-t TOKEN] [-e ENDPOINT] [-c CONFIG]\ndiffweave-ai set-model MODEL_NAME [-c CONFIG]\ndiffweave-ai list-models [-c CONFIG]\n\n# PR description generation\ndiffweave-ai pr [--branch BRANCH] [-m MODEL] [-v] [-c CONFIG]\n```\n\n**Flags for default command:**\n- `-s / --simple` — natural language style (omits Conventional Commits prefix)\n- `--dry-run` — generate message and exit without committing\n- `--non-interactive` — skip all prompts, use first generated message\n- `-w / --open-browser` — open repo in browser after push\n\n---\n\n## Configuration\n\n**Default config location:** `~/.config/diffweave/config.yaml`\n\n```yaml\n<<DEFAULT>>: my-model\nmy-model:\n  endpoint: https://api.openai.com/v1\n  token: sk-...\nanother-model:\n  endpoint: https://custom-endpoint.com/v1\n  token: token-here\n```\n\n- Tokens are redacted when listed\n- Legacy config auto-migrates from `~/.config/llmit/config.yaml`\n- `--config / -c` flag overrides default path\n\n---\n\n## Architecture Notes\n\n### `diffweave/cli.py`\n- `commit()` (line 21) — main flow: init LLM → get repo → stage files → generate diffs → iterate with user → git commit/push\n- `pr()` (line 128) — branch diff → LLM → output PR description\n- Model config commands: `add_model`, `set_model`, `list_models`\n\n### `diffweave/ai.py`\n- `LLM` class wraps OpenAI client with custom endpoint support\n- `iterate_on_commit_message()` — feedback loop: generate → review → refine\n- `query_model()` — async method that calls LLM with system prompt + user content\n- Config stored/loaded from YAML; prompts loaded from `diffweave/prompts/*.md`\n\n### `diffweave/repo.py`\n- `get_repo()` — searches parent directories for `.git`\n- `generate_diffs_with_context()` — main entry point; handles first commit edge case\n- `add_files()` — beaupy multi-select for interactive staging\n- `MAX_DIFF_ITEM_SIZE = 40_000` — truncates large files to prevent token overflow\n- GitHub URL regex handles SSH, HTTPS, and `git://` remote formats\n\n### `diffweave/utils.py`\n- `run_cmd(cmd: str, ...)` — runs shell commands, formats output, raises `SystemError` on non-zero exit\n\n---\n\n## Testing Conventions\n\n- All tests use `patch_openai` autouse fixture (mocks OpenAI client globally)\n- `new_repo()` fixture creates a real temp git repo for integration tests\n- `populated_config()` provides a ready-made YAML config fixture\n- Run with: `uv run pytest --cov=diffweave --cov-branch tests/`\n\n---\n\n## Code Style\n\n- **Formatter:** ruff (double quotes, 4-space indent, line-length=120)\n- **Import errors ignored:** `F401` (unused imports)\n- **Type hints:** present but not strictly enforced (mypy config exists)\n- Prefer editing existing files over creating new ones\n- Prompts live in `diffweave/prompts/` as Markdown files — edit there, not in Python\n\n---\n\n## External Dependencies\n\nRequires system-level tools:\n- `git` — version control\n- `tree` — used for directory display in UI\n"}}}}