init-pappardelle

/init-pappardelle — Set Up Pappardelle in This Repo

Interactive setup wizard that installs Pappardelle, gathers your configuration preferences, checks prerequisites, and generates a .pappardelle.yml file.

Step 0: Check for Existing Configuration

Before starting the wizard, check if a .pappardelle.yml already exists:

test -f "$(git rev-parse --show-toplevel)/.pappardelle.yml" && echo "EXISTS" || echo "NOT_FOUND"

If NOT_FOUND, skip to Step 1.

If EXISTS, read and parse the config file to extract the current configuration, then walk the user through personalization. Use AskUserQuestion for each sub-step — ask them one at a time, don't bundle questions.

0a. Show Current Configuration

Present a summary of the existing config:

Pappardelle is already configured in this repository.

Current configuration:

• VCS Host: {provider}
• Issue Tracker: {provider}
• Team Prefix: {prefix}
• Profiles:
  • {display_name} — keywords: {comma-separated keywords}
  • {display_name} — keywords: {comma-separated keywords}
  • (repeat for each profile)

0b. Add a New Profile?

Ask: "Do any of the existing profiles fit your use case, or would you like to add a new one?"

• If they're happy with existing profiles, move on.
• If they want a new profile, gather the same info as Step 1c (display name, keywords, project type, commands) and add it to .pappardelle.yml.

0c. Default Profile

Ask: "Which profile should be your default? (This is the profile used when no keywords match your issue.)"

List the available profiles by name. If they pick one that differs from the current default_profile, write/update .pappardelle.local.yml with the override:

default_profile: their-choice

If they pick the one that's already the default, skip writing.

0d. Dangerously Skip Permissions

Show the current dangerously_skip_permissions value and ask: "Should Claude start in 'yolo mode' — automatically approving all tool calls? (Currently: {yes/no})"

• If they want to change it, write/update .pappardelle.local.yml with the override:

  claude:
    dangerously_skip_permissions: true  # or false
  

• If they're happy with the current value, skip.

0e. Write Local Overrides

If any local overrides were collected in 0c–0d, write or update .pappardelle.local.yml. Preserve any existing content (e.g., keybindings, issue_watchlist) — only add/update the fields that changed.

After this, skip to Step 6 (Summary) — print a summary of what was configured and launch instructions.

Step 1: Gather Configuration

Use AskUserQuestion for each of these. Ask them one at a time — don't bundle questions.

1a. VCS Host

Ask: "Which VCS host do you use?"

Options:

• GitHub (default) — requires gh CLI
• GitLab — requires glab CLI. If selected, follow up asking if it's gitlab.com or self-hosted (get the host value).
• Other — Pappardelle only supports GitHub and GitLab. Let the user know and stop.

1b. Issue Tracker

Ask: "Which issue tracker do you use?"

Options:

