KeyForge

Minimalist Dark Titanium Keyboard & Mouse Macro Studio, Auto-Clicker & Input Recorder.
Free, Open-Source (GPL-3.0), Cybersecurity-Hardened, and Native for Windows, macOS & Linux — with Zero Browser Bloat.

Download v1.3.0 • Visual Tour • Setup Installer & Updater • Quick-Forge DSL • Cybersecurity • CLI & Source

---

Studio Workspace at a Glance

_{Studio Mode (v1.3.0) — Custom saved presets library (+ Preset), pre-start countdown selector (0s–5s), always-on-top Mini HUD toggle, live Quick-Forge DSL bar, color-coded visual timeline cards, and hardware Panic Stop (F12).}

---

Visual Tour

Dual Workspaces: Simple & Studio

KeyForge adapts smoothly from beginner one-click automation to full multi-step macro engineering without forcing complex timelines onto everyday users.

Everyday Automation in One Screen Two Live Modes: Toggle between Simple (Auto-Clicker, Key Spammer, Quick Sequence) and Studio (full visual timeline) with live bidirectional profile syncing. Pre-Start Countdown Timer: Choose a 0s, 1s, 3s, or 5s Start Delay so you have time to focus your target game or app window before inputs begin. Custom Presets Library: Save your favorite Simple or Studio setups with + Preset into the top preset selector across restarts. Built for Older & Low-RAM PCs: Native CustomTkinter + Pillow UI with zero Chromium/WebView runtime overhead and responsive 1280×720 High-DPI sizing.

Floating Mini-HUD & Setup Installer Wizard

Compact Always-on-Top Mini-HUD Click Mini HUD in the header bar to collapse KeyForge into a slim floating control pill that stays above games or desktop workflows with live cycle telemetry, Start/Stop (F6), Panic (F12), and one-click Expand.

Windows Setup Installer & Uninstaller Run KeyForge-Setup-Windows-x64.exe to install per-user without admin UAC prompts, create Desktop & Start Menu shortcuts, register Windows Uninstall cleanly, and keep configs & saved macros safe on uninstall unless opted out.

Modal Step Editor & Cryptographic In-App Updater

Precision Step Inspector Double-click any step (or click Edit) to configure key holds, click modes, relative pixel deltas, nested Repeat loops, or capture live cursor coordinates with Pick XY.

Startup Check & SHA-256 Auto-Updater Checks GitHub Releases cleanly on launch, displays release notes and SHA-256 status, verifies downloads via SHA256SUMS.txt (hmac.compare_digest), and upgrades binaries in-place while keeping every setting and macro intact.

Built-In Static Security Audit & Integrity Verification

