WAIT — Single-maintainer risk — review before adopting

• Last commit 6w ago
• 2 active contributors
• GPL-3.0 licensed
• CI configured
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 97% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility
• ⚠ No test directory detected
• ⚠ Scorecard: default branch unprotected (0/10)

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

Keyviz is a free, open-source desktop application built with Tauri (Rust + TypeScript) that captures and visualizes keyboard keypresses and mouse actions in real-time on-screen. It solves the problem of making keyboard shortcuts and input interactions visible during tutorials, presentations, and live coding sessions by rendering a customizable overlay that displays what keys are being pressed, mouse clicks, drags, and scroll wheel movements as they happen. Hybrid Tauri architecture: src-tauri/crates/rdev/ contains the core Rust input event listener and platform-specific modules (linux/, macos/ with display.rs, grab.rs, keyboard.rs, listen.rs), while the TypeScript/React frontend lives in src/ with Vite bundling and Tailwind CSS styling. Tauri plugins (store, fs, dialog, opener, os) bridge the frontend to native APIs; settings and state managed via zustand.

Content creators, educators, and livestreamers who need to show their keyboard and mouse inputs to audiences during screen recordings or live presentations; also developers and power users who want to verify their muscle memory with frequently-used keyboard shortcuts.

Actively developed with 332KB of TypeScript and 188KB of Rust codebase, CI/CD pipelines via GitHub Actions (winget.yml suggests Windows package manager integration), and support for multiple platforms (Windows, macOS, Linux x11). The project has enough mature polish to ship installers (.msi, .dmg) but is at version 0.1.0, indicating feature development is ongoing rather than stabilized.

The single-maintainer risk is moderate (mulaRahul as primary contributor); dependency surface is broad (36 npm dependencies including motion, recharts, zustand, plus Tauri plugins) which increases supply-chain exposure. No visible test infrastructure in the file list is a notable gap. Platform-specific native input capturing via rdev (custom Rust crate in src-tauri/crates/rdev/) means OS permission handling and driver compatibility bugs could be fragile.

Unable to determine from file list alone (no git log, PRs, or issues visible), but the presence of .github/workflows/winget.yml and active version releases suggests ongoing package distribution work and cross-platform release automation.

git clone https://github.com/mulaRahul/keyviz.git
cd keyviz
npm install
npm run tauri dev

Daily commands: Development: npm run dev (Vite dev server). Production build: npm run build && npx tauri build (outputs .msi, .dmg, or Linux binary to src-tauri/target/).

• src-tauri/src/main.rs — Entry point for the Tauri desktop application; initializes the event loop, window management, and system-level event hooks for keystroke and mouse tracking.
• src-tauri/src/app/state.rs — Manages application state including keyboard/mouse listeners, settings persistence, and real-time event distribution to the frontend.
• src-tauri/crates/rdev/src/lib.rs — Core abstraction for cross-platform input device monitoring; provides unified APIs for Windows, macOS, and Linux keystroke/mouse capture.
• src/App.tsx — Root React component orchestrating UI layout, settings panel, visualization canvas, and event listener subscriptions from Tauri backend.
• src/components/key-overlay.tsx — Primary visualization component rendering keystroke and mouse action overlays in real-time; handles positioning, animations, and custom keycap styles.
• src-tauri/src/app/commands.rs — Tauri IPC bridge exposing backend state and control methods to the React frontend (start/stop listeners, load/save settings).
• tauri.conf.json — Central Tauri configuration defining window bounds, plugin permissions, security capabilities, and platform-specific settings.

Add a new keycap style variant

1. Create a new component file in src/components/keycaps/ (e.g., src/components/keycaps/neon.tsx) exporting a React component that renders keycap elements with custom styling. (src/components/keycaps/neon.tsx)
2. Import and export the new component from src/components/keycaps/index.tsx and add it to the keycap factory function. (src/components/keycaps/index.tsx)
3. Update the settings panel in src/components/custom-filter.tsx to include a radio option for the new keycap style. (src/components/custom-filter.tsx)
4. Update src/App.tsx to pass the selected style state to the key-overlay component and render the chosen variant. (src/App.tsx)

