Configuration Reference

Bloom uses two configuration files: workspace config and user config.

Workspace Configuration

bloom.config.yaml

Located in the workspace root. Created by bloom init.

repos:
  - url: [email protected]:myorg/backend.git
    name: backend
  - url: [email protected]:myorg/frontend.git
    name: frontend
  - url: https://github.com/myorg/shared.git
    name: shared

Properties

repos

List of repositories in the workspace.

repos:
  - url: <git-url>
    name: <local-name>

Property	Type	Description
url	string	Git clone URL (SSH or HTTPS)
name	string	Local directory name

Management

Repositories are automatically added when you run bloom repo clone:

bloom repo clone myorg/backend
# Adds entry to bloom.config.yaml

Manual editing is also supported:

repos:
  - url: [email protected]:myorg/new-repo.git
    name: new-repo

Then sync:

bloom repo sync

User Configuration

~/.bloom/config.yaml

Global user settings. Created on first use.

gitProtocol: ssh

agent:
  defaultInteractive: claude
  defaultNonInteractive: claude

  claude:
    defaultModel: sonnet
    models:
      - sonnet
      - haiku
      - opus

  opencode:
    defaultModel: github-copilot/claude-sonnet-4
    models:
      - github-copilot/claude-sonnet-4
      - openai/gpt-4o

Properties

gitProtocol

Preferred protocol for repository URLs.

gitProtocol: ssh    # [email protected]:org/repo.git
gitProtocol: https  # https://github.com/org/repo.git

• Type: enum
• Values: ssh, https
• Default: ssh (prompted during bloom init)

agent

Agent configuration section containing defaults and per-agent settings.

agent.defaultInteractive

Default agent for interactive commands (bloom enter, bloom refine).

• Type: string
• Values: claude, copilot, codex, goose, opencode
• Default: claude

agent.defaultNonInteractive

Default agent for autonomous task execution (bloom run).

• Type: string
• Values: claude, copilot, codex, goose, opencode
• Default: claude

agent.[agentName].defaultModel

Default model for a specific agent.

agent:
  claude:
    defaultModel: opus
  opencode:
    defaultModel: github-copilot/claude-sonnet-4

• Type: string
• Default: Agent-specific default

agent.[agentName].models

List of available models for a specific agent. Used for model switching in the TUI.

agent:
  claude:
    models:
      - sonnet
      - haiku
      - opus
  copilot:
    models:
      - claude-sonnet-4.5
      - gpt-5.2-codex
      - gemini-3-pro-preview

• Type: string[]
• Default: [] (empty, can be populated via --discover)

Management Commands

View current config:

bloom config

Git Protocol

bloom config set-protocol ssh
bloom config set-protocol https

Agent Defaults

# Set default interactive agent (bloom enter, bloom refine)
bloom config set-interactive claude
bloom config set-interactive goose

# Set default non-interactive agent (bloom run)
bloom config set-noninteractive claude
bloom config set-noninteractive opencode

Model Configuration

# Set default model for an agent
bloom config set-model claude opus
bloom config set-model opencode github-copilot/claude-sonnet-4

# View configured models
bloom config models                       # All agents
bloom config models claude                # Specific agent

# Discover models from agent CLI
bloom config models copilot --discover    # Show available models
bloom config models opencode -d -s        # Discover and save to config

Model discovery works for agents that support it:

• claude: Static list (sonnet, haiku, opus)
• copilot: Parsed from copilot help config
• opencode: From opencode models command

Project Files

PRD.md

Product Requirements Document. Template from template/PRD.md.

Recommended sections:

• Overview
• Problem Statement
• Requirements (Functional, Non-Functional)
• Technical Constraints
• Success Criteria
• Out of Scope

plan.md

Implementation plan. Generated by bloom plan.

Contains:

• Phases
• Steps within phases
• Dependencies
• Technical details

CLAUDE.md

Guidelines for AI agents. Template from template/CLAUDE.template.md.

Recommended sections:

• Code Standards
• Architecture Overview
• Testing Requirements
• Git Practices

tasks.yaml

Task definitions. Generated by bloom generate.

See Task Schema for full reference.

Template Files

Located in template/ directory.

template/PRD.md

Template for new project PRDs.

# [Project Name]

## Overview
[Description]

## Requirements
- [ ] Requirement 1

## Success Criteria
- [ ] Criterion 1

template/plan.md

Template for implementation plans.

# Implementation Plan

## Phase 1: [Name]

### 1.1 [Step]
- Detail 1
- Detail 2

template/CLAUDE.template.md

Template for agent guidelines. Becomes CLAUDE.md in projects.

# Project Guidelines

## Code Style
[Standards]

## Testing
[Requirements]

Directory Structure

Workspace

my-workspace/
├── .gitignore              # Excludes repos/
├── bloom.config.yaml      # Workspace config
├── repos/                  # Repositories
│   ├── backend.git/       # Bare repo
│   ├── backend/           # Default worktree
│   └── backend-feature-x/ # Feature worktree
├── template/              # Project templates
│   ├── PRD.md
│   ├── plan.md
│   └── CLAUDE.template.md
└── my-project/            # Project directory
    ├── PRD.md
    ├── plan.md
    ├── CLAUDE.md
    └── tasks.yaml

User Config

~/.bloom/
└── config.yaml            # User settings

Defaults

Setting	Default
Git protocol	ssh
Task status	todo
Agent	claude-code
Worktree	Repository default branch

Validation

Workspace Config

Must have valid YAML syntax. Repos must have url and name.

Task File

Run validation:

bloom validate

Checks:

• YAML syntax
• Required fields
• Unique IDs
• Valid dependencies
• No circular references