{"id":49743656,"url":"https://github.com/chardigio/pappardelle","last_synced_at":"2026-06-01T13:00:36.000Z","repository":{"id":337477497,"uuid":"1153663770","full_name":"chardigio/pappardelle","owner":"chardigio","description":"A TUI for multi-clauding without losing your marbles","archived":false,"fork":false,"pushed_at":"2026-05-26T09:00:50.000Z","size":9374,"stargazers_count":16,"open_issues_count":0,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-26T11:04:23.228Z","etag":null,"topics":["agent-orchestration","claude","claude-code","multi-claude","multi-clauding","tui"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chardigio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-09T14:59:31.000Z","updated_at":"2026-05-26T09:00:43.000Z","dependencies_parsed_at":null,"dependency_job_id":"a8ae13cd-2cae-4001-b00e-5025a066ed31","html_url":"https://github.com/chardigio/pappardelle","commit_stats":null,"previous_names":["chardigio/pappardelle"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/chardigio/pappardelle","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chardigio%2Fpappardelle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chardigio%2Fpappardelle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chardigio%2Fpappardelle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chardigio%2Fpappardelle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chardigio","download_url":"https://codeload.github.com/chardigio/pappardelle/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chardigio%2Fpappardelle/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33775864,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-orchestration","claude","claude-code","multi-claude","multi-clauding","tui"],"created_at":"2026-05-09T23:59:25.131Z","updated_at":"2026-06-01T13:00:35.986Z","avatar_url":"https://github.com/chardigio.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🦀🍝🦀 Pappardelle 🦀🍝🦀\n\n[![Test](https://github.com/chardigio/pappardelle/actions/workflows/test.yml/badge.svg)](https://github.com/chardigio/pappardelle/actions/workflows/test.yml)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\nA TUI for multi-clauding without losing your marbles.\n\nYou type a description, it reads or creates an issue in Linear/Jira, spawns a configured git worktree, builds a PR/MR, and starts a Claude Code session alongside a lazygit session — all wired together in a 3-pane tmux layout you can navigate with simple, customizable keystrokes.\n\n**Video:**\n\nhttps://github.com/user-attachments/assets/abeaf413-5a1e-448a-ac53-2956a8ada5bf\n\n---\n\n## Table of Contents\n\n1. [Installation and Getting Started](#1-installation-and-getting-started)\n2. [Understanding tmux in Pappardelle](#2-understanding-tmux-in-pappardelle)\n3. [Spawning New Sessions](#3-spawning-new-sessions)\n4. [Spec-Driven Development Mindset](#4-spec-driven-development-mindset)\n5. [Customizing Your Configuration](#5-customizing-your-configuration)\n6. [Advanced: Doom-coding with Pappardelle](#6-advanced-doom-coding-with-pappardelle)\n7. [Advanced: Wrangling Multi-Repo Changes](#7-advanced-wrangling-multi-repo-changes)\n8. [Reference](#8-reference)\n\n---\n\n## 1. Installation and Getting Started\n\nThe fastest way to get set up is with `/init-pappardelle`.\n\nAdd the marketplace:\n\n```bash\nclaude plugin marketplace add chardigio/pappardelle\n```\n\nInstall the plugin. This installs four skills — `/init-pappardelle` (setup wizard), `/update-pappardelle` (update to latest), `/configure-pappardelle` (interactive config editor), and `/sous-chef` (optional workspace coordinator):\n\n```bash\nclaude plugin install pappardelle@pappardelle-marketplace\n```\n\nRun the setup wizard from any repo where you want to use Pappardelle. This installs pappardelle configures your .pappardelle.yml:\n\n```bash\nclaude /init-pappardelle\n```\n\nFor manual installation, see [Section 8: Reference](#8-reference). For the full config format, see the [configuration reference](pappardelle-config.md).\n\n### Launch Pappardelle:\n\n```bash\npappardelle\n```\n\n![Screenshot 2026-03-02 at 4.18.44 PM](assets/Screenshot%202026-03-02%20at%204.18.44%E2%80%AFPM.png)\n\n---\n\n## 2. Understanding tmux in Pappardelle\n\n### The 3-pane layout\n\nWhen you launch `pappardelle`, it creates a tmux session with three panes:\n\n- **Left pane** shows the ticket rail. This is where you navigate workspaces, create new ones, and trigger actions.\n- **Center pane** shows the Claude Code session for whichever workspace is highlighted.\n- **Right pane** shows [lazygit](https://github.com/jesseduffield/lazygit) for the highlighted workspace's worktree.\n\n### How nested sessions work\n\nEach workspace creates two independent tmux sessions:\n\n- `claude-{repo}-{issue-key}` — runs Claude Code\n- `lazygit-{repo}-{issue-key}` — runs lazygit\n\nThe center and right panes in the Pappardelle session are \"viewers\" — they run nested tmux clients that attach to these independent sessions. When you highlight a different workspace in the list, Pappardelle uses `tmux switch-client` to instantly swap which session the viewer pane displays.\n\nThis means:\n\n- **Workspaces are independent.** Each Claude session runs in its own tmux session. If Pappardelle crashes, your Claude sessions keep running.\n- **Attach from anywhere.** You can attach to any workspace's Claude session from a separate terminal: `tmux attach -t claude-stardust-labs-STA-631`.\n- **Switching is instant.** After the first attachment, switching between workspaces uses tmux's fast `switch-client` path — no process restart, no visible flash.\n\n### Recommended tmux config\n\nPappardelle works with any tmux configuration, but these settings improve the experience — mouse support, Ctrl+Shift+arrow pane navigation, and a clean status bar. See [`examples/tmux.conf`](examples/tmux.conf) and append to your `~/.tmux.conf`. If you don't have one yet:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/chardigio/pappardelle/main/examples/tmux.conf -o ~/.tmux.conf\n```\n\n### Exiting Pappardelle\n\nPress `q` in the workspace list pane to quit. This kills the Pappardelle tmux session and all its viewer panes, returning you to your original terminal. Your Claude and lazygit workspace sessions are **not** affected — they run in independent tmux sessions and will keep going after Pappardelle exits. To reattach, just run `pappardelle` again.\n\nTo also kill all workspace sessions, use `Delete` on each workspace from the TUI before quitting, or nuke everything with:\n\n```bash\ntmux kill-server\n```\n\n---\n\n## 3. Spawning New Sessions\n\n### From the TUI\n\nPress `n` in the workspace list to open the prompt dialog.\n\n![New session dialog](assets/new-session-dialog.png)\n\n### What gets provisioned\n\nWhen you create a workspace, Pappardelle runs through these steps:\n\n1. **Profile selection** — Your input is keyword-matched against a profile in `.pappardelle.yml`.\n\n2. **Issue creation/fetch** — For new descriptions, a Linear (or Jira) issue is created with a WIP title. For existing issue keys, the issue is fetched.\n\n3. **Git worktree** — An isolated worktree is created at `~/.worktrees/{repo-name}/{issue-key}/`. This is a full working copy of your repo on a new branch, completely isolated from your main checkout.\n\n4. **PR/MR creation** — A placeholder PR (GitHub) or MR (GitLab) is created from the new branch.\n\n5. **Project setup** — Profile `commands` are executed (e.g., `xcodegen generate`, dependency installs). Top-level `post_workspace_init` commands also run after the worktree is created (e.g., copying `.env` files).\n\n6. **Claude \u0026 lazygit sessions spawned** — A named tmux session is created and Claude Code is launched inside it. If `claude.initialization_command` is set in `.pappardelle.yml` (e.g., `/do`), that command is passed to Claude along with the issue key. A lazygit session rooted at the worktree dir is also spawned.\n\n---\n\n## 4. Spec-Driven Development Mindset\n\n![Spec-driven development in Linear](assets/spec-driven-development-linear.png)\n\nPappardelle's recommended `/do` skill (set via `claude.initialization_command` in `.pappardelle.yml`) starts every Claude session with a **planning-first workflow**. Before writing any code, the agent researches and uses Claude Code's `AskUserQuestion` tool to clarify requirements — asking about ambiguous scope, confirming design decisions, and validating edge cases. The goal is to turn a rough prompt into a detailed, unambiguous spec — **written back to the issue description** — before the first line of code is written.\n\n### Why this matters\n\nA one-line prompt like \"add dark mode to settings\" leaves a lot of questions open: which settings screen? System preference or manual toggle? What colors? The `/do` skill instructs the agent to surface these questions upfront rather than guessing. This front-loaded clarification produces better code on the first pass and fewer revision cycles.\n\n### Automatic Q\u0026A documentation\n\nEvery `AskUserQuestion` exchange is automatically posted as a comment on the Linear or Jira issue by the [`comment-question-answered.py`](hooks/comment-question-answered.py) hook. This means:\n\n- **The issue becomes the single source of truth.** The original prompt, every clarifying question, and every answer are all captured in one place — not scattered across chat windows or terminal scrollback.\n- **Anyone reviewing the PR can see the full context.** The issue thread shows exactly what the agent asked, what the developer decided, and why.\n- **Record-keeping is automatic.** You don't need to manually document decisions or copy-paste from the terminal. The hook handles it silently in the background.\n\n---\n\n## 5. Customizing Your Configuration\n\nUse `/configure-pappardelle` to interactively edit your config — it walks you through adding profiles, keybindings, hooks, and more using `AskUserQuestion`. Available via the [plugin marketplace](#plugin-marketplace) or by asking Claude directly (it's model-invocable).\n\nPappardelle is configured via a `.pappardelle.yml` file at your repo root. The key concepts:\n\n- **Issue watchlist** — Auto-discover issues assigned to you and spawn workspaces for them. Pappardelle polls your issue tracker and creates workspaces for new matching issues. Filter by status, labels, or `key_prefixes` (e.g. watch `STA-*` but not `WAB-*` when one account spans multiple workspaces).\n- **Auto-remove when done** — Opt-in flag (`auto_remove_when_done: true`) that drops a space from the rail as soon as the tracker reports its issue as completed or canceled. Same teardown as pressing `d`; the on-disk worktree is left untouched.\n- **Profiles** — Per-project-type config (keywords, setup commands, VCS labels, optional `emoji:` shown in the ticket rail). Pappardelle keyword-matches your input to auto-select the right profile. Each profile's `tracker_projects` list both routes existing issues to the right profile and (Linear only) lands brand-new issues in `tracker_projects[0]`.\n- **Template variables** — All string values support `${VAR_NAME}` expansion (`${ISSUE_KEY}`, `${WORKTREE_PATH}`, `${PR_URL}`, profile `vars`, env vars, etc.).\n- **Custom keybindings** — Bind single keys to bash commands (`run`) or Claude directives (`send_to_claude`).\n- **Providers** — Pluggable issue trackers (Linear, Jira) and VCS hosts (GitHub, GitLab). Defaults to Linear + GitHub.\n- **Built-in file copies** — `.pappardelle.local.yml` and `.claude/settings.local.json` are automatically copied from the main repo to new worktrees (if they exist).\n- **Workspace lifecycle hooks** — `post_workspace_init` commands run after worktree creation (e.g., copying `.env` files, installing dependencies). `pre_workspace_deinit` commands run before workspace deletion (e.g., closing issues, removing worktrees).\n\nFor the full schema, all fields, and examples, see the [configuration reference](pappardelle-config.md).\n\nFor a production `.pappardelle.yml` used across a polyglot monorepo (Python backends + Swift iOS apps), see [`examples/monorepo-pappardelle.yml`](examples/monorepo-pappardelle.yml).\n\n---\n\n## 6. Advanced: Doom-coding with Pappardelle\n\n**Video:**\n\nhttps://github.com/user-attachments/assets/824307b7-73a6-48d2-918f-4a2d75fcb39b\n\nBecause Pappardelle runs entirely inside tmux, you can access your full workspace setup from anywhere — all you need is an SSH connection to the machine running it.\n\n### What you need\n\n- **A machine that stays on** — I'm not a Mac Mini guy (yet), I just keep my MacBook plugged in. macOS won't sleep with the lid closed as long as it has power and an active SSH session.\n- **[Tailscale](https://tailscale.com/)** — A mesh VPN that makes your dev machine accessible from any network without port forwarding or firewall configuration. Install on both your dev machine and your mobile device.\n- **[Termius](https://termius.com/)** (iOS) — A full-featured SSH client for iPhone and iPad with good tmux support, copy/paste, and keyboard shortcuts.\n\n### Nice-to-haves\n\n- **[ntfy](https://ntfy.sh/)** — Push notifications to your phone when Claude needs input. Pappardelle ships with a [`zap-notification.py`](hooks/zap-notification.py) hook that sends a push via ntfy whenever Claude asks a question or hits a permission prompt. To get it working, set the `PAPPARDELLE_NTFY_TOPIC` environment variable and subscribe to the same topic in the ntfy app on your phone — the hook only fires when an Tailscale SSH session is active. This way you don't have to babysit the terminal — just wait for the buzz.\n- **[Wispr Flow](https://apps.apple.com/us/app/wispr-flow-ai-voice-keyboard/id6497229487)** — Voice-to-text dictation that works system-wide, including inside Termius. Lets you talk to Claude instead of thumb-typing on a phone keyboard.\n\n### Recommended Termius keyboard shortcuts\n\nTermius lets you customize the shortcut bar above the on-screen keyboard — these are my favorite groups for Pappardelle:\n\n![Termius keyboard shortcuts](assets/termius-keyboard-shortcuts.jpg)\n\n- **Arrow keys** — scroll through Claude output and navigate the workspace list\n- **pgUp / pgDn** — cycle between tmux panes (requires the `PageUp`/`PageDown` bindings from [`examples/tmux.conf`](examples/tmux.conf))\n- **esc / ^C** — cancel prompts, exit modes\n- **paste / tab / ctrl / alt** — general terminal essentials\n\nAlso recommended: toggle on **Settings \u003e Hide the AI widget** in Termius for extra screen real estate.\n\n### Useful keybindings\n\nWhen you're doom-coding from your phone, you want one-tap access to open the PR on the device in your hand. Bind a key that sends an ntfy notification with a clickable link:\n\n```yaml\nkeybindings:\n  - key: 'z'\n    name: 'Zap PR'\n    # Use `--search \"head:${ISSUE_KEY}\"` (tokenized prefix match) rather than\n    # `--head ${ISSUE_KEY}` (exact match) so follow-up branches like\n    # ${ISSUE_KEY}-FOLLOW-1 are also discoverable from the parent issue key.\n    # Sort by updatedAt desc — when a branch name has been reused (e.g. an\n    # old merged PR + a freshly opened one), surface the PR you're actually\n    # working on, not the oldest stale match.\n    run: \u003e\n      PR_JSON=$(gh pr list --search \"head:${ISSUE_KEY}\" --state all --json number,url,updatedAt\n        -q 'sort_by(.updatedAt) | reverse | .[0]' 2\u003e/dev/null);\n      PR_NUM=$(echo \"$PR_JSON\" | jq -r '.number // empty');\n      PR_URL=$(echo \"$PR_JSON\" | jq -r '.url // empty');\n      if [ -n \"$PR_NUM\" ]; then\n        curl -d \"${ISSUE_KEY} GitHub PR #$PR_NUM\"\n          -H \"Click: $PR_URL\"\n          ntfy.sh/${PAPPARDELLE_NTFY_TOPIC};\n      fi\n```\n\nPress `z` on a workspace and your phone buzzes with a notification — tap it and the PR opens in the GitHub app.\n\n---\n\n## 7. Advanced: Wrangling Multi-Repo Changes\n\nPappardelle is designed for single-repo workflows, but (experimentally) you can extend it to orchestrate changes across multiple repositories using a parent (pappa) repo.\n\n### The setup\n\nCreate a parent repository that serves as the orchestration hub:\n\n```\nmy-workspace/\n├── .pappardelle.yml\n├── .claude/\n│   ├── settings.json         # shared settings + plugins\n│   └── skills/\n│       ├── do/\n│       │   └── SKILL.md      # initialization skill\n│       └── address-mr-feedbacks/\n│           └── SKILL.md      # orchestration skill\n└── CLAUDE.md\n```\n\nThe parent repo's primary purpose is to share settings, context, and orchestration skills to coordinate work across child repos. Child repos are **not** committed to the parent — they're shallow-cloned on demand during workspace setup.\n\n### Spawning agents in child repos\n\nMulti-repo work has been an achilles heel for Claude Code in the past, but I'm hoping **[Agent Teams](https://code.claude.com/docs/en/agent-teams)** can help solve this. One key unlock with agent teams is that teammates can be spawned in _separate directories_, meaning we can have a parent repo, but then spawn an agent per relevant child repo, which is nice because it automatically loads that repo's CLAUDE.md, skills, settings, etc.\n\n### On-demand shallow cloning\n\nRepos are pulled down as needed, not upfront. During the planning phase, use a search tool like SourceBot's `codesearch` MCP to identify which repos are relevant, then shallow-clone only what you need:\n\n```bash\ngit clone --depth 1 https://github.com/org/repo-a.git\n```\n\nThis keeps initialization fast and reduces noise for the agent while it greps and globs. Because we use `--depth 1`, only the latest commit is fetched — no full history.\n\n### Plugin skills vs. parent repo skills\n\nOne key distinction for multi-repo work is between plugin skills and parent repo skills:\n\n- **Plugin skills** (added in the parent repo's `settings.json` but defined elsewhere) are skills that can be used by any repo / agent teammate receives automatically. These handle single-repo concerns.\n\n  Example: An `/address-mr-feedback` plugin that lets any agent look at its own repo's MR and address reviewer comments.\n\n- **Parent repo skills** (in the parent repo's `.claude/skills/`) are orchestration skills that spawn agent teams across child repos.\n\n  Example: An `/address-mr-feedbacks` (plural) skill that spins up an agent team, spawning one agent per relevant child repo — each agent calls the plugin's singular skill for its own MR.\n\n### Example `/do` skill for multi-repo\n\nA starter `/do` skill tailored for multi-repo workflows is available at [`examples/skills/do-multi-repo/SKILL.md`](examples/skills/do-multi-repo/SKILL.md). It covers shallow cloning, agent team spin-up, per-repo QA, and coordinated PR creation. Install it into your parent repo with:\n\n```bash\nmkdir -p .claude/skills/do \u0026\u0026 curl -fsSL https://raw.githubusercontent.com/chardigio/pappardelle/main/examples/skills/do-multi-repo/SKILL.md -o .claude/skills/do/SKILL.md\n```\n\n### Useful keybindings\n\nBind keys to open specific child repos in your editor for quick navigation:\n\n```yaml\nkeybindings:\n  - key: 's'\n    name: 'Open repo-a in Cursor'\n    run: 'open -a \"Cursor\" \"${WORKTREE_PATH}/repo-a\" 2\u003e/dev/null || open -a \"Cursor\" \"${REPO_ROOT}/repo-a\"'\n```\n\nNote the fallback to `${REPO_ROOT}/repo-a` here ensures this shortcut works in the `master`/`main` space.\n\n---\n\n## 8. Reference\n\n### Prerequisites\n\n| Tool                                                                   | Required | Install                                                            |\n| ---------------------------------------------------------------------- | -------- | ------------------------------------------------------------------ |\n| Node.js \u003e= 18                                                          | Yes      | `brew install node`                                                |\n| npm                                                                    | Yes      | Comes with Node.js                                                 |\n| git                                                                    | Yes      | `brew install git`                                                 |\n| tmux                                                                   | Yes      | `brew install tmux`                                                |\n| jq                                                                     | Yes      | `brew install jq`                                                  |\n| [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) | Yes      | `curl -fsSL https://claude.ai/install.sh \\| bash`                  |\n| [linctl](https://github.com/raegislabs/linctl)                         | Optional | `brew tap raegislabs/linctl \u0026\u0026 brew install linctl` (for Linear)   |\n| [gh](https://cli.github.com/)                                          | Optional | `brew install gh` (for GitHub)                                     |\n| [glab](https://gitlab.com/gitlab-org/cli)                              | Optional | `brew install glab` (for GitLab)                                   |\n| [acli](https://developer.atlassian.com/)                               | Optional | `brew tap atlassian/homebrew-acli \u0026\u0026 brew install acli` (for Jira) |\n\n### Manual installation\n\nIf you prefer to install without the `/init-pappardelle` skill:\n\n**One-line install:**\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/chardigio/pappardelle/main/install.sh | bash\n```\n\n**From a local clone:**\n\n```bash\ngit clone https://github.com/chardigio/pappardelle.git\ncd pappardelle\n./install.sh\n```\n\n**Manual install:**\n\n```bash\ngit clone https://github.com/chardigio/pappardelle.git\ncd pappardelle\nnpm install\nnpm run build\nnpm link                # makes `pappardelle` available globally\n./hooks/install.sh      # installs Claude Code hooks for status tracking\n```\n\n**Directories created by the installer:**\n\n| Directory / File                                   | Purpose                                                   |\n| -------------------------------------------------- | --------------------------------------------------------- |\n| `~/.pappardelle/`                                  | Config, hooks, logs, and Claude status files              |\n| `~/.pappardelle/repos/{repoName}/open-spaces.json` | Persisted workspace registry (per-repo, survives reboots) |\n| `~/.pappardelle/repos/{repoName}/issue-meta/`      | Issue metadata for hook tracking (per-repo)               |\n| `~/.pappardelle/claude-status/`                    | Real-time status JSON files from Claude hooks             |\n| `~/.pappardelle/logs/`                             | Daily log files (7-day retention)                         |\n| `~/.worktrees/`                                    | Git worktrees for all your workspaces                     |\n\n\u003e **Multi-repo support:** State is namespaced per repository under `~/.pappardelle/repos/{repoName}/`.\n\u003e Running pappardelle in two different repos keeps their workspace registries completely separate.\n\u003e On first run, existing state is automatically migrated from the legacy global location.\n\n### Claude Code hooks\n\nPappardelle installs three Claude Code hooks that provide integration between Claude sessions and the TUI:\n\n| Hook                           | Trigger                             | What it does                                                                  |\n| ------------------------------ | ----------------------------------- | ----------------------------------------------------------------------------- |\n| `update-status.py`             | `PreToolUse`, `PostToolUse`, `Stop` | Writes session status to `~/.pappardelle/claude-status/` for live TUI updates |\n| `comment-question-answered.py` | `PostToolUse` (AskUserQuestion)     | Posts Q\u0026A exchanges as comments on the issue (Linear or Jira)                 |\n| `zap-notification.py`          | `PreToolUse`, `PermissionRequest`   | Sends push notifications via ntfy when Claude needs user input                |\n\n### Versioning and updates\n\nPappardelle is versioned via git tags on `chardigio/pappardelle` (`vX.Y.Z`) — `package.json` is not bumped on release. Every push to `main` cuts a new tag + GitHub Release via the `release` workflow. Bump type is driven by PR labels:\n\n| Label           | Effect               |\n| --------------- | -------------------- |\n| `release:major` | `X.0.0` bump         |\n| `release:minor` | `x.Y.0` bump         |\n| `release:patch` | `x.y.Z` bump         |\n| _(no label)_    | patch bump (default) |\n\nTwo paths feed the release workflow:\n\n- **Direct merge on `chardigio/pappardelle`** — an external contributor opens a PR here and you merge it. The release workflow reads the `release:*` label on the chardigio-side PR directly.\n- **Forward sync from `stardust-labs-io/stardust-labs`** — rsync pushes straight to `main` with no PR on this side. The monorepo's sync workflow reads the merged _monorepo_ PR's `release:*` label and propagates it to the synced commit as a `Release-bump: \u003cmajor|minor|patch\u003e` trailer, which the release workflow here consumes.\n\nOn startup, the TUI checks the GitHub Releases API (cached for 24h at `~/.pappardelle/update-check.json`) and, if a newer tag is available, renders a magenta banner above the workspace list:\n\n```\nUpdate available: v0.1.0 → v0.2.0 · U to update · X to dismiss\n```\n\nThe installed version is read from `git describe --tags --abbrev=0 --match 'v*.*.*'` on the install clone, with `package.json` as a fallback for the pre-release window. Press `U` to exit the TUI and re-run the install script in-place. Press `X` to dismiss the banner for the current session — the next launch re-reads the cache.\n\nWhen running out of the stardust-labs monorepo (LOCAL_MODE), the check is skipped entirely; the monorepo is the source of truth and must not be clobbered by `curl | bash`.\n\n### Logging\n\nLogs are written to `~/.pappardelle/logs/` with daily rotation (7-day retention):\n\n```bash\n# View today's log\ncat ~/.pappardelle/logs/pappardelle-$(date +%Y-%m-%d).log\n\n# Tail logs in real-time\ntail -f ~/.pappardelle/logs/pappardelle-*.log\n\n# View errors only\ngrep '\\[ERROR\\]' ~/.pappardelle/logs/*.log\n```\n\nWarnings and errors also appear in a red box at the bottom of the TUI. Press `e` to view them.\n\n### Development\n\n```bash\nnpm run dev      # Watch mode (auto-rebuild on changes)\nnpm run build    # Build once\nnpm start        # Run without building\nnpm test         # Lint + format check + tests\n```\n\n### Integration tests\n\nStandalone scripts in `integration-tests/` verify providers against real instances. They are **not** ava tests and are never run in CI — use them for local verification after making provider changes.\n\n```bash\nnpx tsx integration-tests/verify-linear.ts     # Linear provider (linctl)\nnpx tsx integration-tests/verify-jira.ts       # Jira provider (acli)\nnpx tsx integration-tests/verify-github.ts     # GitHub PR detection (gh)\nnpx tsx integration-tests/verify-gitlab.ts     # GitLab MR detection (glab)\nnpx tsx integration-tests/verify-config.ts     # Config loading + validation\nnpx tsx integration-tests/verify-watchlist.ts  # Full watchlist pipeline end-to-end\nnpx tsx integration-tests/verify-comments.ts   # Comment posting (creates real comments)\n```\n\nSee [`integration-tests/README.md`](integration-tests/README.md) for env vars and prerequisites.\n\n### Plugin Marketplace\n\nPappardelle ships a [Claude Code plugin marketplace](plugins/) with a single `pappardelle` plugin containing four skills:\n\n| Skill                    | Description                                                                                                                                            | Model-invocable |\n| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------- |\n| `/init-pappardelle`      | Interactive setup wizard — installs Pappardelle, checks prerequisites, generates `.pappardelle.yml`                                                    | No              |\n| `/update-pappardelle`    | Re-runs the install script to update Pappardelle to the latest version                                                                                 | No              |\n| `/configure-pappardelle` | Interactive config editor for `.pappardelle.yml` and `.pappardelle.local.yml` — profiles, keybindings, hooks, watchlists, and more                     | Yes             |\n| `/sous-chef`             | Kitchen-style coordinator — quick overview of active spaces, drill into any space for a sitrep, relay instructions to running Claude sessions via tmux | No              |\n\n**Install the plugin:**\n\n```bash\nclaude /plugin marketplace add chardigio/pappardelle\n```\n\n```bash\nclaude /plugin install pappardelle@pappardelle-marketplace\n```\n\nBecause `/configure-pappardelle` is model-invocable, Claude will automatically offer to use it when you ask about configuring Pappardelle — no need to invoke it explicitly.\n\n### Dependencies\n\n- [Ink](https://github.com/vadimdemedes/ink) — React for CLIs\n- [tmux](https://github.com/tmux/tmux) — Terminal multiplexer\n- [lazygit](https://github.com/jesseduffield/lazygit) — Terminal git UI\n- [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) — AI coding assistant\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchardigio%2Fpappardelle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchardigio%2Fpappardelle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchardigio%2Fpappardelle/lists"}