• Linear (default) — requires linctl CLI
• Jira — requires acli CLI. If selected, follow up asking for their Jira base URL (e.g., https://mycompany.atlassian.net).
• Neither / Other — Pappardelle requires Linear or Jira. Let the user know and stop.

1c. Team Prefix & Profiles

Ask: "What are your issue key prefixes? For example, if your issues look like PROJ-123, the prefix is PROJ. If you have multiple teams/projects with different prefixes (e.g., FE-123, BE-456), list them all."

Single prefix (e.g., they say just "PROJ"):

• Set the global team_prefix: PROJ
• Create one default profile with no keywords (it catches everything)
• Ask what kind of project it is (iOS app, backend, frontend, etc.) to generate sensible display_name and commands

Multiple prefixes (e.g., they say "FE for frontend, BE for backend, MOB for mobile"):

• Set the global team_prefix to whichever prefix they use most (ask if unclear)
• Create one profile per prefix:
  • Slug name: kebab-case of the project name (e.g., frontend, backend, mobile)
  • display_name: human-readable name they gave
  • keywords: include the prefix with hyphen (e.g., ["FE-"]) — this is how Pappardelle auto-selects the profile when the user enters an issue key like FE-123
  • team_prefix: set per-profile to override the global prefix for issue creation
  • commands: reasonable setup commands based on project type (e.g., npm install for Node.js, xcodegen generate for iOS)
• Set default_profile to the most common one

1d. Claude initialization command

Ask: "Would you like Claude to run a skill automatically when a new workspace is created? The default is /do which starts planning and implementing the issue."

Options:

• Yes, use /do (default) — set initialization_command: '/do'
• Custom — let them type a skill name
• No — omit the claude section

If they chose /do, also offer to install the starter /do skill:

mkdir -p .claude/skills/do && curl -fsSL https://raw.githubusercontent.com/chardigio/pappardelle/main/examples/skills/do/SKILL.md -o .claude/skills/do/SKILL.md

1e. Dangerously Skip Permissions ("Yolo Mode")

Ask: "Should Claude start in 'yolo mode' — automatically approving all tool calls without asking for permission? (This sets dangerously_skip_permissions: true in your config)"

Options:

• No (default) — set dangerously_skip_permissions: false
• Yes — set dangerously_skip_permissions: true. Warn the user: "This means Claude can read, write, and execute anything without confirmation. Only enable this if you trust the skills and prompts being used in your workspaces."

This setting is only relevant if a claude section exists (i.e., the user chose an initialization command in 1d). If they opted out of claude in 1d, skip this question.

Step 2: Install Pappardelle

Check if Pappardelle is already installed:

command -v pappardelle &>/dev/null && echo "INSTALLED" || echo "NOT_INSTALLED"

• If not installed, tell the user you'll install it now and run the install script:

curl -fsSL https://raw.githubusercontent.com/chardigio/pappardelle/main/install.sh | bash

The install script checks base prerequisites (Node.js >= 18, npm, git, tmux, jq), clones the repo, builds it, and makes pappardelle and idow available globally. If it fails due to missing prerequisites, help the user install them (e.g., brew install node tmux jq) and re-run.

• If already installed, print "Pappardelle is already installed" and move on.

Step 3: Check Prerequisites & Provider CLIs

Now that you know which providers they chose, check the required tools and provider-specific CLIs. Run these checks in a single bash command:

echo "=== Required ===" && \
for cmd in node npm git tmux jq yq claude; do printf "%-10s %s\n" "$cmd" "$(command -v $cmd >/dev/null 2>&1 && echo '✓' || echo '✗ MISSING')"; done && \
echo "=== Provider CLIs ===" && \
for cmd in <VCS_CLI> <TRACKER_CLI> lazygit; do printf "%-10s %s\n" "$cmd" "$(command -v $cmd >/dev/null 2>&1 && echo '✓' || echo '✗ MISSING')"; done

Replace <VCS_CLI> with gh (GitHub) or glab (GitLab), and <TRACKER_CLI> with linctl (Linear) or acli (Jira) based on the answers from Step 1.

• If any required tools are missing, stop and do not proceed to Step 4. Tell the user which ones are missing and offer to install them via brew install <tool> (or the appropriate install command for Claude Code: curl -fsSL https://claude.ai/install.sh | bash). Use AskUserQuestion to confirm before installing. Re-run the check after installation and only proceed once all required tools pass.
• If any provider CLIs are missing, warn the user but allow proceeding — Pappardelle will work but some features will be degraded.
• If all tools are present, move on.

Step 4: tmux Configuration

Ask: "Would you like me to add the recommended tmux config? It enables mouse support, pane navigation with Ctrl+Shift+arrow keys, and a clean status bar. (I'll append to ~/.tmux.conf)"

If yes, fetch the recommended config and append it to ~/.tmux.conf (skip any settings that already exist):

curl -fsSL https://raw.githubusercontent.com/chardigio/pappardelle/main/examples/tmux.conf >> ~/.tmux.conf

Check if ~/.tmux.conf exists first and read it — if settings already exist, skip the duplicates rather than appending blindly.

If they decline, move on.

Step 5: Generate .pappardelle.yml

Based on the answers, generate a .pappardelle.yml file at the repository root. Use the full config format from the configuration reference.

Rules:

• Always include version: 1
• Always issue_tracker
• Always vcs_host
• Always include team_prefix
• Single prefix: one profile with no keywords, set as default_profile
• Multiple prefixes: one profile per prefix, each with keywords: ["PREFIX-"] (include the hyphen) and a per-profile team_prefix override. Set default_profile to the most common one

Step 6: Summary

After writing the file, print a summary:

1. What was configured (providers, profiles)
2. How to launch: pappardelle
3. Link to the full config reference: pappardelle-config.md for customizing keybindings, post-worktree hooks, lifecycle hooks, and more

Example Outputs

Single prefix (GitHub + Linear)

version: 1

# Issue key prefix (e.g., PROJ-123)
team_prefix: PROJ

# VCS host
vcs_host:
  provider: github

# Issue tracker
issue_tracker:
  provider: linear

# Claude configuration
claude:
  initialization_command: '/do'
  dangerously_skip_permissions: false

# Commands to run after git worktree is created
post_workspace_init:
  - name: 'Copy .env'
    run: 'cp -n ${REPO_ROOT}/.env ${WORKTREE_PATH}/.env 2>/dev/null || true'

# Custom keybindings
keybindings:
  - key: 'c'
    name: 'Clear context'
    send_to_claude: '/clear'

# Profiles
profiles:
  default:
    display_name: 'Default'
    links:
      - url: '${ISSUE_URL}'
        title: 'Linear Issue'
      - url: '${PR_URL}'
        title: 'GitHub PR'
        if_set: 'PR_URL'

Multiple prefixes (GitLab + Jira)

version: 1

# Issue key prefix (most common one — FE is the default for bare numbers)
team_prefix: FE

# VCS host
vcs_host:
  provider: gitlab
  host: gitlab.mycompany.com

# Issue tracker
issue_tracker:
  provider: jira
  base_url: https://mycompany.atlassian.net

# Claude configuration
claude:
  initialization_command: '/do'
  dangerously_skip_permissions: false

# Commands to run after git worktree is created
post_workspace_init:
  - name: 'Copy .env'
    run: 'cp -n ${REPO_ROOT}/.env ${WORKTREE_PATH}/.env 2>/dev/null || true'

# Custom keybindings
keybindings:
  - key: 'c'
    name: 'Clear context'
    send_to_claude: '/clear'

# Profiles
profiles:
  frontend:
    display_name: 'Frontend'
    team_prefix: FE
    keywords:
      - FE-
      - frontend
    links:
      - url: '${ISSUE_URL}'
        title: 'Jira Issue'
      - url: '${MR_URL}'
        title: 'GitLab MR'
        if_set: 'MR_URL'

  backend:
    display_name: 'Backend'
    team_prefix: BE
    keywords:
      - BE-
      - backend
    links:
      - url: '${ISSUE_URL}'
        title: 'Jira Issue'
      - url: '${MR_URL}'
        title: 'GitLab MR'
        if_set: 'MR_URL'

  mobile:
    display_name: 'Mobile'
    team_prefix: MOB
    keywords:
      - MOB-
      - mobile
    links:
      - url: '${ISSUE_URL}'
        title: 'Jira Issue'
      - url: '${MR_URL}'
        title: 'GitLab MR'
        if_set: 'MR_URL'