DevBuddy is a command-line tool that automates development environment setup and provides project-specific commands. Define your project's requirements in a dev.yml file and let bud handle the rest.

With DevBuddy, getting started on a project you've never touched looks like this:

bud clone devbuddy/devbuddy
bud up
# hack hack hack
bud test

DevBuddy manages environments and dependencies through tasks defined in dev.yml:

Languages:

• Python — version management (pyenv + virtualenv), pip, Pipfile
• Go — version management, Go modules
• Node.js — version management (including Apple Silicon), npm

System & Environment:

• Homebrew — install macOS packages
• Apt — install Debian/Ubuntu packages
• Environment variables — set project-specific env vars
• Env files — load variables from .env files
• Custom tasks — conditional shell commands (met?/meet pattern)

See the full task documentation for details.

• Automatic environment activation/deactivation as you cd between projects
• Notification when important files (e.g. requirements.txt) are updated locally
• bud open to jump to the GitHub repo page, or bud open <name> for project URLs
• bud clone / bud cd for fast project navigation
• bud tree to create, navigate, and clean up Git worktrees
• Shell completion (bash and zsh)

• macOS (Intel and Apple Silicon)
• Linux (amd64 and arm64)

• Bash
• Zsh

curl -sSL https://raw.githubusercontent.com/devbuddy/devbuddy/main/install.sh | sh

Pin a specific version:

curl -sSL https://raw.githubusercontent.com/devbuddy/devbuddy/main/install.sh | VERSION=v0.15.0 sh

Choose a custom install directory (defaults to /usr/local/bin):

curl -sSL https://raw.githubusercontent.com/devbuddy/devbuddy/main/install.sh | INSTALL_DIR=./bin sh

brew install devbuddy/devbuddy/devbuddy

Requires Go and GOPATH/bin in your PATH:

go install github.com/devbuddy/devbuddy/cmd/bud@latest

Add shell integration to your ~/.bash_profile or ~/.zshrc:

eval "$(bud --shell-init --with-completion)"

A safer version that only activates if bud is installed:

type bud > /dev/null 2> /dev/null && eval "$(bud --shell-init --with-completion)"

DevBuddy reads ~/.config/devbuddy/config.yml (respecting $XDG_CONFIG_HOME). All keys are optional.

# Default organization: "bud clone myrepo" becomes "bud clone myorg/myrepo"
default_org: myorg

# Default hosting platform (default: github.com)
# Supported: github.com, gitlab.com, bitbucket.org, codeberg.org,
#            git.sr.ht, any self-hosted Gitea/GitLab instance
default_platform: gitlab.com

shell:
  defer_init: false

bud clone and bud cd accept short org/repo identifiers, full SSH URLs (git@host:org/repo.git), and full HTTPS URLs (https://host/org/repo[.git]).

DevBuddy can run your project commands in CI without full shell integration. Install the binary, then activate the environment with eval "$(bud --shell-hook)" before running any bud command:

curl -sSL https://raw.githubusercontent.com/devbuddy/devbuddy/main/install.sh | sh
eval "$(bud --shell-hook)"
bud up
bud test

Example GitHub Actions step:

- name: Run tests
  run: |
    curl -sSL https://raw.githubusercontent.com/devbuddy/devbuddy/main/install.sh | sh
    eval "$(bud --shell-hook)"
    bud up
    bud test

Add a dev.yml file to your project root:

env:
  DATABASE_URL: postgres://localhost:5432/myapp_dev

up:
  - go:
      version: '1.22'
  - python: 3.12.0
  - pip:
    - requirements.txt
  # For pyproject.toml / uv.lock projects, use:
  # - uv
  - homebrew:
    - curl
  - custom:
      name: Download GeoIP db
      met?: test -e GeoIP.dat
      meet: curl -sL http://example.com/GeoIP.dat.gz | gunzip > GeoIP.dat

commands:
  test:
    desc: Run the tests
    run: script/test
  lint:
    desc: Lint the project
    run: script/lint

open:
  staging: https://staging.myapp.com
  ci: https://github.com/org/myapp/actions

See DevBuddy's own dev.yml for a real-world example.

DevBuddy can manage Git worktrees beside your existing checkout. The normal clone remains the main worktree:

~/src/github.com/org/repo
~/src/github.com/org/repo--feature-a

Create and jump between worktrees from any checkout in the repository:

bud tree new feature-a
bud tree switch feature-a
bud tree switch

bud tree new creates the worktree and jumps into it. bud tree prune cleans stale Git worktree metadata and asks whether to delete each existing worktree that has not been touched for more than one week.

bud tree switch jumps directly when given a query, or opens an interactive selector with up/down keys and enter when no query is provided. Regular bud cd also understands managed worktree branches, so bud cd feature-a can jump to a worktree even when its directory is named for a different agent or task.

If a branch is already checked out in another worktree, DevBuddy shows the existing path and a command to jump there instead of leaving you with Git's raw error.

Contributions are welcome! See CONTRIBUTING.md for details.

MIT

Authors:

• Pior Bastida (pior@pbastida.net)
• Mathieu Leduc-Hamel (mathieu.leduchamel@shopify.com)
• Emmanuel Milou manumilou@mykolab.com
• John Duff @jduff