mcpField
P
paper-spine-ui

paper-spine-ui

github.com/wubing2023Agent workflows6.1k204 installsUpdated 2w ago
Repository

About paper-spine-ui

paper-spine-ui is an interactive configuration skill for PaperSpine, used when its configuration is missing or when interactive setup is requested. It launches a terminal-based wizard, with fallback menus or chat questions when an interactive terminal is unavailable.

Key features

  1. 01Launch an interactive configuration wizard
  2. 02Edit fields and choices in a terminal UI
  3. 03Save PaperSpine configuration files
  4. 04Fall back to numbered menus or chat

Use cases

  1. 01Configure PaperSpine when its config is missing
  2. 02Set up PaperSpine through an interactive terminal
  3. 03Configure PaperSpine when a graphical terminal is unavailable

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/wubing2023/paperspine --skill paper-spine-ui

After installing, type/paper-spine-uiin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

agents/
openai.yaml
references/
interactive-intake.md
scripts/
_paper_spine_utils.py
humanize_check.py
intake_wizard.py
launch_paperspine_ui.ps1
launch_paperspine_ui.sh

Details

From the project README

PaperSpine UI

Use this branch whenever paper_spine_config.json is missing, incomplete, or the user asks to configure PaperSpine interactively.

Required Behavior

The supported interaction is a real terminal window launched by the installed launch_paperspine_ui.ps1 (resolve its absolute path under ~/.codex/skills/... or ~/.claude/skills/...). Do not run input()-based Python inside a hidden tool surface when the host cannot expose stdin.

In Claude Code, /paperspine must call this branch automatically when config is missing.

In Codex, launching this window opens a visible GUI/terminal, which Codex treats as an escalated action — request it with sandbox_permissions: require_escalated, or the window will not reliably appear. Launch the UI as the first action when config is missing; do not infer config from materials instead.

# Pass the ABSOLUTE path to the installed launcher. Codex/Claude run from the
# user's project folder, where `scripts/` does not exist, so a relative path is
# the most common reason the UI window never opens. Resolve the install dir:
$launcher = @(
  "$env:USERPROFILE\.codex\skills\paper-spine-ui\scripts\launch_paperspine_ui.ps1",
  "$env:USERPROFILE\.claude\skills\paper-spine-ui\scripts\launch_paperspine_ui.ps1",
  "$env:USERPROFILE\.codex\skills\paper-spine-intake\scripts\launch_paperspine_ui.ps1",
  "$env:USERPROFILE\.claude\skills\paper-spine-intake\scripts\launch_paperspine_ui.ps1"
) | Where-Object { Test-Path $_ } | Select-Object -First 1
powershell.exe -NoProfile -ExecutionPolicy Bypass -File $launcher -OutputDir paper_rewriting_output

If no separate window appears (headless or sandboxed Codex with no interactive desktop), add -InPlace to run the wizard in the current terminal instead; if stdin is still not interactive, fall back to numbered menus or native questions. Never silently skip configuration.

The UI writes:

paper_rewriting_output/paper_spine_config.json
paper_rewriting_output/paper_spine_config.md

UI Contract

  • Open a separate interactive terminal window when possible.
  • Provide a full-screen terminal UI when a real Windows terminal is available: centered welcome screen, white ridge wordmark, readable field/option panels, and a stable 30% field list plus 70% detail panel.
  • Use Up/Down for field navigation, Left/Right for choice fields, Enter for text/list editing, S to save, and Q to quit.
  • Show only one active field's reasoning and value details on the right panel; do not dump a long JSON-like checklist into the chat.
  • Fall back to numbered terminal menus only when arrow-key UI is unavailable.
  • Use chat questions only when terminal execution is impossible.
  • Never require the user to manually write JSON.

Read references/interactive-intake.md for the question order and fallback template.

Comments

Markdown supported