vibrator

Run AI coding agents — Claude Code, Codex, OpenCode, Kimi Code, or Pi — in an isolated Docker container per project. One Go binary (vibrate, alias vb), a declarative .vb file that pins your setup, and a wizard that fills the gaps.

📖 Full documentation →

Claude Code is the primary, fully-exercised harness. Codex, OpenCode, Kimi Code, and Pi are wired in and usable, but experimental — expect rough edges and please file issues.

Features

• One binary, zero host clutter — the only thing you install on the host is Docker; everything else runs in the container.
• Isolated per project — a throwaway container per workspace, so your host stays clean and projects never share state.
• Declarative .vb — harness, profile, extensions, mounts, and LLM provider in one TOML file. Gitignored automatically once it holds credentials; an existing .gitignore is always updated. Replayed on every run.
• Wizard fills the gaps — anything you don't pass as a flag, it asks; fully scriptable with --no-wizard.
• Runtime auto-detection — Docker Desktop, OrbStack, Colima, Rancher Desktop, Podman, or native Docker.
• Profiles & features — minimal / backend / frontend / full, fine-tuned with --with / --no.
• Curated extensions — MCP servers, skills, and agents (Serena, Context7, Playwright, claude-mem, the ECC bundle) added with --extensions.
• Language servers on PATH — gopls, basedpyright, and typescript-language-server, baked into the profiles that need them.
• Cloud or local LLMs — Anthropic, OpenAI, any OpenAI-compatible endpoint, or a local Ollama / LM Studio model.
• The container is the boundary — the agent runs with permission prompts bypassed and passwordless root inside, and your workspace is mounted read-write at its real path. That is the design; --no-yolo restores prompts, and --dind removes the boundary entirely.

Install

Download a release binary (quickest)

Grab the asset for your OS/arch from the latest release — vibrate_<version>_<os>_<arch>, built for Linux and macOS on amd64/arm64 — then:

chmod +x vibrate_*_*_*
sudo mv vibrate_*_*_* /usr/local/bin/vibrate
vibrate --version

Windows isn't built natively — run the linux/amd64 binary under WSL2.

Build from source

Needs Go and just. just install compiles the binary, puts it on your $PATH, adds the vb alias, and registers shell completion.

git clone https://github.com/wlame/vibrator.git
cd vibrator
just install                 # → /usr/local/bin (sudo); or: just install ~/.local/bin

Quick start

cd ~/my-project
vibrate          # or `vb` — wizard fills the gaps, builds the image, drops you in

The first run writes a .vb file capturing your choices; every run after that reuses the container and jumps straight in. An existing .gitignore always gets a .vb entry added; a missing one is created only once the file holds credentials.

vibrate --harness=codex --profile=backend   # pick an agent + stack
vibrate --extensions=ecc-developer          # add a curated bundle
vibrate shell                               # a plain shell instead of the agent
vibrate reconfigure                         # re-run the wizard, keep credentials

See the CLI reference for every command and flag.

Development

just              # list all recipes
just build        # build ./build/vibrate (native platform)
just build-all    # cross-compile every supported platform
just test         # unit tests with the race detector
just ci           # what CI runs: lint + test + build

Releases are drafted in the GitHub UI; CI builds the per-platform binaries and attaches them. The documentation has the full development and release guide, plus an architecture overview.

License

MIT — see LICENSE.