diff --git a/README.md b/README.md
index 7141f84..df2003f 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,7 @@
 ## Features
 
 ![Demo](./assets/demo.gif)
+*(Want to create a demo like this? Check out the [recording documentation](demo/recording-demo.md))*
 
 - **Standalone Executable** - perfect for wrapping slow commands in bash scripts
 - **16 built-in spinner styles** - dots, line, arc, bounce, and more
diff --git a/assets/demo.gif b/assets/demo.gif
index 4267217..24beebf 100644
Binary files a/assets/demo.gif and b/assets/demo.gif differ
diff --git a/demo.lua b/demo.lua
deleted file mode 100644
index e1d3f0c..0000000
--- a/demo.lua
+++ /dev/null
@@ -1,98 +0,0 @@
-#!/usr/bin/env lua
---- roda.lua demo script
---- Run with: lua demo.lua (from project root)
---- Record with: vhs demo.tape
-
--- Add local lua path for running from project root
-package.path = "./lua/?.lua;./lua/?/init.lua;" .. package.path
-
-local roda = require("roda")
-local system = require("system")
-
---- Spin for a given duration (in seconds)
---- This is required because Lua is single-threaded - we must
---- manually call :spin() in a loop to animate the frames.
----@param spinner table Spinner instance
----@param duration number Duration in seconds
-local function spin_for(spinner, duration)
-	local start = system.gettime()
-	while (system.gettime() - start) < duration do
-		spinner:spin()
-		system.sleep(0.05) -- ~20 FPS
-	end
-end
-
-print("")
-print("  🎡 roda.lua - Elegant terminal spinners for Lua")
-print("")
-
--- Demo 1: Basic spinner with success
-local s1 = roda("Installing dependencies..."):start()
-spin_for(s1, 1.8)
-s1:succeed("Dependencies installed!")
-
-system.sleep(0.5)
-
--- Demo 2: Different spinner style with failure
-local s2 = roda({
-	text = "Connecting to database...",
-	spinner = "dots2",
-	color = "yellow",
-}):start()
-spin_for(s2, 1.8)
-s2:fail("Connection refused!")
-
-system.sleep(0.5)
-
--- Demo 3: Warning state
-local s3 = roda({
-	text = "Validating configuration...",
-	spinner = "arc",
-	color = "cyan",
-}):start()
-spin_for(s3, 1.5)
-s3:warn("Using deprecated options")
-
-system.sleep(0.5)
-
--- Demo 4: Info state
-local s4 = roda("Checking cache..."):start()
-spin_for(s4, 1.2)
-s4:info("Using cached response")
-
-system.sleep(0.5)
-
--- Demo 5: Dynamic text updates with progress
-local s5 = roda({
-	text = "Processing files...",
-	spinner = "bouncingBar",
-	color = "magenta",
-}):start()
-
-for i = 1, 5 do
-	s5:setText(string.format("Processing file %d of 5...", i))
-	spin_for(s5, 0.5)
-end
-s5:succeed("All 5 files processed!")
-
-system.sleep(0.5)
-
--- Demo 6: Multiple spinner styles showcase
-print("")
-print("  Available spinner styles:")
-print("")
-
-local styles = { "dots", "line", "star", "bounce", "arrow" }
-for _, style in ipairs(styles) do
-	local s = roda({
-		text = string.format('Style: "%s"', style),
-		spinner = style,
-		color = "green",
-	}):start()
-	spin_for(s, 1.2)
-	s:stop()
-end
-
-print("")
-print("  ✨ Learn more: luarocks.org/modules/tkolleh/roda")
-print("")
diff --git a/demo/demo.lua b/demo/demo.lua
index 565bbe4..56182a0 100755
--- a/demo/demo.lua
+++ b/demo/demo.lua
@@ -1,6 +1,7 @@
 #!/usr/bin/env -S lx lua
 --- Demo script for Roda terminal spinner library
---- Run this script to see all features in action
+--- Run this script using: just demo run
+--- Record this script using: just demo record
 
 local system = require("system")
 
diff --git a/demo.tape b/demo/demo.tape
similarity index 80%
rename from demo.tape
rename to demo/demo.tape
index 8f03262..551d45f 100644
--- a/demo.tape
+++ b/demo/demo.tape
@@ -6,14 +6,14 @@
 #   lx install  (or ensure roda is in package.path)
 #
 # Generate GIF:
-#   vhs demo.tape
+#   just demo record
 #
 # Generate MP4:
-#   vhs demo.tape --output assets/demo.mp4
+#   vhs demo.tape --output ../assets/demo.mp4
 
 # Output configuration
-Output assets/demo.gif
-Set Shell "zsh"
+Output ../assets/demo.gif
+Set Shell "bash"
 
 # Set up a 1200x600 terminal
 Set FontSize 30
@@ -27,7 +27,7 @@ Set PlaybackSpeed 1
 Sleep 500ms
 
 # Show command being typed
