Hummingbot Developer

Developer skill for running Hummingbot and Gateway from source, building wheel and Docker images, and testing against Hummingbot API running from source. Use this skill when a developer wants to build, run, or test Hummingbot components locally.

# hummingbot-developer

Developer workflow skill for building and running the full Hummingbot stack from source.

**Commands** (run as `/hummingbot-developer <command>`):

| Command | Description |
|---------|-------------|
| `start` | Check dev environment status |
| `select-branches` | Pick branches for all 3 repos |
| `install-all` | Install all 3 repos in order |
| `build-all` | Build wheel + all Docker images |
| `verify-build` | Verify builds are correct + in sync |
| `run-dev-stack` | Start full stack from source |
| `setup-hummingbot` | Install Hummingbot from source |
| `run-hummingbot` | Run Hummingbot CLI from source |
| `build-hummingbot` | Build wheel + Docker image |
| `setup-gateway` | Install Gateway from source |
| `run-gateway` | Run Gateway in dev mode |
| `build-gateway` | Build Gateway Docker image |
| `setup-api-dev` | Wire API to local Hummingbot source |
| `run-api-dev` | Run API from source with hot-reload |
| `test-integration` | Smoke test the full stack |

**Typical dev workflow:**
```
install-deps → select-branches → install-all → build-all → verify-build → run-dev-stack → test-integration
```

**Repo locations (all in workspace):**

| Repo | Path |
|------|------|
| hummingbot | `~/.openclaw/workspace/hummingbot` |
| gateway | `~/.openclaw/workspace/hummingbot-gateway` |
| hummingbot-api | `~/.openclaw/workspace/hummingbot-api` |

Override with env vars: `HUMMINGBOT_DIR`, `GATEWAY_DIR`, `HUMMINGBOT_API_DIR`, or `WORKSPACE`.

---

## Command: install-deps

Auto-install all missing dev dependencies. Safe to re-run — skips anything already installed.

```bash
bash scripts/install_deps.sh
```

**Installs (only if missing):**
- Homebrew (macOS)
- Xcode Command Line Tools (macOS — needed for Cython `build_ext`)
- Miniconda (conda)
- Node.js v22 (via nvm, Homebrew, or installs nvm)
- pnpm (via npm or Homebrew)
- Git
- Docker Desktop (macOS — via Homebrew cask or opens download page)

**Options:**
```bash
--check         # check only, don't install anything
--conda         # only install conda
--node          # only install node + nvm
--pnpm          # only install pnpm
```

**After installing**, restart your terminal (or `source ~/.zshrc`) to apply PATH changes, then run `check_env.sh` to confirm.

---

## Command: select-branches

Interactively pick a branch for each repo, checkout, and save to `.dev-branches`.

```bash
bash scripts/select_branches.sh
```

**Non-interactive options:**
```bash
# Use development for all
bash scripts/select_branches.sh --defaults

# Specify each branch
bash scripts/select_branches.sh \
  --hummingbot development \
  --gateway core-2.7 \
  --api development
```

Branch selections are saved to `$WORKSPACE/.dev-branches` and automatically loaded by `install_all.sh`, `build_all.sh`, and `verify_build.sh`.

---

## Command: install-all

Install all three repos in the correct order. Requires `select-branches` first (or pass `--defaults`).

```bash
bash scripts/install_all.sh
```

**What it does (in order):**
1. Removes `solders` from `environment.yml` (pip-only)
2. `make install` in hummingbot → `conda env hummingbot`
3. `pip install solders>=0.19.0` into hummingbot env
4. `pnpm install && pnpm build && pnpm run setup:with-defaults` for gateway
5. `conda env create` for hummingbot-api
6. `pip install -e <hummingbot_dir> --no-deps` → wires local source into API env

**Options:**
```bash
--skip-hbot      # skip hummingbot conda install
--skip-gateway   # skip gateway pnpm install
--skip-api       # skip hummingbot-api install
--no-local-hbot  # use PyPI hummingbot in API env instead of local source
```

---

## Command: build-all

Build hummingbot wheel and all Docker images in the correct order.

```bash
bash scripts/build_all.sh
```

