Human contributor guide. AI agents: read AGENTS.md instead — it is the authoritative source for agent workflow, release policy, and the version-bump rules. Do not duplicate that content here.
FlashPaste is a clipboard glue tool for GNOME Wayland + kitty + tmux. Patches that broaden the supported stack (wlroots, KDE, foot, alacritty) are welcome but must not break the canonical stack.
git clone https://github.com/NagyVikt/flashpaste.git
cd flashpaste
./bin/flashpaste-doctor.sh # 17-check pre-flight; touches nothing
./install.sh # symlinks into ~/.local/bin/, drops user systemd unitsTo build the Rust tiers from source:
cd rs
cargo build --release
install -m 0755 target/release/flashpaste-{dispatch,trigger,shoot} \
target/release/flashpasted \
~/.local/bin/cargo build hits crates.io — run it interactively, not in unattended scripts.
Quoted verbatim from AGENTS.md. If a patch might affect any of them, attach a regression test or a manual test plan to the commit body.
kitty @ send-textis the only transport that triggers Claude Code's image-paste handler.tmux send-keys -t pane C-vwrites the byte but the handler doesn't fire.tmux bind -n C-vrecurses when\026arrives via kitty send-text.tmux unbind -n C-vbefore send-text, rebind ~100ms later viasetsid -f sh -c 'sleep 0.1; tmux bind ...'(detached so it survives parent exit).- Wayland-authoritative
has_imagepolicy. Trust Wayland if it answers; only fall back to X11 when Wayland is fully silent. mutter's X11↔Wayland bridge is sticky and X11 keeps advertising staleimage/pngafter fresh text copies — trusting it produces the obs #6881 "GitHub URL → [Image #9]" bug. - GNOME PrtScr saves but doesn't copy. Auto-pickup loads
~/Pictures/Screenshots/<latest>.pnginto the clipboard if ≤30s old and clipboard text is empty.
Follow the existing v1.10–v1.19 voice. Subject + body + trailer:
v1.X: <one-line summary>
<multi-paragraph body explaining what changed and why,
matching the style of v1.10–v1.17 in the existing history.>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The Co-Authored-By trailer is required for any AI-assisted change. Confirm it survived with git log --pretty=fuller.
- Patch (
v1.X.Y) — bash-only fixes, doc changes, .desktop tweaks, install.sh hygiene. - Minor (
v1.X) — new bash scripts, new systemd units, new env knobs. - Major (
v2.X) — reserved for the daemon becoming the default path and the bash dispatcher becoming a fallback only. Do not cut v2.0 until the dispatcher mode-flag flips by default.
Every commit titled vX.Y MUST be tagged and have a matching GitHub release before the turn ends. The .github/workflows/release.yml workflow auto-builds the .deb and publishes the release on every v* tag push.
git push origin main
git tag -a v1.X -m "v1.X: <one-line summary>" <commit-sha>
git push origin v1.X
gh run watch $(gh run list --workflow=release.yml --limit 1 --json databaseId -q '.[0].databaseId')
gh release view v1.XVerify with the tag-audit:
bash AGENTS-release-check.shIf anything prints, you have unfinished work. Full policy in AGENTS.md.
Before opening a PR:
# Bash syntax check
bash -n bin/*.sh install.sh bootstrap.sh
# Rust workspace (gated on user approval — hits crates.io)
cargo build --release --manifest-path rs/Cargo.toml
cargo fmt --manifest-path rs/Cargo.toml --check
cargo clippy --release --manifest-path rs/Cargo.toml -- -D warnings
# Pre-flight
flashpaste-doctorRun flashpaste-doctor on your own machine before submitting — every PR template asks for its output.
Use the GitHub issue forms:
bug_report.yml— image paste failing, dock flicker, daemon crash, etc.feature_request.yml— new capability or transport.
Security vulnerabilities go through SECURITY.md, not the public tracker.
By participating you agree to the Contributor Covenant 2.1.
By contributing you agree your work is licensed under MIT — see LICENSE.