wrkflovv 0.1.3

Work Flow Simulator - Keystroke simulation tool for fraud detection research

wrkflovv

A keystroke simulation tool designed for fraud detection research. Simulates human-like typing behavior by automating the process of typing content from source files at realistic speeds with authentic behavioral patterns.

Features

• Realistic Typing Simulation - Variable WPM with human-like delays and variance
• Typo Simulation - Automatic typos with corrections using adjacent key mapping
• Burst Typing - Variable speed patterns within sessions
• Idle Periods - Simulated work interruptions for authentic behavior
• Dual Interface - Both interactive TUI and headless CLI modes
• Auto-Detection - Automatically finds source files in current directory
• File Selection - Select specific files to type using spacebar
• Live IDE Preview - Opens temp files in VS Code/IDE to watch typing in real-time
• Stealth Mode - Hide the TUI with a fake process list (F9)
• Persistent Configuration - Settings saved between sessions

Installation

Requirements

• Python 3.10 or higher
• Linux or Windows

Quick Install (One-liner)

curl -sSL https://raw.githubusercontent.com/Umar-Khan-Yousafzai/Workflovv-TUI/main/install.sh | bash

Install from PyPI (Recommended)

pip install wrkflovv

Install from GitHub (Latest)

pip install git+https://github.com/Umar-Khan-Yousafzai/Workflovv-TUI.git

Install from Source (Development)

# Clone the repository
git clone https://github.com/Umar-Khan-Yousafzai/Workflovv-TUI.git
cd Workflovv-TUI

# Install in editable mode
pip install -e .

# Or install normally
pip install .

Verify Installation

wrkflovv --version

Uninstall

pip uninstall wrkflovv

Quick Start

Interactive Mode (Recommended)

# Navigate to your project directory
cd /path/to/your/project

# Launch wrkflovv - it auto-detects files!
wrkflovv

Then in the TUI:

1. Use ↑/↓ to navigate the file list
2. Press SPACE to select files (or A for all)
3. Press ENTER to start typing!
4. Watch the magic in VS Code!

Headless Mode

# Run without TUI
wrkflovv run /path/to/file.py

---

Usage Modes

Interactive Mode (TUI)

Launch the full interactive terminal interface with real-time visualization.

wrkflovv

TUI Controls

Key	Action
F10	Start typing simulation
F2	Stop typing simulation
F3	Pause/Resume
F5	Refresh/rescan files in directory
F9	Toggle Stealth Mode
+ / =	Increase WPM by 5
-	Decrease WPM by 5
SPACE	Select/deselect file (in file list)
ENTER	Start typing (if files are selected)
A	Select all files
N	Deselect all files
Ctrl+C	Quit
Ctrl+Q	Quit

TUI Features

• Auto-Detection - Automatically scans current directory for source files on launch
• File Selection - Use SPACE to select which files to type (checkbox UI)
• Live IDE Preview - Creates temp file and opens in VS Code to watch typing live
• Header Bar - Shows app title, current status, active file, and live stats
• File List - Displays all detected files with selection checkboxes
• Typing Preview - Shows the last 500 characters being typed
• Status Bar - Progress bar, WPM display, and session statistics
• Stealth Mode - Press F9 to hide TUI and show fake system processes

Status Indicators

Status	Color	Meaning
TYPING	Green	Actively typing
PAUSED	Yellow	Simulation paused (manual)
USER	Orange	Paused - user takeover detected
IDLE	Yellow	Simulating work break
STOPPED	Red	Simulation stopped

IDE Integration

When you start typing (F10 or ENTER), wrkflovv will:

1. Create a temp file in the same directory as the source (e.g., .myfile_wrkflovv_tmp.py)
2. Open it in your IDE (auto-detects VS Code, Cursor, Sublime, etc.)
3. Update the file in real-time as characters are "typed"
4. Clean up temp files when the file is complete or simulation stops

