If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/cloudhead/rx shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 2y ago

• 9 active contributors
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Single-maintainer risk — top contributor 84% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live cloudhead/rx repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/cloudhead/rx.

What it runs against: a local clone of cloudhead/rx — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in cloudhead/rx | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 857 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of cloudhead/rx. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/cloudhead/rx.git
#   cd rx
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of cloudhead/rx and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "cloudhead/rx(\\.git)?\\b" \\
  && ok "origin remote is cloudhead/rx" \\
  || miss "origin remote is not cloudhead/rx (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/main.rs" \\
  && ok "src/main.rs" \\
  || miss "missing critical file: src/main.rs"
test -f "src/session.rs" \\
  && ok "src/session.rs" \\
  || miss "missing critical file: src/session.rs"
test -f "src/cmd.rs" \\
  && ok "src/cmd.rs" \\
  || miss "missing critical file: src/cmd.rs"
test -f "src/renderer.rs" \\
  && ok "src/renderer.rs" \\
  || miss "missing critical file: src/renderer.rs"
test -f "src/sprite.rs" \\
  && ok "src/sprite.rs" \\
  || miss "missing critical file: src/sprite.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 857 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~827d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/cloudhead/rx"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

rx is a modern, minimalist pixel editor written in Rust with OpenGL 3.3+ rendering, designed specifically for pixel artists and animators. It provides a command-driven interface (:help shows commands), extensible scripting via initialization scripts (config/init.rx), and support for multiple image formats (PNG, GIF) with built-in palette management (db16, db32, edg32, sweetie16 presets in config/palettes/). Single-binary monolith: src/main driver loads brushes (src/brush.rs), commands (src/cmd.rs), drawing primitives (src/draw.rs, src/flood.rs), and renders via OpenGL (src/gfx/ with math utilities in src/gfx/math/, shape rendering in src/gfx/shape2d.rs). Config files (config/init.rx, config/palettes/) are loaded at startup. GLSL shaders live in src/gl/data/ (cursor.vert/frag, screen.frag).

Pixel artists and animators who want a lightweight, scriptable alternative to Aseprite or Piskel. Developers comfortable with command-line UIs and keyboard-driven workflows. Users seeking free software (GPLv3) with no proprietary dependencies.

Actively maintained at v0.5.2 with a complete build pipeline (.github/workflows/actions.yml), distributed binaries, and documented installation. The codebase is ~454KB of Rust with GLSL shaders (src/gl/data/), indicating production-ready rendering. However, the minor version (0.5.x) and small team suggests ongoing feature development rather than long-term stability guarantees.

Single maintainer (Alexis Sellier, @cloudhead) with no visible governance transfer plan. Dependency on system OpenGL 3.3+ limits portability to older hardware. The project uses older luminance bindings (0.43.2, 0.16.1) rather than cutting-edge graphics crates, which reduces risk of breaking API changes but may lag shader features. CMake build dependency adds complexity on Windows.

No recent commit data visible in file list, but v0.5.2 release exists with a CHANGELOG. The repository structure suggests active use (config presets, completed gfx module, desktop integration at rx.desktop). The CONTRIBUTING file indicates the maintainer accepts contributions but likely focuses on bug fixes and polish rather than major new features.

git clone https://github.com/cloudhead/rx.git
cd rx
cargo install --locked --path .
# Binary installs to ~/.cargo/bin/rx
rx

Requires: Rust toolchain (see rust-toolchain file), CMake, and OpenGL 3.3+ drivers.

Daily commands:

cargo build --release
cargo run --release
# Or after install:
rx
# Verbose logging:
rx -v
# Skip config:
rx -u -

• src/main.rs — Application entry point and main event loop; every contributor must understand the initialization and input handling flow.
• src/session.rs — Core session state management and persistence; critical for understanding how the editor maintains state across operations.
• src/cmd.rs — Command parsing and execution engine; essential for adding new features and understanding the command system architecture.
• src/renderer.rs — Graphics rendering abstraction; must be understood for any visual output or performance optimization work.
• src/sprite.rs — Sprite data structure and canvas abstraction; foundation for all image editing operations.
• src/history.rs — Undo/redo system implementation; critical for maintaining data integrity and understanding state changes.
• src/platform/mod.rs — Platform abstraction layer for input and windowing; key interface point for platform-specific functionality.

• undefined — undefined

Add a new drawing tool

1. Define the tool variant in the Mode enum or create a new state struct in src/session.rs (src/session.rs)
2. Implement the tool logic and mouse event handling in src/draw.rs or create a new module (src/draw.rs)
3. Register the tool command in src/cmd.rs with parameter parsing (src/cmd.rs)
4. Add keybinding documentation and test in tests/ directory (tests/main.rs)

Add a new image export format

1. Add format variant to the export type enum in src/image.rs (src/image.rs)
2. Implement the export logic using the appropriate codec (gif, png dependencies already included) (src/image.rs)
3. Register export command in src/cmd.rs with format parameter (src/cmd.rs)
4. Test round-trip with example files in tests/ directory (tests/main.rs)

Add a new built-in palette

