Typing Trainer

An AI-powered CLI typing trainer with personalized error analysis, built with React Ink and Google Gemini AI.

Features

• Real-time Typing Tests - Practice typing with instant visual feedback
• AI-Powered Analysis - Get personalized insights about your typing patterns using Google Gemini AI
• Adaptive Practice Mode - Focus on characters you struggle with most
• Progress Tracking - Track your WPM, accuracy, and improvement over time
• Persistent Statistics - Your progress is saved locally between sessions

Screenshots

Installation

Prerequisites

• Node.js 18.0.0 or higher
• npm or yarn

Setup

# Clone the repository
git clone git@github.com:trett/taip-trainer.git
cd taip-trainer

# Install dependencies
npm install

# Run the application
npm start

Setting up AI Analysis (Optional)

To enable AI-powered error analysis with Google Gemini:

1. Get a free API key from Google AI Studio
2. Set the environment variable:

# Temporary (current session)
export GEMINI_API_KEY="your_api_key_here"

# Permanent (add to your shell config)
echo 'export GEMINI_API_KEY="your_api_key_here"' >> ~/.zshrc
source ~/.zshrc

Usage

Starting the Application

npm start

Navigation

Use arrow keys to navigate menus and the following keys:

Key	Action
↑/↓	Navigate menu options
Enter	Select option
ESC	Go back / Exit
R	Retry test (from results)
S	View statistics (from results)
A	AI Analysis (from results)

Main Menu Options

1. Start New Test - Begin a typing test with random text
2. Practice Weak Characters - Practice with text targeting your problem areas
3. View Statistics - See your overall progress and trends
4. Exit - Quit the application

During a Typing Test

• Characters turn green when typed correctly
• Characters turn red when typed incorrectly
• Current position is highlighted in blue
• Live statistics show WPM, accuracy, errors, and time
• Visual progress bar shows completion status

After Completing a Test

• View your final WPM, accuracy, and error count
• Press R to retry with new text
• Press S to view your statistics
• Press A for AI-powered error analysis
• Press ESC to return to main menu

AI Error Analysis

When you press A after a test, Gemini AI analyzes your errors and provides:

• Error Patterns - Which characters you frequently mistype
• Likely Causes - Why you might be making these mistakes
• Practice Exercises - Custom sentences targeting your weak areas
• Improvement Tips - Actionable advice for better typing

Configuration

Data Storage

Your profile and statistics are stored in:

~/.typing-trainer/profile.json

Profile Data Includes

• Total tests completed
• Average WPM and accuracy
• Problem characters with error counts
• Last 20 test session history
• AI-generated practice texts

Project Structure

taip-trainer/
├── index.tsx              # Entry point
├── package.json           # Dependencies and scripts
├── README.md              # This file
└── src/
    ├── App.tsx            # Main application component
    ├── api/
    │   └── gemini.js      # Google Gemini AI integration
    ├── components/
    │   ├── Menu.tsx           # Main menu
    │   ├── TypingTest.tsx     # Core typing interface
    │   ├── PracticeMode.tsx   # Adaptive practice
    │   ├── Results.tsx        # Test results display
    │   ├── Statistics.tsx     # Progress statistics
    │   ├── ErrorAnalysis.tsx  # AI analysis display
    │   └── ProgressBar.tsx    # Visual progress components
    └── utils/
        ├── stats.js           # WPM/accuracy calculations
        ├── storage.js         # Profile persistence
        ├── textGenerator.js   # Sample texts
        └── analyzer.js        # Error pattern detection

Technical Details

Built With

• React - UI library
• Ink - React for CLI
• Google Generative AI - Gemini AI SDK
• tsx - TypeScript/JSX execution

Key Algorithms

WPM Calculation:

WPM = (characters / 5) / (seconds / 60)

Accuracy Calculation:

Accuracy = ((total - errors) / total) * 100

Scripts

npm start    # Run the application
npm run dev  # Run with watch mode (auto-restart on changes)

Troubleshooting

"Raw mode is not supported"

This error occurs when running in a non-interactive terminal. Make sure you're running in a proper terminal emulator, not through automation or piped input.

AI Analysis shows "Local analysis"

This means the Gemini API key is not set or there was an API error. Check:

1. GEMINI_API_KEY environment variable is set
2. API key is valid
3. Network connection is available

Profile not saving

Ensure the application has write permissions to your home directory. The profile is stored at ~/.typing-trainer/profile.json.

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

License

MIT License

Acknowledgments

• Powered by Google Gemini AI
• Built with Ink by Vadim Demedes