-Type "lua demo.lua"
+Type "just demo run"
 Sleep 300ms
 Enter
 
diff --git a/demo/mod.just b/demo/mod.just
new file mode 100644
index 0000000..2d396d2
--- /dev/null
+++ b/demo/mod.just
@@ -0,0 +1,8 @@
+[doc("Run the demo script to showcase Roda features")]
+run:
+    lx lua -- demo/demo.lua
+
+[doc("Record the demo and generate a GIF using VHS")]
+record:
+    cd demo && vhs demo.tape
+
diff --git a/demo/recording-demo.md b/demo/recording-demo.md
new file mode 100644
index 0000000..c9d216c
--- /dev/null
+++ b/demo/recording-demo.md
@@ -0,0 +1,51 @@
+# Recording the Demo GIF
+
+Generate the demo GIF using [VHS](https://github.com/charmbracelet/vhs).
+
+## Prerequisites
+
+```bash
+brew install vhs          # Terminal recorder
+lx install                # Or ensure roda is in package.path
+```
+
+## Demo Script
+
+`demo/demo.lua` showcases Roda features:
+- Basic spinner usage
+- Terminal states (succeed, fail, warn, info)
+- Dynamic text updates
+- Different spinner styles
+
+Run interactively: `just demo run`
+
+## Recording
+
+Generate the GIF:
+```bash
+just demo record
+```
+
+This runs `vhs` with `demo/demo.tape`, producing `assets/demo.gif`.
+
+## Tape Configuration
+
+`demo/demo.tape` configures the recording:
+```tape
+Output ../assets/demo.gif
+Set Shell "bash"
+Set FontSize 30
+Set Width 1200
+Set Height 600
+Set TypingSpeed 50ms
+Set PlaybackSpeed 1
+```
+
+Customize settings like `FontSize`, `Width`, `Height` as needed.
+
+## Tips
+
+- Use a dark terminal background for contrast
+- Ensure terminal uses a monospace font (JetBrains Mono, Fira Code)
+- The demo runs ~18 seconds; adjust `Sleep` in the tape accordingly
+- For MP4 output: `vhs demo.tape --output ../assets/demo.mp4`
diff --git a/docs/recording-demo.md b/docs/recording-demo.md
deleted file mode 100644
index d68ea06..0000000
--- a/docs/recording-demo.md
+++ /dev/null
@@ -1,96 +0,0 @@
-# Recording the Demo GIF
-
-This guide explains how to create the demo GIF shown in the README.
-
-## Prerequisites
-
-Install the required tools:
-
-```bash
-# macOS
-brew install asciinema
-brew install agg  # asciinema-agg for GIF conversion
-
-# Or use npm
-npm install -g svg-term-cli
-```
-
-## Demo Script
-
-The demo script is located at `demo/demo.lua`. It showcases Roda's features including:
-
-- Basic spinner usage
-- Different terminal states (succeed, fail, warn, info)
-- Dynamic text updates
-- Different spinner styles
-
-## Recording
-
-1. **Record the terminal session**:
-
-```bash
-# Start recording
-asciinema rec demo.cast --cols 80 --rows 24
-
-# Run the demo
-lua demo/demo.lua
-
-# Press Ctrl+D to stop recording
-```
-
-2. **Convert to GIF**:
-
-Using agg (recommended):
-```bash
-agg demo.cast assets/demo.gif --cols 80 --rows 24 --speed 1.0
-```
-
-Using svg-term:
-```bash
-svg-term --in demo.cast --out assets/demo.svg --window
-```
-
-## Tips
-
-- Use a clean terminal with a dark background
-- Set terminal to 80x24 for consistency
-- Use a monospace font that supports Unicode (e.g., JetBrains Mono, Fira Code)
-- Keep the demo under 15 seconds for a reasonable GIF size
-
-## Alternative: VHS
-
-[VHS](https://github.com/charmbracelet/vhs) is another excellent option:
-
-```bash
-brew install vhs
-```
-
-Create a `.tape` file:
-
-**File**: `demo/demo.tape`
-
-```tape
-Output assets/demo.gif
-Set FontSize 14
-Set Width 800
-Set Height 400
-
-Type "lua demo/demo.lua"
-Enter
-Sleep 15s
-```
-
-Run:
-```bash
-vhs demo/demo.tape
-```
-
-## Optimizing the GIF
-
-If the GIF is too large:
-
-```bash
-# Using gifsicle
-brew install gifsicle
-gifsicle -O3 --colors 64 assets/demo.gif -o assets/demo-optimized.gif
-```
diff --git a/justfile b/justfile
index ec370e1..bc82f25 100644
--- a/justfile
+++ b/justfile
@@ -12,6 +12,8 @@ set unstable := true
 
 # Enable latest Just features
 
+mod demo
+
 set dotenv-load := true
 
 # Auto-load .env files