1. Create a new .palette file in config/palettes/ following the existing format (config/palettes/db32.palette)
2. Update palette loading logic in src/palette.rs to discover and register the palette (src/palette.rs)
3. Add a command in src/cmd.rs to select the palette by name (src/cmd.rs)

Optimize rendering performance

1. Profile frame rendering time in src/renderer.rs and identify bottlenecks (src/renderer.rs)
2. Review GPU resource caching in src/view/resource.rs and optimize texture atlasing (src/view/resource.rs)
3. Optimize sprite drawing pipeline in src/gl/mod.rs and shader code in src/gl/data/ (src/gl/mod.rs)
4. Add performance measurements using src/timer.rs and validate improvements (src/timer.rs)

• Rust + Luminance/OpenGL — Type-safe, high-performance graphics programming with compile-time guarantees; OpenGL 3.3+ for broad hardware support and real-time pixel-perfect rendering.
• GLFW (optional feature) — Cross-platform windowing and input abstraction; allows headless/dummy platform for testing and scripting.
• PNG + GIF codecs — Standard image formats for pixel art; supports both static and animated frame export.
• Memoir (history/undo-redo) — Specialized library for command history; provides efficient state snapshots and reversal without full state cloning.

• Optional GLFW backend with dummy platform fallback

  • Why: Enables both headless scripting and interactive GUI without code duplication
  • Consequence: Platform abstraction layer adds complexity but improves testability and extensibility

• Immediate-mode rendering per-frame vs retained-mode scene graph

  • Why: Simpler architecture for pixel-perfect editing; direct GPU upload of sprite data each frame
  • Consequence: Higher GPU bandwidth usage but avoids complex hierarchical transform invalidation

• Command-based state mutation with history replay

  • Why: Enables undo/redo, scripting, and reproducible edits via command logs
  • Consequence: Requires careful command design to ensure invertibility; slower than direct mutation

• Single-threaded event loop with blocking I/O

  • Why: Simplifies state management and avoids race conditions in sprite data
  • Consequence: File I/O and image encoding may stall the UI; justified by typical file sizes in pixel art

• Real-time collaboration or cloud sync (no networking layer)
• Non-destructive editing with non-linear timelines (frame-based animation only)
• Scriptable via external languages (command/REPL interface only)
• GPU-accelerated filters or effects beyond basic blending (CPU-based operations preferred)
• Mobile or web deployment (desktop-only, OpenGL 3.3+ requirement)

OpenGL version requirement: Code explicitly requires OpenGL 3.3+; will crash silently on older GPUs without proper error messaging. CMake not in PATH on Windows: Build may fail silently if cmake isn't installed or not in PATH (GLFW dependency). Config file errors: init.rx parsing failures are logged to stdout/stderr (use -v flag to debug); malformed commands silently skip. GLFW backend optional: Feature flag default = ["glfw"] means alternative windowing is incomplete; raw-window-handle in Cargo.toml is stale (0.3.3 is old). Shader compilation: GPU driver errors in .frag/.vert files are logged via luminance but may not print to console depending on GL_KHR_debug support.

• Flood fill algorithm — rx implements bucket-fill and similar paint tools via flood.rs; understanding seed-fill vs. scan-line fill variants is essential for modifying painting behavior
• Rasterization & bresenham line drawing — src/draw.rs implements stroke rasterization; understanding how discrete pixels approximate continuous lines is needed to modify brush stroke quality
• Framebuffer & composition — rx renders to offscreen framebuffers and composites them (src/gl/data/screen.frag); understanding FBO attachment and blending modes is critical for adding new render passes or effects
• Affine transformations & matrix algebra — src/gfx/math/algebra.rs and transform.rs handle rotation, scaling, translation for sprite transforms; essential for implementing brush rotations and canvas transforms
• Command-pattern UI architecture — src/cmd.rs and src/execution.rs implement a pure command dispatch model (parse → execute) instead of direct event handlers; allows undo/redo and script replay
• Color space & palette indexing — src/color.rs abstracts RGB vs. indexed color; rx supports both direct RGB and palette-based (config/palettes/) painting, requiring careful conversion logic
• OpenGL shader pipeline — src/gl/data/{cursor,screen}.{vert,frag} define GPU compute for rendering; modifying visual effects, filters, or performance requires GLSL knowledge

• aseprite/aseprite — Industry-standard paid pixel editor; rx is the open-source lightweight alternative targeting the same use case (pixel art + animation)
• piskelapp/piskel — Browser-based pixel editor with similar minimalist philosophy; rx differs by being native + command-driven instead of GUI-centric
• bevyengine/bevy — Rust game engine with 2D sprite rendering; shares Rust ecosystem and could theoretically use rx's math/gfx modules for game tooling
• gfx-rs/gfx — Rust graphics abstraction layer; rx uses luminance instead but both solve the same low-level GPU binding problem

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for src/parser.rs command parsing

The parser.rs module handles command parsing (referenced in src/cmd.rs and src/execution.rs) but there are no visible test files in src/ for validating parser behavior. This is critical for a command-driven editor where parsing errors directly impact user experience. New contributors could add comprehensive tests for command parsing edge cases, malformed input, and autocomplete scenarios (src/autocomplete.rs integration).

