Reading the repo
Opening the box…
Reading the repo
Opening the box…
How to install on Windows
It's Vibecraft!
GitHub didn't answer, so this is the saved copy from 1 days ago
Will it work on Windows?
The maintainers included scripts/install.sh. Run it from the cloned folder after reading it.
bash scripts/install.sh
docs/SETUP.mdComplete installation and troubleshooting guide for Vibecraft.
Vibecraft visualizes Claude Code's activity in real-time as a 3D workshop. When Claude uses tools (Read, Edit, Bash, etc.), a character moves to corresponding workstations.
Two parts:
┌─────────────────┐ hooks ┌─────────────────┐
│ Claude Code │ ───────────────→ │ Vibecraft │
│ (your CLI) │ │ Server (:4003) │
└─────────────────┘ └────────┬────────┘
│
↓ WebSocket
┌─────────────────┐
│ Browser │
│ (3D Scene) │
└─────────────────┘
# macOS
brew install jq tmux
# Ubuntu/Debian
sudo apt install jq tmux
# Arch
pacman -S jq tmux
npx vibecraft setup
This automatically adds hooks to ~/.claude/settings.json.
# Terminal 1: Start Vibecraft server
npx vibecraft
# Terminal 2: Use Claude Code normally
claude
Open http://localhost:4003 in your browser.
That's it! Every time Claude uses a tool, you'll see it in the 3D visualization.
| Dependency | Required? | Purpose | |------------|-----------|---------| | Node.js 18+ | Yes | Runs the server | | jq | Yes | JSON processing in hook scripts | | tmux | Optional | Session management, browser→Claude prompts |
Check if installed:
node --version # Should be 18+
jq --version # Should output version
tmux -V # Should output version (optional)
npx vibecraft setup
This:
~/.vibecraft/hooks/vibecraft-hook.sh~/.vibecraft/data/ directory~/.claude/settings.jsonAfter setup, restart Claude Code for hooks to take effect.
If you prefer to configure hooks manually, add to ~/.claude/settings.json:
{
"hooks": {
"PreToolUse": [
{ "matcher": "*", "hooks": [{"type": "command", "command": "HOOK_PATH", "timeout": 5}] }
],
"PostToolUse": [
{ "matcher": "*", "hooks": [{"type": "command", "command": "HOOK_PATH", "timeout": 5}] }
],
"Stop": [
{ "hooks": [{"type": "command", "command": "HOOK_PATH", "timeout": 5}] }
],
"SubagentStop": [
{ "hooks": [{"type": "command", "command": "HOOK_PATH", "timeout": 5}] }
],
"SessionStart": [
{ "hooks": [{"type": "command", "command": "HOOK_PATH", "timeout": 5}] }
],
"SessionEnd": [
{ "hooks": [{"type": "command", "command": "HOOK_PATH", "timeout": 5}] }
],
"UserPromptSubmit": [
{ "hooks": [{"type": "command", "command": "HOOK_PATH", "timeout": 5}] }
],
"Notification": [
{ "hooks": [{"type": "command", "command": "HOOK_PATH", "timeout": 5}] }
]
}
}
Replace HOOK_PATH with the output of:
npx vibecraft --hook-path
Note: You must also copy the hook script to a stable location and ensure ~/.vibecraft/data/ exists.
If you see this overlay in the browser:
┌──────────────────────────────────┐
│ │
│ 🔌 Agent Not Connected │
│ │
│ Vibecraft needs a local agent │
│ running to receive events. │
│ │
│ [ npx vibecraft ] │
│ │
└──────────────────────────────────┘
It means ONE of these:
| Problem | Solution |
|---------|----------|
| Server not running | Run npx vibecraft in a terminal |
| Wrong port | Check URL matches server port (default: 4003) |
| Hooks not configured | Run npx vibecraft setup |
Quick test:
# Check server is running
curl http://localhost:4003/health
# Should return: {"ok":true,...}
To send prompts to Claude from the Vibecraft UI:
# Create named tmux session
tmux new -s claude
# Start Claude inside tmux
claude
# In another terminal
npx vibecraft
In the browser, type in the prompt field and click "Send" with "Send to tmux" checked.
Note: If you named your tmux session something other than claude:
VIBECRAFT_TMUX_SESSION=myname npx vibecraft
# macOS
brew install jq
# Ubuntu/Debian
sudo apt install jq
# Arch
pacman -S jq
chmod +x $(npx vibecraft --hook-path)
1. Check server is running:
curl http://localhost:4003/health
2. Check hooks are configured:
cat ~/.claude/settings.json | grep vibecraft
3. Restart Claude Code (hooks load at startup)
# List sessions
tmux list-sessions
# Default session name is 'claude'
# If different, set environment variable:
VIBECRAFT_TMUX_SESSION=yourname npx vibecraft
You likely have duplicate hooks configured. Check ~/.claude/settings.json for duplicate vibecraft-hook entries and remove extras. Then run npx vibecraft setup to ensure correct configuration.
For speech-to-text prompts:
.env file:
DEEPGRAM_API_KEY=your_api_key_here
Alt+S or click the microphone icon| Variable | Default | Description |
|----------|---------|-------------|
| VIBECRAFT_PORT | 4003 | Server port |
| VIBECRAFT_TMUX_SESSION | claude | tmux session for prompts |
| VIBECRAFT_DEBUG | false | Verbose logging |
| DEEPGRAM_API_KEY | (none) | Deepgram API key for voice input |
Example:
VIBECRAFT_PORT=4005 VIBECRAFT_DEBUG=true npx vibecraft
For contributing or modifying:
# Clone
git clone https://github.com/nearcyan/vibecraft
cd vibecraft
# Install dependencies
npm install
# Start dev servers (frontend :4002, API :4003)
npm run dev
# Open browser
open http://localhost:4002
Note: In dev mode, frontend and API run on different ports. In production (npx vibecraft), everything runs on port 4003.
To remove Vibecraft hooks (keeps your event data):
npx vibecraft uninstall
This:
~/.claude/settings.json~/.vibecraft/hooks/~/.vibecraft/data/To completely remove all data:
rm -rf ~/.vibecraft
Restart Claude Code after uninstalling for changes to take effect.
Then run powershell -ExecutionPolicy Bypass -File .\setup.ps1. It stops at the first error and is safe to run again. Servers and tests aren't started; it lists them at the end. Read it first.
Needs Git: winget install Git.Git
git clone https://github.com/Nearcyan/vibecraft.git cd vibecraft
Node.js LTS (no version pinned), jq
winget install CoreyButler.NVMforWindows nvm install lts nvm use lts winget install jqlang.jq
npm ci
npm run dev
# 1. Install dependencies
brew install jq tmux # macOS
# sudo apt install jq tmux # Ubuntu/Debian
# 2. Configure hooks (one time)
npx vibecraft setup
# 3. Start server
npx vibecraft
Open http://localhost:4003 and use Claude Code normally. You'll see Claude move around the workshop as it uses tools.
From source:
git clone https://github.com/nearcyan/vibecraft
cd vibecraft && npm install && npm run dev
# Opens on http://localhost:4002
To uninstall: npx vibecraft uninstall (removes hooks, keeps your data)
No reports for Windows yet.
GitManual AI Agent reads the 3 key files and writes a step-by-step guide for Windows. Once written, it's saved for everyone.