Getting started

Installation

One line installs voodoo and has its daemon start at login. voodoo update keeps it current.

What you need

  • A Mac (Apple silicon or Intel), or Linux on x86_64 or arm64.
  • For agent sessions, claude or codex on your PATH. voodoo starts the one you pick and doesn’t install either.

Install it

curl -fsSL https://usevoodoo.dev/install | sh

That downloads the build for your machine, checks it against the release’s checksums, and puts it in ~/.local/bin as voodoo, with lu beside it as a compatibility alias. It never asks for sudo. If ~/.local/bin isn’t on your PATH yet, it says the line to add for your shell.

Then it runs voodoo setup, which has the daemon start at login (a launchd agent on macOS, a systemd user unit on Linux), starts it, checks for claude and codex, and says what to do next.

Running the line again is safe. It changes only what is out of date.

Options

Set any of these in front of sh:

  • VOODOO_VERSION=0.1.0 installs that version instead of the latest.
  • VOODOO_INSTALL_DIR=/somewhere/bin installs there instead of ~/.local/bin.
  • VOODOO_NO_SETUP=1 installs the binary and stops, without voodoo setup.

Check it worked

voodoo status
voodoo status

  Voodoo

  ✓ The daemon is up · voodoo 0.1.0 · pid 4120 · just started
  ✓ The link is up · 3f9a1c2e · reachable from anywhere
  › No projects yet.
    `voodoo add <folder>` adds one.

Plain voodoo opens the terminal UI. Your first session goes on from there.

After a reboot

The daemon starts when you log in. Sessions don’t outlive the machine: the ones it was running come back as lost until you restart them.

The daemon started at login runs with the PATH you ran voodoo setup from, which is where it finds the agents. If you install one somewhere new, run voodoo setup again.

On Linux, a systemd user unit runs while you are logged in. To keep the daemon up on a machine nobody logs in to, run loginctl enable-linger once. Where there is no systemd, as in most containers, voodoo setup starts the daemon and says how to have it start with the machine.

Update it

voodoo update

That installs the latest release over the one you have, checked the same way, and restarts the daemon as the new version. Its sessions keep running through the restart.

Build it from source

For working on voodoo itself. It takes a stable Rust toolchain. Clone the repository:

git clone https://github.com/tin0d0/voodoo

From the root of the clone:

cargo install --path crates/voodoo-cli --locked

That installs into cargo’s bin folder. A build from source updates the same way, not with voodoo update. Run voodoo restart afterwards so the daemon is the new build too.