How It Works

The init pipeline

When you run streb init, it runs seven installation steps sequentially — order matters because Claude Code CLI requires Bun to be installed first.

Each step follows a check → install → re-check lifecycle: streb first verifies whether the tool is already present and at an acceptable version. If it is, the step is skipped. If not, streb installs it and re-checks to confirm success before moving on.

If any step fails, streb reports the error and exits with code 1. Pressing Escape or Ctrl+C at any point cancels cleanly with exit code 130.

1. 1

   Authentication

   Checks for existing Claude credentials. If missing, launches an interactive provider picker.

2. 2

   Git

   Verifies Git is installed and accessible. Installs via the platform package manager if missing (Homebrew on macOS, winget on Windows, apt/dnf on Linux).

3. 3

   Git user config

   Checks that user.name and user.email are set. Launches an interactive form if they're missing.

4. 4

   Bun

   Installs the Bun JavaScript runtime if missing. Bun replaces Node.js + npm as a single, fast runtime and package manager.

5. 5

   Claude Code CLI

   Installs the Anthropic Claude Code CLI via bun install -g @anthropic-ai/claude-code. Runs after Bun to guarantee the dependency is available.

6. 6

   jq

   Command-line JSON processor used to query and transform JSON in shell scripts and AI tooling pipelines. Installed via platform package manager.

7. 7

   yq

   YAML processor used to read and write .streb/config.yaml and other YAML-based config files in AI-assisted workflows. Installed via platform package manager.

Environment checks

After the installation steps, streb runs five read-only environment checks. These never install anything — they report warnings or pass/fail status only. The same checks run in streb doctor, in parallel.

Authentication providers

streb supports three Claude authentication methods. The interactive TUI lets you choose at first run; env vars allow non-interactive configuration for CI or shared machines.

Configuration layering

streb merges configuration from multiple sources. Later sources override earlier ones. Both the global file and the project file accept any subset of the same keys — you only need to set what differs from the defaults.

1. 1

   Built-in defaults

   Baked into the binary. Log level info, text format, 3 retry attempts.

2. 2

   Global config — ~/.streb/config.yaml

   Per-user settings that apply to every project. Good for personal preferences like log level or output format.

3. 3

   Project config — .streb/config.yaml

   Project-specific settings committed to the repository. Set project.name and any shared defaults here so every developer picks them up automatically.

4. 4

   Encrypted session — .streb/session

   API keys and tokens stored as an AES-256-GCM encrypted blob. Never committed — add it to .gitignore.

5. 5

   Environment variables

   STREB_AIHUB_KEY, etc. Override the session file — inject these in CI instead of copying a session file between machines.

6. 6

   CLI flags

   --log-level, --verbose, --quiet. Highest priority — useful for one-off debug runs without editing any config file.

Secrets and the session file

Sensitive values (API keys, tokens) are stored in .streb/session as an AES-256-GCM encrypted blob. The encryption key is derived from a device fingerprint — a stable identifier unique to the current machine.

How the fingerprint is determined per OS:

• Linux — /etc/machine-id or /var/lib/dbus/machine-id
• macOS — IOPlatformUUID from ioreg
• Windows — MachineGuid from HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography

Health checks (streb doctor)

streb doctor runs all the prerequisite checks in parallel — faster than init because it's read-only. It also includes an OS and architecture check that init doesn't run. Use it any time you suspect something is broken, or after a machine rebuild.

$ streb doctor
  ✓  Authentication
  ✓  Git                  2.47.0
  ✓  Git user config
  ✓  Bun                  1.2.4
  ✓  Claude Code CLI      1.5.0
  ✓  jq                   1.7.1
  ✓  yq                   4.44.6
  ✓  Network
  ✓  Disk space           47.3 GB free
  ✓  Write permission
  ✓  Home directory
  ⊖  Proxy config         none configured
  ✓  OS                   linux/amd64

A failed doctor check means streb init would also fail. Fix the reported issue and re-run streb init to correct it.

Resetting with streb reset

streb reset reverses streb init. By default it removes all configured components: auth credentials, Git config changes, Bun, Claude Code CLI, jq, and yq. Use --skip-* flags to preserve specific items.

# Remove everything
streb reset

# Keep Claude Code and Bun, reset everything else
streb reset --skip-claude-code --skip-bun

# Keep auth credentials only
streb reset --skip-auth

After a reset, re-running streb init starts fresh — useful for troubleshooting a broken environment or onboarding to a different auth provider.

TUI and plain-text mode

When stdout is a terminal (TTY), streb uses a full Bubble Tea TUI with color, interactive prompts, and progress indicators.

When stdout is not a TTY — a CI pipeline, a script, a pipe, or an SSH session — streb falls back to plain text output automatically. No flag needed; it detects terminal capabilities at startup.

# CI usage — plain text output, no interactivity
STREB_AIHUB_KEY=sk-... streb init