**Build order:**
1. `hummingbot` wheel (`dist/*.whl`) via `python setup.py bdist_wheel`
2. `hummingbot/hummingbot:dev` Docker image
3. `hummingbot/gateway:dev` Docker image (also rebuilds dist/)
4. `hummingbot/hummingbot-api:dev` Docker image

**Each image is also tagged with the branch name** (e.g., `hummingbot/gateway:core-2.7`).

**Options:**
```bash
--wheel-only     # only build hummingbot wheel, no Docker
--no-docker      # skip all Docker builds
--no-hbot        # skip hummingbot builds
--no-gateway     # skip gateway builds
--no-api         # skip hummingbot-api builds
--tag <name>     # Docker tag (default: dev)
```

---

## Command: verify-build

Verify that all builds are correct and in sync.

```bash
bash scripts/verify_build.sh
```

**Checks:**
1. Each repo is on the expected branch (from `.dev-branches`)
2. Hummingbot wheel exists in `dist/`
3. Gateway `dist/` is built and not stale vs source
4. Local hummingbot source is active in hummingbot-api env
5. Docker images exist with correct branch labels
6. Running services (API + Gateway) are reachable
7. API → Gateway connectivity

```bash
bash scripts/verify_build.sh --no-docker   # skip Docker checks
bash scripts/verify_build.sh --no-running  # skip service checks
bash scripts/verify_build.sh --json        # JSON output
```

---

## Command: run-dev-stack

Start the full dev stack from source.

```bash
bash scripts/run_dev_stack.sh
```

**Start order:**
1. Docker infra (postgres + EMQX) via `docker compose up emqx postgres -d`
2. Gateway from source in background (`node dist/index.js --passphrase=hummingbot --dev`)
3. Hummingbot API from source in foreground (`uvicorn main:app --reload`)

**Options:**
```bash
--no-gateway           # skip gateway start
--passphrase <pass>    # gateway passphrase (default: hummingbot)
--stop                 # stop everything
--status               # show running status
```

**Logs:**
- Gateway logs: `tail -f ~/.openclaw/workspace/.gateway.log`
- API logs: printed to terminal (foreground)

---

## Command: start

Check the full dev environment and show a status summary.

### Step 1: Run environment check

```bash
bash scripts/check_env.sh --json
```

### Step 2: Check repo branches

```bash
bash scripts/check_repos.sh --json
```

### Step 3: Check running services

```bash
bash scripts/check_api.sh --json
bash scripts/check_gateway.sh --json
```

### Step 4: Show status checklist

Present a checklist like:

```
Dev Environment Status
======================
  [x] Prerequisites     — conda, node, pnpm, docker, git OK
  [x] Hummingbot repo   — branch: development, env: hummingbot (installed)
  [x] Gateway repo      — branch: development, built: yes
  [x] Hummingbot API    — running at http://localhost:8000
  [x] Gateway           — running at http://localhost:15888
  [ ] Local hummingbot  — hummingbot-api NOT using local source

Next: run /hummingbot-developer setup-api-dev to wire API to local source
```

Adapt to actual state. If all good, show the test command.

---

## Command: setup-hummingbot

Install Hummingbot from source on the `development` branch.

### Step 1: Check prereqs

```bash
bash scripts/check_env.sh
```

### Step 2: Checkout development branch

```bash
cd <HUMMINGBOT_DIR>
git fetch origin
git checkout development
git pull origin development
```

### Step 3: Remove solders from environment.yml (pip-only package)

```bash
sed -i '' '/solders/d' setup/environment.yml 2>/dev/null || sed -i '/solders/d' setup/environment.yml
```

### Step 4: Install conda environment

```bash
make install
```

This creates the `hummingbot` conda env. Takes 3-10 minutes on first run.

### Step 5: Install solders via pip (not on conda)

```bash
conda run -n hummingbot pip install "solders>=0.19.0"
```

### Interpreting output

| Output | Meaning | Next step |
|--------|---------|-----------|
| `conda develop .` succeeds | Dev install registered | Proceed |
| `PackagesNotFoundError: solders` | Forgot step 3 | Run sed + reinstall |
| `Error: Conda is not found` | conda not in PATH | `source ~/.zshrc` or install Anaconda |
| `build_ext` errors | Missing build tools | Install Xcode CLT: `xcode-select --install` |

### After setup

```
  [x] conda env "hummingbot" created
  [x] solders ins