Contributing to agent-vision-toolkit

Thanks for helping improve agent-vision-toolkit. Focused fixes, tests, host integrations, visual workflows, and documentation improvements are welcome.

By participating, you agree to follow the Code of Conduct.

Before You Start

1. Read README.md and, for deployment changes, AGENT_INSTALL.md.
2. Search existing issues and pull requests before starting duplicate work.
3. Open an issue before broad architecture changes, new protocol behavior, or new host integrations.
4. Keep changes narrowly scoped. Do not combine unrelated refactors with a fix or feature.

Project Scope and Invariants

The repository has two layers:

1. Five standalone CLIs (glance, ground, detect, trace, and crop) plus the vision-skills skill.
2. Optional seamless integration through the local proxy or single-file native extensions.

Contributions must preserve these boundaries:

• Do not add a universal one-click installer, uninstaller, migration framework, or configuration-editing framework. Installation remains agent-led and machine-specific.
• Keep the proxy standard-library-only. Optional CLI dependencies must remain isolated from the proxy.
• Preserve ordinary text, model names, and authentication headers exactly. The only fixed display alias is gpt-5.2 to deepseek-v4-flash.
• Keep default SSE forwarding incremental. Buffer only the specific response path that requires compatibility handling.
• Never log request bodies, images, prompts, conversations, API keys, or other credentials.
• Keep Pi / Oh My Pi and OpenCode extensions single-file and self-contained. Failures must remain visible rather than being silently swallowed.
• Keep glance, ground, and the other CLIs independent from the proxy request path.
• Do not modify the effect images under assets/ unless the contribution specifically targets those assets.

Development Setup

• Python 3.11 or newer is required for the Python entry points and core tests.
• Node.js 24 or newer, or Bun, is required only for extension tests.
• Core tests stub their network dependencies; they do not require a real VISION_API_KEY.
• Install optional dependencies such as Pillow and vtracer in an isolated environment only when testing the tools that need them.

Required Verification

Run the core checks after every change:

python3 -m py_compile vision_proxy.py vision_client.py ground.py detect.py bin/glance bin/trace bin/crop
python3 tests/test_image_rewrite_shapes.py
python3 tests/test_focus_hint.py
python3 tests/test_anthropic_rewrite.py
python3 tests/smoke_test_proxy.py
python3 tests/test_vision_client.py
git diff --check

Add the focused check for each changed area:

Changed area	Additional check
ground.py / bin/ground	python3 tests/test_ground.py
detect.py / bin/detect	python3 tests/test_detect.py
bin/glance	python3 tests/test_glance_region.py
bin/trace	python3 tests/test_trace.py
bin/crop	python3 tests/test_crop.py
skills/vision-skills/scripts/html_shot.py	python3 tests/test_html_shot.py
skills/vision-skills/scripts/dominant_colors.py	python3 tests/test_dominant_colors.py
skills/vision-skills/scripts/extract_fg.py	python3 tests/test_extract_fg.py
skills/vision-skills/scripts/long_screenshot_ocr.py	python3 tests/test_long_screenshot_ocr.py
extensions/**/*.ts	node tests/test_extensions.mjs

Some focused tests skip optional CLI cases when their external dependency is unavailable. Mention any skipped check in the pull request.

Documentation

• Keep README.md and README_CN.md aligned when changing shared product behavior or setup instructions.
• Preserve the existing product copy and structure; make the smallest patch required for the change.
• Put detailed deployment steps in AGENT_INSTALL.md, reusable visual workflows in the skill references, and evaluation evidence in research/ rather than expanding the README indefinitely.
• Use relative links for repository files so forks and local copies keep working.

Pull Requests

A pull request should include:

• the concrete problem or use case;
• a concise explanation of the chosen implementation;
• the exact verification commands and results;
• screenshots or fixtures only when they materially verify visual behavior;
• documentation updates for user-visible changes.

Maintainers may ask to split a broad pull request into smaller changes or to move an out-of-scope idea into a discussion first.