Add a new input event filter option

1. Define a new filter enum variant in src-tauri/src/app/event.rs alongside existing event types. (src-tauri/src/app/event.rs)
2. Add filter logic in src-tauri/src/app/state.rs to check whether an event matches the new filter before broadcasting. (src-tauri/src/app/state.rs)
3. Expose a new Tauri command in src-tauri/src/app/commands.rs to toggle the filter (e.g., set_filter_mouse_only). (src-tauri/src/app/commands.rs)
4. Add a UI checkbox or toggle in src/components/custom-filter.tsx that invokes the backend command on change. (src/components/custom-filter.tsx)

Support a new operating system (e.g., Android mock for testing)

1. Create a new platform module directory src-tauri/crates/rdev/src/android/ with listen.rs, keyboard.rs, and simulate.rs matching the interface. (src-tauri/crates/rdev/src/android/mod.rs)
2. Add platform-specific keycode mappings in src-tauri/crates/rdev/src/keycodes/android.rs. (src-tauri/crates/rdev/src/keycodes/android.rs)
3. Update src-tauri/crates/rdev/src/lib.rs to conditionally compile and expose the new platform via cfg(target_os = ...). (src-tauri/crates/rdev/src/lib.rs)
4. Add Android-specific build flags in src-tauri/Cargo.toml if required (features, optional dependencies). (src-tauri/Cargo.toml)

• Tauri (Rust + WebView) — Provides lightweight, native desktop apps with OS-level input hook access; React UI with system integration without Electron overhead.
• rdev (custom Rust crate) — Unified cross-platform keyboard/mouse event capture via native OS APIs (Windows WinAPI, macOS CoreGraphics, Linux X11); no kernel drivers needed.
• React + TypeScript — Declarative, component-based UI with strong typing; seamless real-time event rendering and animation via React state/hooks.
• Tailwind CSS + Ark UI — Utility-first styling and accessible component primitives for rapid UI iteration and consistent design system.
• Tauri Store Plugin — Persistent JSON-backed settings storage (keycap style, filters, window position) without embedding a database.

• Unified event type in rdev instead of platform-specific types

  • Why: Simplifies frontend logic and reduces conditional code; single visualization layer works across all OSs.
  • Consequence: Some platform-specific event data (e.g., keyboard scan codes) is lost; may limit advanced use cases like raw key disambiguation.

• IPC-driven architecture vs. shared memory or file sockets

  • Why: Tauri IPC is secure, sandboxed, and type-safe; reduces ceremony for command/event passing.
  • Consequence: Slight latency overhead (~1–5ms per event round-trip); not suitable for ultra-low-latency gaming overlays but acceptable for visualization.

• Custom rdev crate instead of using external input libraries

  • Why: Full control over keycode mappings and event filtering; no reliance on third-party API stability.
  • Consequence: Higher maintenance burden for platform-specific OS API changes; must update Windows WinAPI, macOS CoreGraphics, and Linux X11 bindings independently.

• Browser-based UI renderer (WebView) instead of native window toolkit

  • Why: Rapid iteration, CSS animations, responsive design; familiar web tech stack for most contributors.
  • Consequence: Slightly higher memory footprint than native Cocoa/WinUI; potential rendering jank on very low-end hardware.

• Linux support (README explicitly lists Windows | macOS only; Linux platform files in rdev are archived/unmaintained)
• Network/cloud synchronization of keystroke logs (purely local visualization)
• Keystroke recording or macro playback (rdev.simulate() exists but is not used by the app)
• Real-time analytics or heatmaps of key usage patterns
• Integration with streaming platforms (OBS, YouTube) via plugin SDKs

