ghost-typer 0.1.0

A minimalist CLI for creating aesthetic code typing animations. Perfect for sharing code demos on social media with a clean, terminal-first look.

Ghost-Typer is a terminal demo tool that replays source code as if someone were typing it live. It is designed for polished screen recordings, short-form demos, and social media clips.

What it does

• Reads a source file and detects the language when possible.
• Replays the file character by character with human-like typing delays.
• Supports syntax highlighting with Rich and Pygments.
• Supports built-in Pygments themes and custom JSON themes.
• Detects special pause comments such as pause: 2s to add dramatic pauses.
• Offers both a classic command-line mode and an interactive setup wizard.

Requirements

• Python 3.13 or newer is recommended.
• A virtual environment is strongly recommended.

Install from a clone

git clone <repo-url>
cd ghost-typer
python -m venv venv

Windows PowerShell

.\venv\Scripts\Activate.ps1
pip install rich pygments colorama questionary

macOS / Linux

source venv/bin/activate
pip install rich pygments colorama questionary

If you prefer, you can also install the packages globally, but a virtual environment is the safest option.

Install from PyPI

When the package is published, install it with:

pip install ghost-typer

Run it from anywhere with:

ghost-typer --cli

Quick start

Interactive mode

The interactive wizard opens automatically when you run the tool with no extra CLI flags, or explicitly with --cli.

python ghost_typer.py

or

python ghost_typer.py --cli

If you start it with only a source file, it will also enter the interactive flow without asking for the file again:

python ghost_typer.py script.py

Classic CLI mode

If you pass additional options, Ghost-Typer uses the standard CLI flow.

python ghost_typer.py script.py --theme pygments:dracula --speed 1.2

How it works

Ghost-Typer can be used in two ways:

1. Interactive wizard

The wizard guides you through:

• choosing a theme
• choosing a lexer if needed
• configuring typing speed
• configuring delay ranges
• confirming whether to clear the screen before starting

This mode is designed to feel like a clean setup dashboard.

2. Direct command-line configuration

You can still pass parameters directly from the terminal for faster workflows, scripts, or automation.

Themes

Ghost-Typer supports two theme sources:

Built-in Pygments themes

Use the pygments: prefix:

python ghost_typer.py script.py --theme pygments:monokai
python ghost_typer.py script.py --theme pygments:dracula

Custom JSON themes

You can load a theme from a local JSON file or from a theme file inside the themes/ folder.

Examples:

python ghost_typer.py script.py --theme themes/Clancy\ Stealth.json
python ghost_typer.py script.py --theme themes/example-neon.json
python ghost_typer.py script.py --theme monokai

If the JSON theme lives inside themes/, you can use its name without the extension:

python ghost_typer.py script.py --theme example-neon

Theme catalog

List available built-in and local themes with:

python ghost_typer.py --list-themes

Custom theme format

A custom theme JSON can define:

• metadata
• terminal
• syntax
• ui
• typing_config

Example:

{
  "metadata": {
    "name": "Clancy Stealth",
    "author": "JoseDev",
    "version": "1.0"
  },
  "terminal": {
    "background": "#000000",
    "cursor_color": "#FFE700",
    "cursor_style": "block"
  },
  "syntax": {
    "keyword": "#FF0000",
    "string": "#FFE700",
    "function": "#FFFFFF"
  },
  "ui": {
    "header_color": "#FFE700",
    "border_color": "#FF0000"
  },
  "typing_config": {
    "base_speed": 0.05,
    "variance": 0.02,
    "line_pause_multiplier": 1.5
  }
}

Pause comments

Ghost-Typer can pause on special annotations inside the file:

# pause: 2s

Supported units:

• ms
• s
• m

CLI options

Core options

• file: source file to replay
• --theme: theme name, built-in Pygments theme, or JSON path
• --themes-dir: folder used to search local JSON themes
• --list-themes: print available themes and exit
• --cli: open the interactive wizard
• --language: force a lexer alias
• --no-clear: do not clear the screen before starting

Typing options

• --min-delay: minimum delay per character in milliseconds
• --max-delay: maximum delay per character in milliseconds
• --speed: speed multiplier
• --newline-multiplier: extra multiplier for newline pauses

Other options

• --cursor: visible cursor symbol in non-interactive mode

Examples

Replay a Python file with a built-in theme

python ghost_typer.py script.py --theme pygments:dracula

Replay a file using a local theme JSON

python ghost_typer.py script.py --theme themes/Clancy\ Stealth.json

Open the interactive wizard

python ghost_typer.py --cli

Use a custom lexer and speed settings

python ghost_typer.py script.py --language python --min-delay 20 --max-delay 90 --speed 1.4

Notes

• The tool respects the terminal's native background in the minimalist UI mode.
• If you pass additional CLI arguments, Ghost-Typer uses the command-line flow instead of the simplified interactive path.
• Custom themes inside themes/ are discovered automatically by name.

Project structure

ghost-typer/
├── ghost_typer.py
├── pyproject.toml
├── MANIFEST.in
├── themes/
│   ├── Clancy Stealth.json
│   ├── dracula.json
│   ├── example-neon.json
│   └── monokai.json
└── venv/

Packaging and publishing (PyPI)

1. Update version

Before each release, bump the version in pyproject.toml.

2. Build distribution artifacts

From the project root:

python -m pip install --upgrade build twine
python -m build

This generates:

• dist/*.tar.gz (source distribution)
• dist/*.whl (wheel)

3. Validate package metadata

python -m twine check dist/*

4. Upload to TestPyPI (recommended)

python -m twine upload --repository testpypi dist/*

Test install from TestPyPI:

pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple ghost-typer

5. Upload to PyPI

python -m twine upload dist/*

If you use an API token, set it as the password in Twine with username __token__.

License

Add your preferred license here.