Skip to content
efeartnPublic

Repository files navigation

KeyForge Studio Logo

KeyForge

Precision Obsidian & Mint Emerald Keyboard & Macro Sequence Studio & Live Input Recorder.
Free, Open-Source (GPL-3.0), Cybersecurity-Hardened, and Native for Windows, macOS & Linux — with Zero Browser Bloat.

CI & Release Compiler Latest Release Platform: Windows | macOS | Linux Python: 3.10+ Security: SHA-256 Signed + Static Auditor License: GPL-3.0

Download v1.5.0 • Release Notes • Visual Tour • Setup Installer & Updater • Sequence DSL • Cybersecurity • CLI & Source


Studio Workspace at a Glance

KeyForge Studio Mode Obsidian and Mint Emerald Desktop Interface
Studio Mode (v1.5.0) — Decluttered top utility header, 4-Card Hero Control Strip (Profile, Engine Telemetry, Hotkeys & Dry-Run, Delay & Start CTA), All Steps / Keys / Waits / Mouse filter pills with / quick search, aligned timeline cards, keyboard shortcuts (Del / Ctrl+D / Space / Alt+↑/↓), and compact Mini HUD.

Visual Tour

Dual Workspaces: Simple & Studio

KeyForge adapts smoothly from quick keyboard automation to full multi-step sequence engineering without forcing complex timelines onto everyday workflows — styled uniformly with deep charcoal-obsidian surfaces (#090C10 / #0E1319), hairline 1px borders, and a restrained Mint Emerald CTA (#2EE59D).

KeyForge Simple Mode Key Repeater and Control Center

Everyday Keyboard Automation

  • Two Synchronized Modes: Toggle cleanly between Simple (Key Repeater & Quick Sequence) and Studio (4-card hero strip + timeline) with live bidirectional profile sync.
  • Click-to-Bind Key Capture & Presets: Click Bind Key to capture any physical key or modifier combo (e.g. Ctrl+Shift+F), use speed presets (25ms–500ms), or save custom profiles via + Save Preset.
  • Fast Step Filtering & Shortcuts: Slice steps by Keys, Waits, or Mouse, press / to filter, and manage timeline rows via Del, Ctrl+D, Space, and Alt+↑/↓.
  • Low-Spec & Low-RAM Optimized: Pure CustomTkinter + Pillow UI with zero Chromium/WebView subprocess bloat, a warm 64-slot pooled timeline renderer, and dirty-checked telemetry (~44.6 MB Private RAM idle on Windows).

Floating Mini-HUD & Setup Installer Wizard


KeyForge Always-on-Top Compact Floating Mini-HUD Pill

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.

KeyForge v1.5.0 Setup Installer Wizard with Browse Button

Windows Setup Installer & Uninstaller
Run KeyForge-Setup-Windows-x64.exe to choose a destination with Browse..., install per-user without admin UAC prompts, create Desktop & Start Menu shortcuts, and preserve user configs & macros on uninstall unless opted out.

Modal Step Editor & Cryptographic In-App Updater

KeyForge Modal Action Step Editor with Bind Key Capture

Precision Step Inspector
Double-click any step (or click Edit) to configure readable action modes, capture keys directly with Bind Key, build nested Repeat loops, or capture live screen coordinates with Pick XY.

KeyForge SHA-256 Verified Software Update Sheet

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

KeyForge Static Security Audit Tab and SHA-256 Digest
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, Key Repeater interval, 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
Simple Key Repeater + Visual Studio ✅ Dual UI Modes ❌ Record-only blob ❌ Scripts only ⚠️ Often split tiers
One-Line Sequence DSL 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

Sequence DSL Reference

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

Action Sequence DSL 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                # Sequence DSL Parser & Formatter
│   │   ├── keymap.py             # Virtual-Key (VK), Scan-Code & Key Capture 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 Obsidian Desktop GUI & 4-Card Hero
│   │   ├── installer_dialog.py   # Windows Setup & Uninstaller Wizard with Browse...
│   │   ├── mini_hud.py           # Always-on-Top Floating Compact Control Pill
│   │   ├── step_dialog.py        # Modal Step Inspector with Bind Key & Pick XY Capture
│   │   ├── theme.py              # Obsidian/Emerald 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
├── RELEASE_NOTES.md              # Latest Release Notes (Published to GitHub Releases)
├── 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

Releases

Packages

Contributors

Languages