# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this is

Single bash script (`runpod-session.sh`) that manages RunPod GPU pod lifecycle for running Ollama models, then patches `~/.config/opencode/opencode.jsonc` so opencode points at the live pod.

## Running / testing

```bash
# Check syntax
bash -n runpod-session.sh

# Lint
shellcheck runpod-session.sh

# Run (requires RUNPOD_API_KEY in ~/.config/runpod-session/config)
./runpod-session.sh --status
./runpod-session.sh --model qwen3-coder:latest
./runpod-session.sh --stop
./runpod-session.sh --all-models
./runpod-session.sh --new --gpu-type "RTX PRO 6000" --max-price 1.50
```

## Architecture

All logic is in `main()` which runs these steps in order:

1. **Existing pod check** — queries RunPod GraphQL API, matches pod by name containing "ollama"
2. **Pod creation** — if none found: picks cheapest secure-cloud GPU under `MAX_PRICE_PER_HR`, creates pod with `ollama/ollama:latest` image, network volume mounted at `/workspace`
3. **Wait for Ollama** — polls `https://<pod-id>-11434.proxy.runpod.net/api/tags` until `.models` appears
4. **Patch opencode.json** — updates `baseURL`, active `model`, and merges `WARMUP_MODELS` into provider models block using jq `*` merge (existing config wins on conflicts)
5. **Warmup** — POST to `/api/generate` with a dummy prompt to load model into VRAM at `WARMUP_NUM_CTX` context length
6. **Save state** — writes `~/.config/runpod-session/state.json` with pod_id, url, model, timestamp

## Key design constraints

- All RunPod calls go through `gql()` — single curl wrapper that exits on API errors
- Pod is identified by name matching `test("ollama"; "i")` — not by ID — so the name `ollama-session` set at creation must not change
- `patch_opencode_config()` writes a `.bak` before touching opencode.jsonc; jq `*` merge means existing per-model settings survive
- `OLLAMA_MODELS_PATH` env var on the pod is not set by the script — must be set in config if models live outside default location on the network volume
- GPU selection only queries `secureCloud == true` pods; community cloud is excluded

## Config and state files

| Path | Purpose |
|------|---------|
| `~/.config/runpod-session/config` | Sourced as bash; holds API key, defaults |
| `~/.config/runpod-session/state.json` | Last session record (pod_id, url, model, timestamp) |
| `~/.config/opencode/opencode.jsonc` | Patched in-place; `.bak` written before changes |