Reading the repo
Opening the box…
Reading the repo
Opening the box…
How to install on Linux
It's Vibecraft!
GitHub didn't answer, so this is the saved copy from 1 days ago
Will it work on Linux?
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 bash setup.sh. 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.
git clone https://github.com/Nearcyan/vibecraft.git cd vibecraft
Node.js LTS (no version pinned), jq
# needs nvm: https://github.com/nvm-sh/nvm nvm install --lts sudo apt install 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 Linux yet.
GitManual AI Agent reads the 3 key files and writes a step-by-step guide for Linux. Once written, it's saved for everyone.