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
  },
  "issues": {
    "autoClose": true
  },
  "failures": {
    "expiryDays": 90
  },
  "models": {
    "quest": null,
    "scout": null,
    "palantir": null,
    "balrog": null,
    "explore": null,
    "validator": null
  }
}

Settings Reference

Enforced by marks how a setting takes effect: Binary settings are read and applied by the fellowship Go CLI itself; Prompt settings are followed by the agent reading the merged config from skill/agent instructions, with no structural enforcement behind them.

Setting	Default	Enforced by	Description
`dataDir`	`".fellowship"`	Binary	Directory name for fellowship working files (state, checkpoints, todos, history). Created inside each worktree and the main repo root.
`branch.pattern`	`null`	Prompt	Branch name template with placeholders: {slug}, {ticket}, {author}. When null, defaults to "fellowship/{slug}".
`branch.author`	`null`	Prompt	Static value for the {author} placeholder. If not set and pattern uses {author}, you'll be prompted.
`branch.ticketPattern`	`"[A-Z]+-\\d+"`	Prompt	Regex to extract ticket IDs from quest descriptions. Default matches Jira-style IDs (e.g., PROJ-123).
`worktree.enabled`	`true`	Prompt	Whether quests create isolated worktrees. Set to false to work on the current branch.
`worktree.directory`	`null`	Prompt	Parent directory for worktrees. null uses Claude Code's default (.claude/worktrees/).
`gates.autoApprove`	`[]`	Binary	Gate names to auto-approve: "Research", "Plan", "Implement" — the phase being left. "Review" is not valid: it is the last phase and no gate leaves it. Gates not listed still surface to you.
`pr.draft`	`false`	Prompt	Create PRs as drafts.
`pr.template`	`null`	Prompt	PR body template string. Supports {task}, {summary}, and {changes} placeholders.
`palantir.enabled`	`true`	Prompt	Whether to spawn a palantir monitoring agent during fellowships.
`palantir.minQuests`	`2`	Prompt	Minimum active quests before palantir is spawned.
`issues.autoClose`	`true`	Prompt	When true, /missive includes "Closes #N" in PR keywords so issues close on merge.
`failures.expiryDays`	`90`	Binary	Days before a quest failure record expires and is eligible for cleanup.
`models.quest`	`null`	Prompt	Model for quest teammates. Valid values: "haiku", "sonnet", "opus" (aliases only — spawn parameters accept neither "inherit" nor full model IDs; leave null to inherit). null = built-in default: inherit the session model.
`models.scout`	`null`	Prompt	Model for scout teammates. Same valid values. null = built-in default: sonnet.
`models.palantir`	`null`	Prompt	Model for the palantir monitor. Same valid values. null = built-in default: haiku.
`models.balrog`	`null`	Prompt	Model for balrog adversarial review. Same valid values. null = built-in default: inherit the session model.
`models.explore`	`null`	Prompt	Model for Explore scan subagents spawned by quest, scout, council, and guide. Same valid values. null = built-in default: haiku.
`models.validator`	`null`	Prompt	Model for scout's validation subagent. Same valid values. null = built-in default: sonnet.

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 a quest flows from 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 the Research and Plan gates for faster iteration — you still review at the Implement gate, the last one before the PR.

3. No worktrees, minimal oversight

fellowship.json

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

Works on the current branch without worktree isolation. Auto-approves all three gates, so a quest runs start to finish without pausing. No palantir monitoring. Use for trusted, low-risk tasks.