FlowState

A realistic typing simulator that pastes clipboard content by "typing" it out with human-like imperfections.
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Option 1: Installer
   • Option 2: Manual Setup
3. Usage
4. Transparency
5. Roadmap
6. Contributing
7. License
8. Acknowledgments

About The Project

FlowState is a cross-platform typing simulator designed for intelligent humanlike autotyping. Unlike standard macro pastes that dump text instantly, FlowState simulates a human touch by incorporating:

• Natural Rhythm: Gaussian distribution for keystroke delays to avoid robotic patterns.
• Context Awareness: Faster typing on common bigrams and realistic pauses at punctuation.
• Intelligent Errors: Simulated mistakes determined by content, followed by realistic correction pauses.
• Cognitive Pauses: Random "thinking" moments and paragraph breaks.
• Per-App Profiles: Override typing settings per application (e.g., fast in Slack, careful in Google Docs).

(back to top)

Built With

• 
• 
• 
• 

(back to top)

Getting Started

FlowState has separate builds for Windows and macOS. Choose the method that works best for you.

Option 1: Download the Installer (Recommended)

Pre-built installers are available on the Releases page.

Platform	Download	What it does
Windows	FlowState_Windows_Setup.exe	Standard Windows installer (Inno Setup). Installs to Program Files, creates Start Menu & desktop shortcuts.
macOS	FlowState_Mac_Installer.dmg	Standard macOS disk image. Drag FlowState.app to your Applications folder.

Windows Note: FlowState requires Administrator to run because it uses global keyboard hooks (a Windows security requirement).

macOS Note: On first launch, macOS will ask you to grant Accessibility permission (System Settings → Privacy & Security → Accessibility). This is required for global hotkeys and is a standard Apple security prompt.

Option 2: Manual Setup (Clone / ZIP)

If you prefer to run from source, or you want to inspect exactly what FlowState does:

1. Clone the repo (or download the ZIP)

   git clone https://github.com/hammersurf1/FlowState.git
   cd FlowState

2. Run the setup script for your platform:

   Windows:

   setup_windows.bat

   macOS:

   chmod +x setup_mac.sh
   ./setup_mac.sh

   The setup scripts will:

   • Check that Python 3 is installed
   • Create a virtual environment in .venv/
   • Install dependencies from the platform-specific requirements file
   • Download the spaCy en_core_web_md model
   • Print clear instructions for running the app

3. Run FlowState:

   Windows (run as Administrator):

   .venv\Scripts\activate
   python src\main_win.py

   macOS:

   source .venv/bin/activate
   python3 src/main_mac.py

(back to top)

Usage

1. Copy text to your clipboard (Ctrl+C / Cmd+C).
2. Click into the target text field (in Chrome).
3. Press the trigger hotkey. A 3-second countdown lets you release the hotkey before typing starts.

Controls

Hotkey	Windows	macOS
Start / Pause / Resume	Ctrl+Alt+V	⌘+⌥+V
Pause immediately	Esc	Esc
Abort and reset	Esc (double-tap, <0.5s)	Esc (double-tap, <0.5s)
Cycle through settings	Ctrl+Shift+Alt+↑/↓	⌘+⇧+⌥+↑/↓
Adjust selected setting	Ctrl+Shift+Alt+→/←	⌘+⇧+⌥+→/←

Rich Text Formatting

FlowState can type with rich formatting (bold, italic, lists, headings, etc.) when Enable Rich Text is turned on in Settings. Use Markdown syntax in your clipboard text:

Syntax	Result	Shortcut sent
**text** or __text__	Bold	Ctrl/Cmd+B
*text* or _text_	Italic	Ctrl/Cmd+I
___text___	Underline	Ctrl/Cmd+U
~~text~~	Strikethrough	Alt+Shift+5 (Google Docs)
# Heading	Heading 1	Ctrl/Cmd+Alt+1
## Heading	Heading 2	Ctrl/Cmd+Alt+2
### Heading	Heading 3	Ctrl/Cmd+Alt+3
- item or * item	• Bullet list	Ctrl/Cmd+Shift+8
1. item	1. Numbered list	Ctrl/Cmd+Shift+7
- item (2 spaces)	→ Sub-bullet	Tab indent
\t- item (tab)	→ Sub-bullet	Tab indent

Example clipboard text:

# Meeting Notes

**Attendees:** Alice, Bob

## Agenda
- Intro
  - Welcome
- ~~Old item~~ (cancelled)
1. Action items
  1. Send report

Notes:

• Strikethrough (~~) works best in Google Docs (uses the Docs-specific Alt+Shift+5 shortcut).
• Sub-bullets and sub-numbers are created by indenting with 2 spaces or a tab.
• The target editor must support the standard Ctrl/Cmd shortcuts for formatting.

System tray HUD

The icon gives a live status readout. It shows the active setting's short name and current value.

Icon color	Meaning
🔵 Blue	Idle
🟢 Green	Typing / countdown
🟠 Orange	Paused

Semantic Humanization

FlowState uses spaCy with the en_core_web_md model to make typing feel genuinely human. These features can be toggled individually in Settings under the Semantic Humanization section:

Feature	What it does
Smart Revisions	Occasionally types a semantically similar word first, hesitates, backspaces, and types the correct word. Only triggers on nouns, verbs, and adjectives.
Semantic Speed	Adjusts typing speed based on word frequency. Common words (e.g., "the", "and") flow faster; rare words slow down slightly.
Entity Care	Named entities (people, companies, places) are typed with extra care — fewer typos and steadier rhythm.
Clause Pauses	Uses dependency parsing to insert micro-pauses at the end of subordinate clauses, not just at sentence boundaries.
Chunk Burst	Treats noun phrases like "the quarterly results" as a single cognitive burst, reducing hesitation inside the phrase.
Frequency Typos	Very common words get fewer typos; rare words get the full typo chance.
Deferred Corrections	Sometimes finishes the current word before backspacing a typo, just like a real person would.

Motor Realism

Beyond semantic understanding, FlowState models actual motor constraints:

Feature	What it does
Same-Finger Penalty	Slightly slower when the same finger types two consecutive keys.
Fluency States	Alternates between "in the zone" (low variance) and "stumbling" (higher variance) periods.
Number / Symbol Care	Digits and symbols are typed more deliberately with fewer typos.
Caps Lock Realism	Delay penalty applies only to the first capital in a run, not every capital letter.

(back to top)

Transparency

FlowState is fully open-source and designed to be transparent about what it does:

Why does it need Administrator / Accessibility permissions?

• Windows: The keyboard library requires Administrator to register global hotkeys. This is a Windows security policy — any app that listens for keystrokes system-wide needs elevated privileges.
• macOS: The pynput library requires Accessibility permission to register global hotkeys. This is Apple's standard security model — you enable it once in System Settings and it persists.

What does FlowState access?

• Your clipboard (to read the text you want typed)
• Your keyboard (to simulate keystrokes and listen for hotkeys)
• Google Chrome (connects via Chrome's debugging port to type into browser tabs)

What FlowState does NOT do:

• ❌ No network requests (except localhost to Chrome)
• ❌ No telemetry or analytics
• ❌ No data collection
• ❌ No registry/system modifications

The setup scripts echo every step they perform. The source code is MIT-licensed and fully auditable. The system is 100% local.

(back to top)

Roadmap

• Windows Support
• macOS Support
• Custom Macro Support
• Intelligent revision history w/ NLP
• Per-App Profiles
• Linux Driver Implementation

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

Top contributors:

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Acknowledgments

• Playwright
• pystray
• pynput
• keyboard library
• Best-README-Template

(back to top)