This lets you watch the typing happen live in your editor!

Supported IDEs (auto-detected):

• VS Code (code)
• Cursor (cursor)
• VSCodium (codium)
• Sublime Text (subl)
• Atom (atom)
• Gedit, Vim, Neovim, Nano

Human-Like Behavior

wrkflovv simulates realistic developer typing patterns:

Spontaneous Speed Changes:

• WPM varies randomly between your min/max settings
• Sometimes fast (in the zone), sometimes slow (thinking)
• No predictable patterns - completely spontaneous

Random Pauses:

• Micro-pauses (0.2-0.5s) - brief hesitation
• Thinking pauses (0.5-1.5s) - considering what to type
• Distraction pauses (4-10s) - checking something
• Long pauses (10-30s) - phone/drink/stretch

Developer Habits:

• Ctrl+S - Saves frequently like a real dev
• Ctrl+Shift+I - Auto-formats code periodically
• Typos - Makes realistic typos and corrects them

Adjust WPM on the fly:

• Press + to increase WPM by 5
• Press - to decrease WPM by 5
• Default range: 60-85 WPM (realistic developer speed)
• Settings are saved automatically!

Auto-Pause on User Takeover

wrkflovv detects when you take over and automatically pauses:

Triggers:

• Any keyboard input (except control keys)
• Mouse clicks
• Significant mouse movement
• Mouse scroll

How it works:

1. You're typing along...
2. You click somewhere or start typing → AUTO-PAUSE
3. Status changes to "USER" (orange)
4. Make your changes
5. Press F10 to resume from exact position!

Resume:

• Press F10 to continue from where it paused
• Typing resumes at the exact character position
• No need to restart the file

Stealth Mode (F9)

Press F9 to toggle stealth mode, which:

• Hides the wrkflovv interface
• Shows a fake htop-like process list
• Typing continues in the background
• Press F9 again to return to normal view

Perfect for when someone walks by!

---

Headless Mode (CLI)

Run typing simulation without the TUI - perfect for scripting and automation.

wrkflovv run [OPTIONS] SOURCES...

Arguments

Argument	Description
SOURCES	One or more source files or directories to type from (required)

Options

Option	Default	Description
--output, -o	None	Output directory for typed files
--min-wpm	20	Minimum words per minute
--max-wpm	70	Maximum words per minute
--no-idle	False	Disable idle periods
--loop/--no-loop	True	Loop through files continuously

Examples

Basic usage:

# Type a single file
wrkflovv run myfile.py

# Type multiple files
wrkflovv run file1.py file2.js file3.ts

# Type all files in a directory
wrkflovv run ./src/

With options:

# Custom WPM range (faster typing)
wrkflovv run --min-wpm 40 --max-wpm 100 ./code/

# Disable idle periods for continuous typing
wrkflovv run --no-idle ./code/

# Single pass (no looping)
wrkflovv run --no-loop ./code/

# Specify output directory
wrkflovv run -o ./output/ ./code/

# Combined options
wrkflovv run --min-wpm 30 --max-wpm 80 --no-idle --no-loop ./src/

Stop the simulation:

Press Ctrl+C to stop

Session output:

Loading source files...
Loaded 5 files
Starting typing simulation...
Press Ctrl+C to stop

Typing: main.py
Done: main.py
Typing: utils.py
Idle for 45s...
Done: utils.py

Session Stats:
  Files typed: 2
  Characters: 3,450
  Lines: 128
  Session time: 245s

---

Configuration

View Current Configuration

wrkflovv config

Output:

Configuration

Config directory: /home/user/.wrkflovv

WPM Settings:
  Min WPM: 20
  Max WPM: 70

Idle Settings:
  Min idle: 30s
  Max idle: 300s
  Idle chance: 15.0%

Typing Behavior:
  Typo chance: 2.0%
  Burst typing: True

Source Files:
  - /path/to/file1.py
  - /path/to/file2.js

Configuration File

