Configuration

All configuration files, settings, and customization options.

Project Structure

Fellowship stores all configuration inside the .fellowship/ directory at your project root:

.fellowship/
  config.yaml          # Project settings, AI provider, review, hooks
  team.yaml            # Agent definitions (roles, skills, profiles)
  profiles/            # Agent profile files with coding guidelines
  skills/              # Project-level skill overrides (optional)
  architecture.md      # Project architecture reference
  learnings.md         # Raw lessons from each run
  learnings-distilled.md # Consolidated top learnings (max 30)
  gotchas.md           # Technical pitfalls and warnings
  fellowship.db        # SQLite database (runs, decisions, events)

config.yaml

The main configuration file. Generated by fellowship init or fellowship adopt.

name: my-api
created: '2026-03-11'

ai:
  provider: anthropic
  model: claude-sonnet-4-6
  envVar: ANTHROPIC_API_KEY

# Code review settings
review:
  enabled: true                    # Enable/disable Sentinel
  model: claude-haiku-4-5-20251001 # Cheaper model for reviews
  strictness: balanced             # strict | balanced | lenient
  maxCycles: 2                     # Max review-fix cycles

# Notifications & hooks
hooks:
  onComplete:
    -  sound: done 
    -  notify: desktop 
  onError:
    -  sound: error 
    -  notify: desktop 
  onReview:
    -  sound: review 
    -  notify: desktop 
  sounds: true
  desktop: true

# Documentation generation
scribe:
  enabled: false
  autoRun: false
  model: claude-haiku-4-5-20251001
  outputs: [changelog, readme]

# Learnings search
search:
  maxResults: 10
  minScore: 1.0
  autoIndex: true

# Security
security:
  sanitize: true
  strictMode: false
  logInjections: true

AI Settings

Review Settings

Scribe Settings

Search Settings

Security Settings

Hooks & Notifications

Configure notifications in the hooks: section of config.yaml.

hooks:
  onComplete:
    -  sound: done 
    -  notify: desktop 
    -  notify: telegram 
    - "echo '$FELLOWSHIP_TASK completed' >> ~/fellowship.log"
  onError:
    -  sound: error 
    -  notify: desktop 
  onReview:
    -  sound: review 
    -  notify: desktop 
  sounds: true
  desktop: true
  telegramBotToken: "..."   # or env FELLOWSHIP_TELEGRAM_BOT_TOKEN
  telegramChatId: "..."     # or env FELLOWSHIP_TELEGRAM_CHAT_ID

Hook Events

Hook Actions

Each hook event accepts a list of actions. You can mix and match:

Environment Variables in Custom Hooks

When using custom shell commands, these variables are available:

Custom hook examples

hooks:
  onComplete:
    # Log to a file
    - "echo '$FELLOWSHIP_TASK completed in $FELLOWSHIP_DURATION s' >> ~/fellowship.log"
    # Call a webhook
    - "curl -X POST https://your-api.com/webhook -d '...' "
    # Send a Discord notification
    - "curl -H 'Content-Type: application/json' -d '...' $DISCORD_WEBHOOK_URL"

Setting up Telegram notifications

Step-by-step guide to get Fellowship notifications in Telegram:

1. Create a bot

• Open @BotFather in Telegram
• Send /newbot
• Choose a name (e.g. "Fellowship Notifications")
• Choose a username (e.g. my_fellowship_bot)
• BotFather will give you a token like 123456789:ABCdefGHIjklMNOpqrsTUVwxyz

2. Get your chat ID

• Open @userinfobot in Telegram
• Send /start — it will reply with your ID (a number like 1726726015)

3. Start your bot

• Search for your bot in Telegram by its username
• Press Start — this is required, otherwise the bot can't send you messages

4. Configure Fellowship

Add to your .fellowship/config.yaml:

hooks:
  telegramBotToken: "YOUR_BOT_TOKEN"
  telegramChatId: "YOUR_CHAT_ID"
  onComplete:
    -  notify: telegram 
  onError:
    -  notify: telegram 
  onReview:
    -  notify: telegram 

Or use environment variables instead:

You'll now receive a Telegram message every time a run completes or fails, with the task name, agent, duration, and status.

team.yaml

Defines your agent team. Generated automatically during init or adopt, and extended with fellowship hire.

Each agent has:

• Name — a human-friendly identifier
• Role — what kind of tasks they handle
• Profile — path to a profile file with coding guidelines, skills, and conventions
• Icon — displayed in status and TUI

Skills

Skills are reusable instructions that can be referenced in agent profiles. Fellowship ships with built-in skills, and you can override them with project-level skills.

fellowship/skills/          ← Built-in (shipped with CLI)
  code-review.md            ← Sentinel's review guidelines

.fellowship/skills/         ← Project overrides (optional)
  code-review.md            ← Your custom review guidelines

Project skills override built-in skills with the same name. Profiles reference skills with {{skill:name}}.

Credentials

API keys are stored securely using your system’s credential store:

Use fellowship connect to configure your provider credentials.