Local Config

Local Configuration

Project-specific devloop settings via .devloop/local.md (NOT git-tracked).

Format

YAML frontmatter followed by optional markdown notes:

---
git:
  auto-branch: false           # Create branch when plan starts
  branch-pattern: "feat/{slug}" # {slug}, {date}, {user}
  main-branch: main
  pr-on-complete: ask          # ask | always | never
  worktree_isolation: false    # Isolate swarm workers in git worktrees (opt-in)

commits:
  style: conventional          # conventional | simple
  scope-from-plan: true
  sign: false

review:
  before-commit: ask           # ask | always | never
  use-plugin: null             # null | code-review | pr-review-toolkit

github:
  link-issues: false           # Enable GH issue linking
  auto-close: ask              # ask | always | never
  comment-on-complete: true

tokens:
  token_budget: 4000           # Max tokens for gather-task-context.sh output (default: 4000)
  cache_friendly_context: true # Order agent prompts for prompt cache hits (default: true)
---

Settings Reference

Example Configurations

Minimal (Git-aware)

---
git:
  auto-branch: true
---

Full CI/CD Workflow

---
git:
  auto-branch: true
  pr-on-complete: always
commits:
  style: conventional
  sign: true
review:
  before-commit: always
  use-plugin: pr-review-toolkit
---

Issue-Driven Development

---
git:
  auto-branch: true
  pr-on-complete: always
github:
  link-issues: true
  auto-close: always
  comment-on-complete: true
---

Worktree Isolation

When running /devloop:run-swarm with many parallel tasks, you can enable git worktree isolation so each worker operates in its own isolated branch. This prevents workers from overwriting each other's in-progress changes.

---
git:
  worktree_isolation: true   # Each swarm worker runs in an isolated git worktree
---

Effect: Equivalent to passing --worktrees to every /devloop:run-swarm invocation. The orchestrator merges results back after each batch. Default is false — opt-in only.

When to enable:

• Large parallel plans (5+ concurrent workers) with overlapping file scopes
• You want maximum isolation between workers at the cost of slightly more git overhead

When to leave off (default):

• Most plans: workers are already assigned non-overlapping tasks
• Single-task or sequential plans
• Environments where git worktrees are not supported

Context & Performance

---
fresh_threshold: 10            # Tasks before suggesting /devloop:fresh (default: 10)
context_threshold: 70          # Exit ralph loop at this context % (default: 70)
---

Token Efficiency

Control how devloop manages context size and prompt caching when spawning agents.

---
tokens:
  token_budget: 4000           # Max tokens for context gathering (default: 4000)
  cache_friendly_context: true # Order agent prompts for prompt cache hits (default: true)
---

token_budget

Passed as --token-budget N to gather-task-context.sh. The script estimates file sizes (~4 chars per token) and stops collecting files once the budget is reached. Files are prioritized:

1. Files directly mentioned in the task description (by name)
2. Files matching keywords in content or filename

When to adjust:

• Lower (1000-2000): Fast swarm runs where many small tasks run in parallel; you want lean context per worker.
• Default (4000): Standard single-task execution; balanced coverage.
• Higher (8000-16000): Complex tasks spanning many files; you want more context per task. Increase fresh_threshold when raising this, as heavier context exhausts session budget faster.

cache_friendly_context

When true (default), agent prompts are structured with static content first (instructions, phase name, project conventions) and dynamic content last (task description, gathered file contents). This maximizes Claude's prompt cache hit rate when multiple agents are spawned in the same session.

Effect: On the 2nd+ agent spawn in a parallel batch, the static prefix is already cached -- reducing latency and API cost. The first spawn always pays the full cost; subsequent spawns only pay for the dynamic suffix.

When to disable: If you are debugging agent prompt content and need to see the exact prompt structure without reordering, set cache_friendly_context: false. This has no other effect.

Plugin Integration

---
plugins:
  superpowers-suggestions: false  # Disable seeAlso to superpowers skills
---

Usage

• Edit .devloop/local.md directly; changes take effect on next command
• Parsed by ${CLAUDE_PLUGIN_ROOT}/scripts/parse-local-config.sh
• Add to .gitignore to keep local-only