Reference
Config and files
The settings voodoo reads, the environment variables on top of them, and where it keeps everything.
voodoo reads one file, config.json in its config folder. Every key is optional, a key it doesn’t know is ignored, and a file it can’t read is logged and stood in for by the defaults: the sessions matter more than a setting that was mistyped. The daemon reads it when it starts, so a change takes voodoo restart.
{
"worktrees": true,
"worktree_limit": 8,
"link": true
}Settings
| Key | What it does |
|---|---|
| worktrees | Whether an agent gets a git worktree of its own. true unless you say. Off, every session runs in the project’s own checkout. |
| worktree_limit | How many worktrees a project may hold at once. 8 unless you say, and never more than 64. |
| link | Whether phones can reach this machine. true unless you say. Off, the daemon never touches the network. |
Environment variables
Read by the process they are set for, and they win over the file.
| Variable | What it does |
|---|---|
| LU_HOME | Moves the whole config folder. A moved home is a self-contained instance: its socket, logs and worktrees go with it. |
| LU_RUNTIME_DIR | Moves the socket and the pidfile alone. |
| LU_WORKTREE_DIR | Where the worktrees cut for agents go. |
| LU_LINK | off keeps the daemon off the network, whatever the file says. |
| LU_SHELL | The shell a shell session runs, instead of your login shell. |
| VISUAL EDITOR | Yours, and sessions inherit them. With neither set, a session is told its EDITOR is NeoVim, when nvim is installed. |
| LU_LOG | What the daemon logs, as a tracing filter such as debug or voodoo_daemon=trace. info unless you say. |
| LU_NO_MOTION | Set to anything, and nothing in the terminal UI moves. |
| LU_SCENE | What the splash draws over its stars, where by default it draws nothing: galaxy for the Milky Way, pillars for the Pillars of Creation, or hole for a black hole. |
| LU_PICTURES | off draws Hex in blocks even in a terminal that could show the picture. |
| NO_COLOR | Set to anything, and voodoo draws in the terminal’s own colours and says things with weight alone. |
Where things live
| Path | What it is |
|---|---|
| ~/.config/localuniverse/ | The config folder: config.json, the database lu.db, the link’s key link.key, and the hook settings Claude Code is started with. The folder a backup keeps and a purge deletes. |
| ~/.config/localuniverse/run/ | The socket and the pidfile. Mode 0700, and that mode is the whole of the local auth boundary, as it is for tmux. |
| ~/Library/Logs/localuniverse/ | daemon.log and tui.log on macOS, where Console looks. On Linux, the XDG state folder. |
| ~/.local/share/localuniverse/worktrees/ | The worktrees cut for agents. Outside the config folder on purpose, so that deleting the config never deletes work that hasn’t landed. |
More on the worktrees and what happens to them on the worktrees page; more on the link and its key on the phone page.