Configuration

Overview

Fellowship reads configuration from two files and merges them at startup. ~/.claude/fellowship.json is your personal cross-project config. .fellowship/config.json at the repo root is a per-project config checked into source control. Settings are merged in order: built-in defaults → project config → user config. User config always wins. All settings are optional; missing keys use sensible defaults.

Project Config

Place a .fellowship/config.json file at the root of your repository to share team-wide defaults. Useful for enforcing a consistent branch naming convention or gate policy across everyone who works on the project. Individual team members can still override any setting in their personal ~/.claude/fellowship.json.

.fellowship/config.json

{
  "branch": {
    "pattern": "feat/{ticket}-{slug}"
  },
  "gates": {
    "autoApprove": []
  },
  "pr": {
    "draft": true
  }
}

Complete Configuration

~/.claude/fellowship.json

{
  "dataDir": ".fellowship",
  "branch": {
    "pattern": null,
    "author": null,
    "ticketPattern": "[A-Z]+-\\d+"
  },
  "worktree": {
    "enabled": true,
    "directory": null
  },
  "gates": {
    "autoApprove": []
  },
  "pr": {
    "draft": false,
    "template": null
  },
  "palantir": {
    "enabled": true,
    "minQuests": 2
  }
}

Settings Reference

Setting	Default	Description
`dataDir`	`".fellowship"`	Directory name for fellowship working files (state, checkpoints, errands, tome). Created inside each worktree and the main repo root.
`branch.pattern`	`null`	Branch name template with placeholders: {slug}, {ticket}, {author}. When null, defaults to "fellowship/{slug}".
`branch.author`	`null`	Static value for the {author} placeholder. If not set and pattern uses {author}, you'll be prompted.
`branch.ticketPattern`	`"[A-Z]+-\\d+"`	Regex to extract ticket IDs from quest descriptions. Default matches Jira-style IDs (e.g., PROJ-123).
`worktree.enabled`	`true`	Whether quests create isolated worktrees. Set to false to work on the current branch.
`worktree.directory`	`null`	Parent directory for worktrees. null uses Claude Code's default (.claude/worktrees/).
`gates.autoApprove`	`[]`	Gate names to auto-approve: "Research", "Plan", "Implement", "Review", "Complete". Gates not listed still surface to you.
`pr.draft`	`false`	Create PRs as drafts.
`pr.template`	`null`	PR body template string. Supports {task}, {summary}, and {changes} placeholders.
`palantir.enabled`	`true`	Whether to spawn a palantir monitoring agent during fellowships.
`palantir.minQuests`	`2`	Minimum active quests before palantir is spawned.

Common Setups

1. Auto-approve research, custom branch pattern

fellowship.json

{
  "branch": {
    "pattern": "{author}/{ticket}/{slug}",
    "author": "justin"
  },
  "gates": {
    "autoApprove": ["Research"]
  }
}

Auto-approves the Research gate so quests flow from Onboard straight through Research into Plan without pausing. Branch names include your name and Jira ticket.

2. Team workflow with draft PRs

fellowship.json

{
  "pr": {
    "draft": true,
    "template": "## Summary\n{summary}\n\n## Changes\n{changes}\n\n## Task\n{task}"
  },
  "gates": {
    "autoApprove": ["Research", "Plan"]
  }
}

Creates draft PRs with a custom template. Auto-approves Research and Plan gates for faster iteration — you still review at Implement, Review, and Complete.

3. No worktrees, minimal oversight

fellowship.json

{
  "worktree": {
    "enabled": false
  },
  "gates": {
    "autoApprove": ["Research", "Plan", "Implement", "Review"]
  },
  "palantir": {
    "enabled": false
  }
}

Works on the current branch without worktree isolation. Auto-approves everything except Complete (PR creation). No palantir monitoring. Use for trusted, low-risk tasks.