README.md

Reprompty

Reprompty is an MCP Swiss Army knife for AI agent windows, tooling, desktop layouts, and cross-editor orchestration on Windows 11 and KDE/Linux (Wayland). It helps you manage both the visual and technical side of agent workflows, prompt engineering, and lower-friction MCP handoffs.

I made a demo video: https://www.youtube.com/watch?v=myEoB4hP7Oo

Overview

Reprompty enables you to:

• Shape the actual computer workflow, not just the prompt
• Spawn multiple VS Code windows with isolated chat sessions
• Organize windows, desktops, and layouts around the way you want to work
• Create prompt templates with XML tags for structured prompting
• Automate batch task execution across multiple windows
• Trigger skills and workflows based on conditions
• Build agent teams that collaborate on complex tasks
• Work cleanly alongside projects like Aperant-MCP without adding handoff friction
• Link LLMs to pass information or sync context to prepare for a merge, for example

Features

Window Management

• Spawn duplicate VS Code windows pointing to the same directory
• Each window maintains independent chat history
• Organize windows, desktops, and layouts automatically using scripts and MCP tools

Prompt Engineering

• XML-tagged prompt templates
• Variable substitution and context injection
• Prompt chaining and composition

Automation

• Trigger skills based on events
• Batch task creation and management
• Workflow orchestration for multi-agent teams
• Lower-friction handoffs into Aperant-style MCP workflows

Agent Teams

• Coordinate multiple AI agents
• Parallel task execution
• Result aggregation and synthesis

Getting Started

# Clone the repository
git clone https://github.com/topemalheiro/Reprompty.git

# Install dependencies
cd reprompty
npm install

# Run the framework
npm start

Kilo Code MCP Setup

Reprompty's stdio MCP server entrypoint is reprompty/src/mcp/server.ts.

After installing dependencies in reprompty/, register the MCP server in Kilo Code with:

• Working directory: reprompty
• Command: bun
• Args: run, mcp
• Equivalent shell command: cd reprompty && bun run mcp

Direct entrypoint alternative:

• Command: bun
• Args: run, src/mcp/server.ts

Do not point Kilo Code at reprompty/src/mcp/index.ts; that module contains tool implementations, while reprompty/src/mcp/server.ts is the stdio transport that handles MCP initialize, tools/list, and tools/call.

Spawn Targets (Token-Friendly VS Code Spawning)

Reprompty can save common folders as spawn targets so MCP clients can open VS Code windows with a short alias instead of a long folderPath.

1. Open Reprompty -> Spawn tab.
2. Under Saved Spawn Targets, fill:
   • Alias (example: windows-project)
   • Label (example: OS Toolkit)
   • Folder Path (example: C:\Users\topem\Desktop\OS Toolkit)
   • Optional window name
   • Optional default desktop name
3. Click Save Target.

From MCP:

mcp__reprompty__list_spawn_targets

mcp__reprompty__list_virtual_desktops

mcp__reprompty__ensure_virtual_desktop { "name": "Aperant-MCP" }

mcp__reprompty__rename_virtual_desktop { "currentName": "3", "newName": "Focus" }

mcp__reprompty__spawn_window { "target": "windows-project", "desktop": "2" }
mcp__reprompty__spawn_window { "target": "windows-project", "desktop": "2", "activateDesktop": true }
mcp__reprompty__spawn_and_layout { "target": "windows-project", "slot": "B", "createDesktop": true }

spawn_window and spawn_and_layout still support raw folderPath if you prefer not to use aliases. If desktop is supplied and missing, Reprompty creates it and targets that desktop for the spawn. If createDesktop: true is supplied without an explicit desktop, Reprompty creates a fresh desktop named from the saved target label first, otherwise the folder basename. Desktop-aware spawns stay on your current desktop by default: Reprompty spawns VS Code, isolates the new window handle, and moves that exact window to the target desktop. If you explicitly want the old switch-first behavior, pass "activateDesktop": true. spawn_and_layout now waits for a uniquely identifiable VS Code window handle after spawn. If Reprompty cannot isolate one window safely, it returns an error instead of moving the wrong editor.

Virtual Desktop Management

Reprompty now treats virtual desktops as a built-in backend capability rather than a script convention.

• list_virtual_desktops returns desktop index, name, and isCurrent
• ensure_virtual_desktop creates a named desktop if it is missing and does not switch desktops
• rename_virtual_desktop renames an existing desktop by exact name
• spawn_window and spawn_and_layout accept either:
  • desktop: use or auto-create a named desktop
  • createDesktop: true: create a fresh desktop for this spawn
  • activateDesktop: true: opt into switching desktops before the spawn

Important behavior:

• Desktop names are the public contract for MCP and the Reprompty UI
• Desktop names refresh from backend polling, so the Windows tab updates after rename
• Spawn target defaults still work, but createDesktop: true overrides them for that one call so a fresh project desktop can be created on demand
• Desktop-aware spawns no longer switch by default; repeated calls are the intended way to set up multiple desktops and windows while you stay on the current workspace

Script-Defined MCP Tools (Layout Presets)