_{Live Security Inspector Tab — Displays the active profile's canonical SHA-256 integrity digest, complexity budget counters, and real-time KF-SEC-001..005 static safety checks.}

---

Download Standalone Executables

Every tagged release is compiled, tested on Python 3.11–3.13 across all OS targets, and published by GitHub Actions alongside individual checksums and a combined SHA256SUMS.txt:

Operating System	Variant	Standalone Binary	Checksum Manifest
Windows 10 / 11 (x64)	Setup Installer (Shortcuts + Uninstaller)	KeyForge-Setup-Windows-x64.exe	KeyForge-Setup-Windows-x64.sha256.txt
Windows 10 / 11 (x64)	Portable Single-File	KeyForge-Windows-x64.exe	KeyForge-Windows-x64.sha256.txt
macOS (arm64)	Apple Silicon Standalone	KeyForge-macOS-arm64	KeyForge-macOS-arm64.sha256.txt
Linux (x86_64)	Standalone ELF Binary	KeyForge-Linux-x64	KeyForge-Linux-x64.sha256.txt

Verify Binary Checksum Before Running (Optional)

# Windows (PowerShell)
Get-FileHash .\KeyForge-Setup-Windows-x64.exe -Algorithm SHA256
Get-FileHash .\KeyForge-Windows-x64.exe -Algorithm SHA256

# macOS
shasum -a 256 KeyForge-macOS-arm64 && chmod +x KeyForge-macOS-arm64

# Linux
sha256sum -c KeyForge-Linux-x64.sha256.txt && chmod +x KeyForge-Linux-x64

---

Windows Setup Installer & Auto-Updater

Safe Setup & Uninstaller (Preserves User Data by Default)

• Zero-Elevation Per-User Install: Installs to %LOCALAPPDATA%\Programs\KeyForge\KeyForge.exe, creates optional Desktop & Start Menu shortcuts, and registers KeyForge in Windows Apps & Features (HKCU\...\Uninstall\KeyForge).
• Uninstall Without Data Loss: Running Uninstall leaves your %APPDATA%\KeyForge configuration, custom presets, and saved active macro profile untouched by default unless you explicitly opt in to delete them (--purge-data).
• Silent CLI Support: Both Setup and Uninstall support headless flags (--install --silent and --uninstall --silent [--purge-data]).

Auto-Updater & Persistent Configuration

When you upgrade KeyForge from inside the app or launch a newer standalone binary, your hotkeys, UI mode, Auto-Clicker / Key Spammer sliders, start delay, custom presets, window geometry, and active macro profile stay completely intact.

• Startup Release Check: Background check on startup notifies you cleanly via a dismissible header banner and the Updates pill when a newer release exists on GitHub (can be toggled anytime with Check for updates on startup).
• Strict Transport & Hash Verification: Enforces HTTPS-only GitHub redirects, matches portable binaries cleanly without confusing them for installers, streams downloads atomically with progress reporting, and rejects any download whose SHA-256 fails constant-time comparison against SHA256SUMS.txt / .sha256.txt.
• Crash-Safe Config, Custom Presets & Profile Storage (atomic fsync + .bak fallback; overridable via KEYFORGE_CONFIG_DIR):

Platform	Configuration Directory	Stored Files
Windows	%APPDATA%\KeyForge	config.json, active_profile.kfmacro.json (+ .bak), presets/
macOS	~/Library/Application Support/KeyForge	config.json, active_profile.kfmacro.json (+ .bak), presets/
Linux / BSD	$XDG_CONFIG_HOME/KeyForge (or ~/.config/KeyForge)	config.json, active_profile.kfmacro.json (+ .bak), presets/

---

Why KeyForge?

Many desktop macro tools force a trade-off between usability, transparency, and safety:

Feature / Guarantee	KeyForge (GPL-3.0)	TinyTask	AutoHotkey	Paid Macro Tools
100% Free & Open Source	✅ Yes	❌ Closed binary	✅ Yes	❌ Paywalls / Trials
Beginner Auto-Clicker + Visual Studio	✅ Dual UI Modes	❌ Record-only blob	❌ Scripts only	⚠️ Often split tiers
One-Line Quick-Forge Recipe Bar	✅ Press E -> Wait 200ms -> Click	❌ No	❌ Manual script	❌ No
Humanized Random Jitter (±ms)	✅ Built into Wait steps	❌ Fixed delays	⚠️ Manual Random()	❌ Rare
Auto-Release Stuck Keys on Abort	✅ EmergencyInputSanitizer	❌ Leaves Shift/Ctrl stuck	❌ Manual cleanup	⚠️ Unreliable
SHA-256 Signed Profiles + Static Auditor	✅ Yes (KF-SEC-001..005)	❌ Unverified binary blobs	❌ Arbitrary execution	❌ Closed format
In-App Verified Updater + Config Sync	✅ HTTPS + SHA-256	❌ None	⚠️ External installer	⚠️ Telemetry-heavy
Cross-Platform Native Binaries	✅ Windows, macOS & Linux	⚠️ Windows only	⚠️ Windows only	⚠️ Windows only

---

Quick-Forge Recipe DSL Reference

Type or paste human-readable macro recipes directly into the Quick-Forge bar and press Enter (or click Replace / + Append):

Action	Quick-Forge Syntax Examples	Description
Key Tap	Press E • Press Space • Press 1 (hold 40ms)	Presses and releases a key with configurable hold time
Modifier Combo	Press Ctrl+Shift+E • Press Alt+F	Holds modifiers in order, taps primary key, releases in reverse
Key Hold / Release	KeyDown Shift • KeyUp Shift	Explicit key state transitions (auto-sanitized on stop)
Mouse Click	Click • Click Right • DoubleClick Left at (640, 480)	Single, double, down, or up click at live cursor or fixed (X, Y)
Mouse Move	Move (500, 500) • Move (+120, -40) rel	Absolute screen coordinates or relative pixel delta
Mouse Scroll	Scroll -3 • Scroll +5	Vertical (+Up / -Down) mouse wheel scrolling
Wait + Jitter	Wait 200ms • Wait 150ms ±20ms • Wait 1.5s	High-precision interruptible sleep with optional humanization jitter
Nested Repeat	Repeat 3 { Press F -> Wait 120ms ±15ms } -> Click	Repeats an inner sequence N times inside the main macro loop

Live Input Recorder (F7) & Hardware Panic Kill-Switch (F12)

• Live Recorder (F7): Records real-time keyboard and mouse inputs into editable timeline cards, automatically coalesces KeyDown + KeyUp taps, and filters out KeyForge's own 0x4B465247 ("KFRG") synthetic injection marker and active hotkeys.
• Panic Kill-Switch (F12): Interrupts running macros immediately — even mid-Wait — and invokes EmergencyInputSanitizer to dispatch matching KeyUp / MouseUp events in reverse order so Shift, Ctrl, or mouse buttons never stay stuck down.

---

Cybersecurity & Safety Engineering

KeyForge is built with defensive local and supply-chain safeguards documented in SECURITY.md:

1. Declarative JSON Profiles (Zero eval / exec / pickle): .kfmacro.json files validate strictly against allowlists, bounds, and types in keyforge/security/validator.py, rejecting NaN/Infinity, boolean-as-integer confusion, path traversal, NTFS ADS (:), and reserved device names (CON, NUL, COM1).
2. Canonical SHA-256 Signing: Profiles embed an integrity_sha256 digest verified via constant-time hmac.compare_digest in keyforge/security/integrity.py.
3. Anti-DoS Complexity Budgets: Caps MAX_PROFILE_FILE_BYTES = 1 MiB, MAX_TOTAL_STEPS = 5,000, MAX_NESTING_DEPTH = 5, MAX_EXPANDED_OPS_PER_CYCLE = 100,000, plus a 5ms minimum inter-cycle flood governor.
4. Built-In Static Security Auditor (keyforge/security/auditor.py):

Rule Code	Severity	Security & Safety Check
KF-SEC-001	WARNING	Detects zero-wait infinite loops and confirms the 5ms anti-flood governor is active
KF-SEC-002	WARNING	Detects unbalanced KeyDown / MouseDown actions without matching release steps
KF-SEC-003	CRITICAL	Flags suspicious shell/system shortcuts (Win+R, Win+X, Alt+F4), including split KeyDown RWin -> Press R sequences
KF-SEC-004	WARNING	Flags extreme mouse click rates (> 100 CPS)
KF-SEC-005	WARNING	Flags empty sequences or profiles where every step is disabled

---

Architecture & Repository Layout

flowchart LR
    UI["KeyForge GUI<br/>(Simple + Studio)"] --> DSL["Quick-Forge DSL<br/>(keyforge.models.dsl)"]
    UI --> SEC["Security Layer<br/>(Validator + SHA-256 + Auditor)"]
    UI --> UPD["Auto-Updater + Config<br/>(updater.py + config.py)"]
    UI --> EXEC["MacroExecutor<br/>(keyforge.engine.executor)"]
    UI --> REC["MacroRecorder<br/>(keyforge.engine.recorder)"]
    HK["GlobalHotkeyManager<br/>(F6 Run / F7 Rec / F12 Panic)"] --> EXEC
    HK --> REC
    EXEC --> SAN["EmergencyInputSanitizer<br/>(Auto-Release Ledger)"]
    SAN --> WIN32["Win32InputBackend<br/>(user32.SendInput 64-bit)"]
    SAN --> DRY["DryRunBackend<br/>(Cross-Platform Simulator)"]

Loading

KeyForge/
├── .github/workflows/ci.yml      # Multi-OS Test, Audit, PyInstaller Build & Release Pipeline
├── docs/screenshots/             # README Desktop Interface & Dialog Screenshots
├── keyforge/
│   ├── assets/                   # Bundled App Icon Assets (icon.png, icon.ico)
│   ├── engine/
│   │   ├── backend.py            # InputBackend ABC, DryRunBackend & EmergencyInputSanitizer
│   │   ├── executor.py           # Interruptible MacroExecutor & Live Telemetry
│   │   ├── hotkeys.py            # Global Hotkey Polling Thread (F6 / F7 / F12)
│   │   ├── recorder.py           # Live Input Recorder with Tap Coalescing & Self-Filter
│   │   └── win32_input.py        # 64-bit Win32 SendInput + Cross-Platform Fallback
│   ├── models/
│   │   ├── action.py             # MacroAction Dataclass, ActionType & Validation
│   │   ├── dsl.py                # Quick-Forge Recipe Parser & Formatter
│   │   ├── keymap.py             # Virtual-Key (VK) & Hardware Scan-Code Registry
│   │   └── profile.py            # MacroProfile & Built-In Presets
│   ├── security/
│   │   ├── auditor.py            # Static Security & Safety Analyzer (KF-SEC-001..005)
│   │   ├── integrity.py          # Canonical SHA-256 Signing & Constant-Time Verification
│   │   └── validator.py          # Allowlist Schema, Path & Complexity Budget Validator
│   ├── ui/
│   │   ├── app.py                # Dual Simple/Studio Dark Titanium Desktop GUI
│   │   ├── installer_dialog.py   # Dark Titanium Windows Setup & Uninstaller Wizard
│   │   ├── mini_hud.py           # Always-on-Top Floating Compact Control Pill
│   │   ├── step_dialog.py        # Modal Step Inspector with Live Pick XY Capture
│   │   ├── theme.py              # Dark Titanium Palette, High-DPI & Window Helpers
│   │   └── update_dialog.py      # SHA-256 Verified GitHub Releases Update Sheet
│   ├── config.py                 # Crash-Safe Config, Custom Presets & Active Profile Backup
│   ├── installer.py              # Per-User Installer, Shortcuts & Uninstall Registry Manager
│   ├── main.py                   # Setup Wizard, CLI & Desktop GUI Entry Point
│   └── updater.py                # SemVer Client, SHA-256 Verifier & Atomic Hot-Swapper
├── scripts/build_exe.py          # Cross-Platform PyInstaller Compiler + SHA-256 Generator
└── tests/                        # Unit, Security, Updater, Config, Engine, CLI & UI Tests

---

Installation & Quick Start

Run from Source

git clone https://github.com/efeartn/KeyForge.git
cd KeyForge
pip install -e ".[dev]"

# Launch KeyForge Desktop GUI
python -m keyforge

Command-Line Interface (CLI)

# Check installed version
python -m keyforge --version

# Simulate a Quick-Forge recipe in safe Dry-Run mode (no live OS inputs)
python -m keyforge --expr "Press E -> Wait 200ms -> Click -> Press 1" --repeat 3 --dry-run

# Export the signed starter profile
python -m keyforge --export-default my_combo.kfmacro.json

# Run the static security & safety audit on a saved profile
python -m keyforge --profile my_combo.kfmacro.json --audit

# Execute a saved profile with live OS injection
python -m keyforge --profile my_combo.kfmacro.json

# Launch Setup / Install / Uninstall workflows
python -m keyforge --setup
python -m keyforge --install --silent
python -m keyforge --uninstall --silent

Compile a Standalone Binary & Run Tests

# Build single-file executable + .sha256.txt manifest under dist/
pip install pyinstaller
python scripts/build_exe.py

# Run test suite, coverage, lint & formatting checks
python -m pytest --cov=keyforge --cov-report=term-missing
python -m ruff check keyforge tests scripts
python -m ruff format --check keyforge tests scripts

---

License & Security Policy

• License: Distributed under the GNU General Public License v3.0.
• Security Policy: See SECURITY.md for architecture threat models, auto-updater verification details, and vulnerability disclosure guidelines.