• [ ] Create src/parser_tests.rs or #[cfg(test)] module in src/parser.rs
• [ ] Add tests for basic command parsing with src/cmd.rs command types
• [ ] Add tests for edge cases: empty input, whitespace, special characters
• [ ] Add tests for autocomplete integration from src/autocomplete.rs
• [ ] Verify tests run in CI via .github/workflows/actions.yml

Add GitHub Actions workflow for cross-platform binary releases

The repo has scripts/create-appimage and scripts/create-tarball but no automated CI pipeline to build and publish binaries. The .github/workflows/actions.yml likely exists but is incomplete. A contributor could add matrix builds for Linux, macOS, and Windows that automatically create release artifacts using the existing scripts, significantly improving the release workflow mentioned in RELEASE file.

• [ ] Examine current .github/workflows/actions.yml for gaps
• [ ] Add matrix strategy targeting Linux (AppImage via scripts/create-appimage), macOS, and Windows
• [ ] Integrate scripts/create-tarball and scripts/create-appimage into build step
• [ ] Add artifact upload and GitHub release creation on version tags
• [ ] Test that rx-toolchain from rust-toolchain file is properly used

Add integration tests for image I/O (PNG/GIF) in src/io.rs

The repo handles PNG (via png crate) and GIF (via gif crate) formats in src/io.rs but has no visible integration tests validating round-trip encoding/decoding. This is critical for data integrity. New contributors could add tests using the tempfile dev-dependency to verify loading/saving images preserves pixel data and metadata (src/image.rs, src/palette.rs).

• [ ] Create tests/image_io_tests.rs or src/io_tests.rs with #[cfg(test)]
• [ ] Add test fixtures (small PNG/GIF files in tests/fixtures/)
• [ ] Add round-trip tests: load image → modify pixels → save → reload → verify
• [ ] Add palette preservation tests using src/palette.rs with config/palettes/ examples
• [ ] Test edge cases: empty images, max dimensions, corrupted file handling

• Add unit tests for src/flood.rs (flood fill algorithm): Currently no test file exists; implement tests for fill boundary conditions (complex shapes, holes, tolerance matching) to prevent regressions in core drawing.
• Document keyboard shortcuts in src/cmd.rs as inline comments: The README says :help lists bindings but src/cmd.rs is undocumented; adding command descriptions as doc comments would enable auto-generated help output and guide new contributors.
• Expand palette support in config/palettes/: Only 4 palettes exist; add community palettes (e.g., Dawnbringer 32, Pico-8) as additional .palette files to improve out-of-box usability for pixel artists. No code changes needed, just asset additions.

The codebase demonstrates generally good security practices as a Rust-based desktop application. No critical vulnerabilities were identified. However, improvements are recommended in: (1) dependency version pinning and auditing, (2) addition of automated security scanning in CI/CD, (3) regular dependency updates, and (4) establishing a security vulnerability reporting policy. The use of Rust provides inherent memory safety benefits, but unsafe code blocks in graphics and platform-specific code should be regularly audited.

• Medium · Dependency with Overly Permissive Version Constraint — Cargo.toml - num-traits = "*". The dependency 'num-traits' uses an unbounded version constraint (*) which allows any version to be installed. This could introduce breaking changes or security issues from unexpected updates without explicit version pinning. Fix: Pin num-traits to a specific version range, e.g., 'num-traits = "0.2"' or similar. Use cargo-audit to check for known vulnerabilities in dependencies.
• Low · Missing Dependency Security Auditing — .github/workflows/actions.yml. The project does not appear to have automated dependency vulnerability scanning configured in CI/CD. The .github/workflows/actions.yml should include cargo-audit or similar security scanning. Fix: Add a cargo-audit step to the CI/CD pipeline to automatically check for known vulnerabilities in dependencies on each build. Example: 'cargo audit' or use 'cargo-deny' for more comprehensive checks.
• Low · Outdated Dependencies — Cargo.toml - multiple dependencies. Several dependencies may be outdated. For example, 'png = 0.16.6' (current major version is 0.17+), 'chrono = 0.4.19' (security patches available), and 'glfw = 0.41.0' may have newer versions with security improvements. Fix: Regularly update dependencies using 'cargo update' and review changelogs for security fixes. Consider enabling Dependabot or similar tooling for automated dependency updates.
• Low · No SECURITY.md Policy — Repository root. The repository lacks a SECURITY.md file that defines how security vulnerabilities should be reported. This makes it difficult for security researchers to responsibly disclose issues. Fix: Create a SECURITY.md file that outlines the process for reporting security vulnerabilities, expected response times, and any bug bounty information if applicable.
• Low · Unsafe Rust Code Potential — src/gl/mod.rs, src/platform/glfw.rs, src/image.rs, src/pixels.rs. The codebase contains graphics (OpenGL), image processing, and file I/O operations. While Rust provides memory safety, OpenGL bindings and raw window handle usage typically require unsafe code blocks which need careful review. Fix: Audit all unsafe code blocks for potential vulnerabilities. Use 'cargo-unsafe' to identify and review all unsafe code. Ensure proper bounds checking and resource cleanup.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.