Turn GitHub issues into reproducible bugs.
IssueCapsule v0.2 uses AI to understand a bug report, validates the proposed
steps, and compiles them into a deterministic .icap file.
$ issuecap create https://github.com/foo/bar/issues/123 --ai
Analyzing issue with AI...
✓ Python 3.12
✓ Reproduction code discovered
✓ Expected error: TypeError
Running sandbox...
BUG REPRODUCED ✓
Saved → issue-123.icap
AI understands the report. IssueCapsule reproduces it deterministically.
Important
Git and Docker are required. v0.2 supports public GitHub issues and Python projects. AI mode also needs an OpenAI-compatible JSON chat endpoint.
Install v0.2 from crates.io:
cargo install issuecapsule --version 0.2.0The command is named issuecap. Check the local requirements:
issuecap doctorPrebuilt Windows, Linux, and macOS archives are available from GitHub Releases.
Build the current source instead with:
git clone https://github.com/wantenhot/IssueCapsule.git
cd IssueCapsule
cargo install --path .Set three environment variables for any compatible HTTP endpoint:
export ISSUECAP_AI_BASE_URL="https://your-provider.example/v1"
export ISSUECAP_AI_API_KEY="<api-key>"
export ISSUECAP_AI_MODEL="<model-name>"PowerShell:
$env:ISSUECAP_AI_BASE_URL = "https://your-provider.example/v1"
$env:ISSUECAP_AI_API_KEY = "<api-key>"
$env:ISSUECAP_AI_MODEL = "<model-name>"Then analyze and reproduce an issue:
issuecap create https://github.com/foo/bar/issues/123 --aiBefore anything runs, IssueCapsule shows the proposed Python version, install command, generated files, reproduction command, expected error, and confidence. Confirm the plan to build the Docker sandbox.
Use --yes in CI to accept a validated plan with at least 60% confidence:
issuecap create https://github.com/foo/bar/issues/123 --ai --yesPlans below 60% do not run by default. --force lets you review and confirm a
low-confidence plan, but it never bypasses validation.
Use --ai-plan to analyze an issue without running Docker or creating a
capsule:
issuecap create https://github.com/foo/bar/issues/123 --ai-planAI remains optional. Supply the reproduction command and expected output yourself:
issuecap create https://github.com/foo/bar/issues/123 \
--run "python reproduce.py" \
--expect "IndexError"Run a saved capsule without an AI key:
issuecap run issue-123.icapVerify that its expected error still occurs:
issuecap verify issue-123.icapverify exits with code 0 when the bug is reproduced and code 1 when it
is not.
AI is used only during create. It receives a limited context: the issue,
up to 200 repository paths, small excerpts from dependency files and README,
and code blocks already present in the issue.
Its response must be strict JSON. IssueCapsule then:
- Parses it into a structured reproduction plan.
- Rejects unsafe commands and paths outside the repository.
- Shows the complete plan for review.
- Installs dependencies while building the Docker image.
- Runs the reproduction command with Docker networking disabled.
- Saves the validated plan and generated files in
.icap.
The API key stays in the IssueCapsule process. It is not saved in .icap,
logs, generated files, Git, or the Docker environment.
Warning
AI output is untrusted input. The validator cannot be bypassed by --yes or
--force. You should still review plans and capsules received from others.
| Command | Purpose |
|---|---|
issuecap create URL --ai |
Analyze, review, reproduce, and save a capsule |
issuecap create URL --ai-plan |
Print a plan only |
issuecap create URL --run CMD --expect TEXT |
Use manual mode |
issuecap run FILE.icap |
Run a deterministic capsule |
issuecap verify FILE.icap |
Check its expected error |
issuecap doctor |
Check Git, Docker, and GitHub access |
- Public GitHub repositories only
- Python projects only
- Docker required for execution
- OpenAI-compatible HTTP response shape in AI mode
- Dependency detection limited to
requirements.txtandpyproject.toml
IssueCapsule does not fix bugs. It makes bugs reproducible.
cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test