macOS permissions: Keyviz requires Input Monitoring + Accessibility permissions enabled in System Settings > Privacy & Security; without these, input capture will silently fail. Linux x11-only: Wayland support is not present; users on Wayland desktops will not be able to capture inputs. Platform keycode tables: The keycodes modules (windows.rs, macos.rs, linux.rs, usb_hid.rs) must be kept in sync; adding a new key without updating all platform tables will cause mismatches. Tauri IPC overhead: Real-time input events crossing the Rust→JavaScript bridge may incur latency; high-frequency mouse movement events could cause frame rate issues if not debounced.

• X11 Input Event Interception — Keyviz's Linux support relies on X11 event grabbing (src-tauri/crates/rdev/src/linux/grab.rs) to intercept keystrokes before the window manager sees them; understanding X11's event model and XInput2 API is needed to debug or extend Linux support
• Virtual Keycode Translation (Keysym → Platform-Specific Codes) — Keyviz maintains multiple keycode tables (USB HID, Windows VK_*, macOS virtual keycodes, Linux X11 keysyms) to normalize input across platforms; misalignment between these tables causes keys to display incorrectly, making this the highest-risk area for platform-specific bugs
• Tauri IPC (Inter-Process Communication) and Capability-Based Security — Keyviz uses Tauri's invoke() to call Rust functions from React, gated by capabilities in default.json; understanding this trust boundary is critical for adding new native features without breaking security isolation
• Desktop Window Overlay Rendering — The visualization runs as an always-on-top transparent window; cross-platform window stacking (z-order), transparency, and event passthrough (so clicks don't get intercepted) are non-obvious implementation details handled by Tauri and platform-specific Rust code
• React + Zustand State Management for Rapid Input Events — With keyboard/mouse events firing 50–1000+ times per second, React re-renders must be optimized; zustand (immutable state store) + motion (animation library) must handle high-frequency updates without blocking the UI thread, making memoization and event debouncing essential
• Accessibility and Input Monitoring Permissions (macOS/Windows) — Modern OSes require explicit user consent to capture input; Keyviz must request and check permissions at runtime (src-tauri/crates/rdev/src/macos/keyboard.rs handles this), and silently failing if denied leads to confusing UX
• Tailwind CSS + Vite HMR for Real-Time Styling — Keyviz uses Tailwind 4 with @tailwindcss/vite plugin for zero-config styling; the visualization's colors, sizes, and animations are entirely CSS-driven, allowing non-coders to customize via the settings UI without touching TypeScript

• rdev/rdev — The original upstream library that Keyviz vendored a fork of in src-tauri/crates/rdev; tracks platform input event APIs and keycodes
• tauri-apps/tauri — The desktop framework and IPC system that Keyviz uses to bridge Rust backend and React frontend; understanding Tauri plugins and capabilities is essential for modifying permissions or adding new native APIs
• screego/screego — Alternative open-source screen sharing tool with similar input visualization needs; reference for how to handle cross-platform input capture reliably
• obsproject/obs-studio — Industry-standard streaming software that also captures and displays on-screen indicators for inputs; architectural patterns and performance solutions for real-time visualization are relevant

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 GitHub Actions workflow for Rust/Tauri backend testing and linting

The repo has Tauri backend code in src-tauri/ with Rust crates (especially the custom rdev crate for keyboard/mouse input), but only winget.yml exists in .github/workflows/. There's no CI pipeline to test the Rust code, validate builds, or lint Cargo.toml files. This is critical for a tool that handles system input events across Windows/macOS/Linux.

• [ ] Create .github/workflows/rust.yml to run 'cargo test' and 'cargo clippy' on src-tauri/ changes
• [ ] Add platform matrix for Windows and macOS (matching .vscode/extensions.json and platform support badge)
• [ ] Validate that Tauri builds successfully for both platforms
• [ ] Test the custom rdev crate independently since it has platform-specific implementations in src-tauri/crates/rdev/src/{windows,macos,linux}/

Add GitHub Actions workflow for Node/TypeScript frontend testing and type checking

The package.json shows a complex React + Tauri setup with TypeScript, but there's no CI for the frontend code. With dependencies like @ark-ui/react, @tauri-apps/api, and Tailwind, the build process needs validation. Currently only 'build' script exists but no tests or comprehensive linting in CI.

• [ ] Create .github/workflows/frontend.yml to run 'npm run build' and 'tsc --noEmit' for type checking
• [ ] Add Node.js version matrix (likely 18+ based on package.json patterns)
• [ ] Optionally add ESLint or Prettier checks if .eslintrc or .prettierrc exist in the repo root
• [ ] Ensure the workflow triggers on PRs to catch build breakage early

Add platform-specific capability validation for Tauri security model

The repo contains src-tauri/capabilities/default.json (visible in file structure) which defines Tauri's security model. Given that keyviz captures global keyboard/mouse input across multiple platforms, there's risk of overly permissive capabilities. A test or validation script should verify capabilities match actual plugin usage (@tauri-apps/plugin-{dialog,fs,opener,os,store}).

• [ ] Create src-tauri/capabilities/validate.rs or a build.rs enhancement to parse default.json and verify used plugins match declared capabilities
• [ ] Document which Tauri plugins require which capabilities in src-tauri/capabilities/README.md (currently missing)
• [ ] Add a pre-commit hook or test that fails the build if a new plugin is added to Cargo.toml without updating capabilities/default.json
• [ ] Reference the cross-platform keyboard/mouse handling in src-tauri/crates/rdev/src/{windows,macos,linux}/ to ensure capabilities cover all platforms

• Add unit tests to src-tauri/crates/rdev/src/keycodes/mod.rs covering keycode translation for a specific platform (e.g., test that Windows VK_LSHIFT maps correctly to the Shift variant); no test files currently exist.
• Document the architecture and data flow of input event capture in a CONTRIBUTING.md file, explaining how a keystroke flows from OS listener (linux/listen.rs) through rdev/lib.rs to the Tauri IPC bridge; helps future contributors understand the stack.
• Add a TypeScript type definition or JSDoc comments to the Tauri invoke calls in src/ for the input event schema (key name, timestamp, modifiers, mouse x/y) so frontend developers know the shape of data coming from Rust.

• High · Keyboard and Mouse Input Capture - Privacy Risk — src-tauri/crates/rdev/src/lib.rs, src-tauri/crates/rdev/src/*/listen.rs. The application uses rdev crate (custom implementation in src-tauri/crates/rdev/) to capture all keyboard and mouse inputs in real-time across multiple platforms (Windows, macOS, Linux). This creates significant privacy and security risks. Even though the tool is designed for visualization, keystroke logging capabilities could be misused to capture sensitive information like passwords, credentials, or private messages if not properly restricted or user-aware. Fix: 1) Implement robust user consent mechanisms with clear warnings about input capture. 2) Add user-configurable allowlist/blocklist for applications or windows to exclude sensitive contexts. 3) Implement secure credential detection to avoid logging sensitive fields. 4) Consider implementing a secure audit log of what was captured. 5) Add transparency about data retention and handling.
• High · Missing Security Headers and Capabilities Configuration — src-tauri/capabilities/default.json. The Tauri capabilities file (src-tauri/capabilities/default.json) appears to grant permissions for the application to interact with system-level input devices. Without examining the exact capability definitions, there's a risk of over-privileged permissions. Tauri requires explicit capability configuration, and improper setup could allow unauthorized access to input devices or sensitive system functions. Fix: 1) Review and audit all capabilities in default.json to follow principle of least privilege. 2) Remove any unnecessary permissions. 3) Implement scope restrictions where possible. 4) Document why each permission is required. 5) Consider using separate capability sets for different features.
• Medium · No Visible Input Sanitization or XSS Protection — src/. The application uses React with multiple UI frameworks (shadcn, Ark UI, Base UI, Radix UI) that handle rendering. However, without visible input validation or sanitization in the file structure, there's a risk of XSS vulnerabilities if user-provided data or captured inputs are rendered without proper escaping, especially in the visualization components. Fix: 1) Implement comprehensive input validation and sanitization for all user inputs. 2) Use React's built-in XSS protections consistently. 3) Avoid dangerouslySetInnerHTML unless absolutely necessary. 4) Validate and sanitize captured keystroke data before rendering. 5) Implement Content Security Policy (CSP) headers in the Tauri configuration.
• Medium · Data Storage Without Encryption — @tauri-apps/plugin-store dependency, src-tauri/src/app/state.rs. The application uses @tauri-apps/plugin-store for data persistence. Captured keystroke data, user preferences, and potentially sensitive information may be stored without encryption. If this data includes keystroke sequences or timing information, it could be extracted if the device is compromised. Fix: 1) Implement encryption for all stored data, especially keystroke recordings. 2) Use platform-specific secure storage (Keychain on macOS, Credential Manager on Windows). 3) Implement data expiration policies. 4) Add secure deletion mechanisms. 5) Document all data retention policies to users.
• Medium · Potential Supply Chain Risk - Multiple Unversioned Dependencies — package.json, src-tauri/Cargo.toml. While most dependencies specify versions, the heavy reliance on Tauri ecosystem packages (@tauri-apps/*) creates a centralized supply chain risk. Additionally, the custom rdev crate implementation in the repo bypasses standard vulnerability scanning that would occur with published crates. Fix: 1) Pin all dependency versions to specific releases (avoid ^ and ~ unless absolutely necessary). 2) Implement dependency scanning tools in CI/CD pipeline. 3) Regular security audits of dependencies (npm audit, cargo audit). 4) Use lock files consistently. 5) Consider security reviews of the custom rdev implementation.
• Medium · Platform-Specific Input Capture Without Elevation Warnings — src-tauri/src/*/listen.rs, src-tauri/src/main.rs. The application captures system-wide keyboard and mouse input, which may require elevated privileges on some platforms. There's no visible indication in the file structure of how privilege escalation is handled, whether users are warned, or if there are safeguards against unauthorized escalation. Fix: 1) Implement clear user prompts when elevated privileges are required. 2) Document privilege requirements per platform. 3) Implement integrity verification

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

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

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/mulaRahul/keyviz 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.

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

What it runs against: a local clone of mulaRahul/keyviz — 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 mulaRahul/keyviz | 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 main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 70 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of mulaRahul/keyviz. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/mulaRahul/keyviz.git
#   cd keyviz
#
# 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 mulaRahul/keyviz and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "mulaRahul/keyviz(\\.git)?\\b" \\
  && ok "origin remote is mulaRahul/keyviz" \\
  || miss "origin remote is not mulaRahul/keyviz (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 main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "src-tauri/src/main.rs" \\
  && ok "src-tauri/src/main.rs" \\
  || miss "missing critical file: src-tauri/src/main.rs"
test -f "src-tauri/src/app/state.rs" \\
  && ok "src-tauri/src/app/state.rs" \\
  || miss "missing critical file: src-tauri/src/app/state.rs"
test -f "src-tauri/crates/rdev/src/lib.rs" \\
  && ok "src-tauri/crates/rdev/src/lib.rs" \\
  || miss "missing critical file: src-tauri/crates/rdev/src/lib.rs"
test -f "src/App.tsx" \\
  && ok "src/App.tsx" \\
  || miss "missing critical file: src/App.tsx"
test -f "src/components/key-overlay.tsx" \\
  && ok "src/components/key-overlay.tsx" \\
  || miss "missing critical file: src/components/key-overlay.tsx"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 70 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~40d)"
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/mulaRahul/keyviz"
  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).

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