Settings are stored in ~/.wrkflovv/config.json:

{
  "min_wpm": 20,
  "max_wpm": 70,
  "min_idle": 30,
  "max_idle": 300,
  "idle_chance": 0.15,
  "typo_chance": 0.02,
  "burst_typing": true,
  "source_files": [
    "/path/to/file1.py",
    "/path/to/file2.js"
  ],
  "output_dir": ""
}

Configuration Options

Option	Type	Default	Description
min_wpm	int	60	Minimum typing speed (words per minute)
max_wpm	int	85	Maximum typing speed (words per minute)
min_idle	int	30	Minimum idle period in seconds
max_idle	int	300	Maximum idle period in seconds (5 min)
idle_chance	float	0.10	Probability of idle period after each file (10%)
typo_chance	float	0.015	Probability of making a typo (1.5%)
burst_typing	bool	true	Enable variable speed bursts
save_enabled	bool	true	Ctrl+S saving behavior
format_enabled	bool	true	Auto-formatting (Ctrl+Shift+I)
spontaneous_pauses	bool	true	Random thinking pauses
source_files	list	[]	Saved source file paths
output_dir	string	""	Default output directory

---

File Management

Add Source Files

# Add a single file
wrkflovv add myfile.py

# Add multiple files
wrkflovv add file1.py file2.js file3.ts

# Add a directory (all supported files)
wrkflovv add ./src/

# Add multiple paths
wrkflovv add ./src/ ./tests/ ./lib/

List Source Files

wrkflovv list-files

Output:

         Source Files
┏━━━┳━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━┓
┃ # ┃ File          ┃ Lines ┃ Chars ┃
┡━━━╇━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━┩
│ 1 │ main.py       │ 150   │ 4320  │
│ 2 │ utils.py      │ 89    │ 2150  │
│ 3 │ config.js     │ 45    │ 1200  │
└───┴───────────────┴───────┴───────┘

Total: 7,670 chars, 284 lines

Clear Source Files

wrkflovv clear

Supported File Types

The tool auto-detects common source code extensions:

.py .js .ts .jsx .tsx .java .cpp .c .h .hpp .go .rs .rb .php .swift .kt .scala .cs .vue .svelte .html .css .scss .sass .less .json .yaml .yml .xml .md .txt .sh .bash .zsh .sql

---

CLI Reference

wrkflovv [OPTIONS] COMMAND [ARGS]

Commands:
  run         Run typing simulation in headless mode (no TUI)
  config      Show current configuration
  add         Add source files to configuration
  clear       Clear all source files from configuration
  list-files  List configured source files

Options:
  --version, -v  Show version and exit
  --help         Show help message and exit

---

Examples

Research Workflow

# 1. Add your research dataset
wrkflovv add ./keystroke-samples/

# 2. View loaded files
wrkflovv list-files

# 3. Run simulation (headless for data collection)
wrkflovv run --min-wpm 25 --max-wpm 55 ./keystroke-samples/

# 4. Or use interactive mode for monitoring
wrkflovv

Continuous Simulation

# Run indefinitely with realistic behavior
wrkflovv run --loop ./code/

Fast Typing Simulation

# Higher WPM range, no breaks
wrkflovv run --min-wpm 60 --max-wpm 120 --no-idle ./code/

Single File Session

# Type one file and exit
wrkflovv run --no-loop important_file.py

---

Architecture

wrkflovv/
├── cli.py              # CLI entry point
├── app.py              # TUI application
├── core/
│   ├── typer_engine.py # Keystroke simulation
│   ├── file_manager.py # File handling
│   └── scheduler.py    # Session management
├── ui/
│   ├── theme.py        # TUI styling
│   ├── widgets/        # Custom widgets
│   └── views/          # View components
└── utils/
    └── config.py       # Configuration management

---

License

MIT License - See LICENSE file for details.

Author

Umer Farooq Khan ([e-mail])