Metadata-Version: 2.5
Name: bugbout
Version: 0.1.1
Summary: Find out which coding agent actually fixes bugs in your codebase.
Project-URL: Homepage, https://github.com/Keerthirajan58/bugbout
Project-URL: Issues, https://github.com/Keerthirajan58/bugbout/issues
Author-email: Keerthirajan Senthilkumar <rajankeerthi0261@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: benchmark,coding-agents,evaluation,llm,swe-bench,testing
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: pydantic>=2.10
Requires-Dist: rich>=13.9
Requires-Dist: typer>=0.15
Provides-Extra: dev
Requires-Dist: mypy==2.4.0; extra == 'dev'
Requires-Dist: pytest-cov>=6.0; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff==0.17.1; extra == 'dev'
Description-Content-Type: text/markdown

# bugbout

[![PyPI version](https://img.shields.io/pypi/v/bugbout?label=PyPI&logo=pypi&logoColor=white)](https://pypi.org/project/bugbout/)
[![Supported Python versions](https://img.shields.io/pypi/pyversions/bugbout?label=Python&logo=python&logoColor=white)](https://pypi.org/project/bugbout/)
[![CI status](https://img.shields.io/github/actions/workflow/status/Keerthirajan58/bugbout/ci.yml?branch=main&label=CI&logo=githubactions&logoColor=white)](https://github.com/Keerthirajan58/bugbout/actions/workflows/ci.yml?query=branch%3Amain)
[![License](https://img.shields.io/pypi/l/bugbout?label=License&logo=opensourceinitiative&logoColor=white)](https://github.com/Keerthirajan58/bugbout/blob/main/LICENSE)
[![Development status](https://img.shields.io/pypi/status/bugbout?label=Status&color=orange)](https://github.com/Keerthirajan58/bugbout/blob/main/CHANGELOG.md)
[![Linted and formatted with Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![Type checked with mypy in strict mode](https://img.shields.io/badge/Types-mypy%20strict-2a6db2)](https://mypy-lang.org/)

**Which coding agent actually fixes bugs in *your* codebase?**

Public benchmarks tell you how coding agents do on someone else's code. bugbout tells
you how they do on yours. It replays real bugs from your project's own history, lets
agents race to fix them, and scores every patch with the tests your maintainers wrote
alongside the real fix - tests no agent ever gets to see.

## Why

- **Your code, not a leaderboard's.** An agent that tops a benchmark can still stumble
  on your conventions, your framework and your test suite. Measure it where you will
  use it.
- **Scored by your own tests.** Every task is a fix your team already shipped with a
  new test, and that test decides whether an agent's patch really fixes the bug.
- **Bring any agent.** Codex, Claude Code, Gemini CLI and mini-swe-agent work out of
  the box, and any other agent with a command line takes a few lines of config - so
  you can also compare models, including local ones.
- **Cross-examination.** Agents' tests are run against each other's patches, so you
  also learn whether an "agent jury" could pick, or gate, a patch on its own before you
  trust one in your workflow.
- **Safe to run.** Agents work in history-free checkouts, inside an OS sandbox, with
  web access switched off.

## Quickstart

You need macOS or Linux (on Windows, use WSL2), Python 3.12+, git,
[uv](https://docs.astral.sh/uv/), and at least one coding agent CLI installed and logged in.

```bash
pip install bugbout   # or: uv tool install bugbout

cd your-project
bugbout init      # writes bugbout.toml from your layout and the agents you have
bugbout doctor    # checks everything before any agent spends quota
bugbout run       # mines tasks, races the agents, judges and scores
bugbout report --format markdown
```

A bout is resumable: stop it at any point and run it again to carry on. Add an agent
later and only that agent runs.

## How it works

1. **Mine.** Fixes in your git history that name an issue and add a test become tasks.
2. **Ground truth.** The maintainers' tests run before and after their fix; the tests
   that flip from failing to passing define what "fixed" means.
3. **Race.** Each agent gets the issue and a checkout of the code before the fix - no
   git history, none of the fix's tests - and works inside a sandbox.
4. **Cross-examine.** Every test the agents wrote runs against every patch.
5. **Judge and score.** A policy picks one patch per bug from the executed evidence,
   then the hidden tests score every patch and every pick.

More in [How it works](docs/how-it-works.md).

## Configuration

`bugbout init` writes a commented `bugbout.toml`. A minimal one looks like this:

```toml
[project]
source = "src/mypkg"
tests = "tests"

[[contestants]]
agent = "codex"

[[contestants]]
agent = "claude-code"
model = "sonnet"
```

Every setting is described in [Configuration](docs/configuration.md); the built-in
agents, sandboxing and adding your own agent are covered in [Agents](docs/agents.md).

## From Python

```python
from bugbout import Bout, render_markdown

report = Bout.load(".").run()
print(render_markdown(report))
```

## From your coding agent

bugbout ships an [Agent Skill](https://agentskills.io) that teaches coding agents to set
up a bout, run it and explain the report. Install it in Claude Code (2.1.275 or later):

```text
/plugin install bugbout --marketplace Keerthirajan58/bugbout
```

On older versions, run `/plugin marketplace add Keerthirajan58/bugbout` and then
`/plugin install bugbout@bugbout`. For Codex, Cursor, Copilot, Gemini CLI and other agents:

```bash
npx skills add Keerthirajan58/bugbout
```

Or copy the `skills/bugbout` folder into your agent's skills folder, such as
`~/.claude/skills/` or `~/.agents/skills/`.

## License

[MIT](https://github.com/Keerthirajan58/bugbout/blob/main/LICENSE)