Reprompty can turn script flags / presets into first-class MCP tools. This is the recommended way to expose layout presets like:

• Ctrl+Alt+V: Dual monitor layout (bottom)
• Ctrl+Alt+N: Top monitors layout (panel full)

Option A: Portable Script Headers (Recommended)

Add one or more reprompty-mcp: lines near the top of your script (first ~40 lines). Each line is JSON describing one tool.

Example (PowerShell):

# reprompty-mcp: {"toolName":"dual_monitor_layout_bottom","label":"Dual monitor layout (bottom)","description":"Run the Ctrl+Alt+V dual monitor bottom layout","args":["-Once"]}
# reprompty-mcp: {"toolName":"top_monitors_layout_panel_full","label":"Top monitors layout (panel full)","description":"Run the Ctrl+Alt+N top monitors panel-full layout","args":["-SingleOnce"]}
param(...)

Then in Reprompty:

1. Open Reprompty -> Scripts tab -> + Add Script.
2. Point to the script file and save.
3. In the script card, under MCP Tools, click Re-scan header if needed and make sure the tools are enabled.

Now those tool names show up in MCP tools/list and can be called directly:

mcp__reprompty__dual_monitor_layout_bottom
mcp__reprompty__top_monitors_layout_panel_full

Option B: UI-Defined Presets (No Script Edits)

In the Scripts tab, click + Add MCP tool inside a script card and set:

• Tool name (must be unique across all scripts and not collide with built-in tools)
• Args (space-separated) to pass into the script (example: -A or -Once)

Important Notes

• Generated script tools are one-shot invocations. The MCP call waits for the script to exit.
  • If your script is a long-running hotkey listener, add a one-shot switch like -Once that runs the layout and exits.
• Output from MCP-triggered runs is appended to the script terminal with a [MCP:<toolName>] prefix.
• Reprompty passes -WindowHandle and -LogPath automatically for built-in layout calls, so layout scripts can target an exact VS Code window and write a per-run transcript without changing user-facing flags.

Linux Global Shortcuts (KDE / Wayland)

On Linux, Reprompty uses KDE's global shortcut system (kglobalaccel) so layouts work even when Reprompty itself is not running.

How it connects

1. ~/.reprompty/layouts.json — stores slot coordinates (windowX, windowY, windowWidth, windowHeight, panelWidth) and scriptArgs

   • Slot A: "scriptArgs": ["--once", "--slot", "A"]
   • Slot B: "scriptArgs": ["--once", "--slot", "B"]

2. ~/.reprompty/scripts.json — set "autoStart": false so the layout script does not resize VS Code: on Reprompty launch.

3. Wrapper scripts (reprompty/linux/layout-dual.sh, layout-single.sh)

   • Call linux_layout.py --once --slot A (or B)
   • The script reads the slot coordinates from layouts.json and applies them to the active VS Code: window via CDP.

4. KDE shortcut registration

   • ~/.local/share/applications/reprompty-layout-dual.desktop → Ctrl+Alt+V
   • ~/.local/share/applications/reprompty-layout-single.desktop → Ctrl+Alt+N
   • ~/.config/kglobalshortcutsrc maps the keys to the .desktop files
   • ~/.config/khotkeysrc stores the direct command fallback

5. Session restart required

   • KDE's kglobalaccel daemon caches .desktop file Exec= lines in memory.
   • After changing .desktop files or kglobalshortcutsrc, log out and back in for the changes to take effect.

Troubleshooting

• Shortcut does nothing → Log out / back in. KDE has the old command cached.
• Layout goes to wrong position → Check ~/.reprompty/layouts.json slot coordinates. The script uses those exact values when called with --slot A/B.
• "No VS Code: window found" → Make sure a VS Code: window is open before pressing the shortcut.
• Reprompty resizes VS Code: on launch → Verify "autoStart": false in scripts.json.

Layout Debug Logs

Reprompty now writes two useful log streams for layout troubleshooting:

• App / MCP orchestration log:
  • %USERPROFILE%\\reprompty-logs\\reprompty-YYYY-MM-DD.log
  • Contains spawn_and_layout / apply_layout requests, baseline window handles, candidate handles, chosen target, and the generated layout log path.
• Per-run layout transcript:
  • %LOCALAPPDATA%\\VSCodeSidePanelLayout\\layout-run-<timestamp>.log
  • Contains the one-shot PowerShell layout transcript, including Found:, Repositioned to:, title-matching diagnostics, and CDP resize output.
• CDP repair / health log:
  • %LOCALAPPDATA%\\VSCodeSidePanelLayout\\repair.log
  • Contains the longer-lived repair and launch-hook health events.

For direct MCP calls:

mcp__reprompty__apply_layout { "slot": "B", "windowHandle": 123456 }

windowHandle is preferred over windowTitle when you already know the exact target window.

Architecture

Reprompty is designed as a modular MCP toolkit that can:

• Run as a VS Code extension
• Integrate with existing tools like Kilo Code
• Spawn and manage native Windows processes
• Improve day-to-day UX at the computer-workflow level, not just inside one chat pane

License

MIT License - see LICENSE file for details.

Contributing

Contributions welcome!