If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/xpipe-io/xpipe shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Solo project — review before adopting

• Last commit today
• Apache-2.0 licensed
• Tests present
• ⚠ Solo or near-solo (1 contributor active in recent commits)
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live xpipe-io/xpipe repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/xpipe-io/xpipe.

What it runs against: a local clone of xpipe-io/xpipe — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in xpipe-io/xpipe | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of xpipe-io/xpipe. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/xpipe-io/xpipe.git
#   cd xpipe
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of xpipe-io/xpipe and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "xpipe-io/xpipe(\\.git)?\\b" \\
  && ok "origin remote is xpipe-io/xpipe" \\
  || miss "origin remote is not xpipe-io/xpipe (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "app/src/main/java/io/xpipe/app/Main.java" \\
  && ok "app/src/main/java/io/xpipe/app/Main.java" \\
  || miss "missing critical file: app/src/main/java/io/xpipe/app/Main.java"
test -f "app/src/main/java/io/xpipe/app/beacon/AppBeaconServer.java" \\
  && ok "app/src/main/java/io/xpipe/app/beacon/AppBeaconServer.java" \\
  || miss "missing critical file: app/src/main/java/io/xpipe/app/beacon/AppBeaconServer.java"
test -f "app/src/main/java/io/xpipe/app/beacon/impl" \\
  && ok "app/src/main/java/io/xpipe/app/beacon/impl" \\
  || miss "missing critical file: app/src/main/java/io/xpipe/app/beacon/impl"
test -f "app/src/main/java/io/xpipe/app/browser/BrowserFullSessionModel.java" \\
  && ok "app/src/main/java/io/xpipe/app/browser/BrowserFullSessionModel.java" \\
  || miss "missing critical file: app/src/main/java/io/xpipe/app/browser/BrowserFullSessionModel.java"
test -f "app/build.gradle" \\
  && ok "app/build.gradle" \\
  || miss "missing critical file: app/build.gradle"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/xpipe-io/xpipe"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

XPipe is a desktop connection hub that bridges your local machine to remote infrastructure (SSH servers, Docker containers, Kubernetes clusters, VMs, cloud instances) via a JavaFX GUI and REST API beacon. It wraps existing CLI tools (ssh, docker, kubectl, etc.) without requiring remote setup, and integrates with local editors, terminals, and password managers. Gradle monorepo: app/ contains the JavaFX desktop client (Main.java entry point), with core/ and beacon/ as sibling modules (inferred from dependencies). Within app/src/main/java/io/xpipe/app: action/ handles UI actions (ActionProvider, StoreContextAction), beacon/ implements request handlers (BeaconRequestHandler, AppBeaconServer) with exchange impls in beacon/impl/ (ConnectionAddExchangeImpl, ActionExchangeImpl, etc.). Modular extension-friendly design: ActionProvider and BeaconRequestHandler appear to be plugin points.

Infrastructure engineers, DevOps practitioners, and systems administrators who manage multiple remote servers/containers and want a unified UI + scriptable API to connect, query, and control their entire stack from one desktop app—without installing agents on remote systems.

Actively developed. Large codebase (3.7M lines Java, structured Gradle multi-module build, organized beacon/action/extension patterns) suggests production maturity. Presence of CODE_OF_CONDUCT.md, CONTRIBUTING.md, SECURITY.md, and modular architecture (core, beacon, app modules with their own build.gradle) indicate established project governance. Specific maturity verdict: production-ready with ongoing active development.

Moderate risk. Heavy dependency on flexmark (14 transitive deps for markdown), MCP SDK, and native CLI tool availability on host. Single entry point in app/src/main/java/io/xpipe/app/Main.java—no visible multi-entry architecture. Risk scales with number of integrated connection types (SSH, Docker, K8s, etc.); a bug in one beacon exchange impl (e.g., ConnectionAddExchangeImpl.java) could affect infrastructure automation. No test files visible in localTest (only Test.java stub), suggesting thin test coverage for core beacon logic.

Cannot determine from file list alone, but the presence of recent gradle config, dependabot.yml for automated dependency updates, and beacon exchange impls for modern tools (Kubernetes, Tailscale, Netbird, Teleport, Hetzner Cloud) suggest active feature development around cloud/container integrations. Likely in-flight: expanding connection provider coverage and stabilizing the beacon REST API surface.

git clone https://github.com/xpipe-io/xpipe.git
cd xpipe
./gradlew build
./gradlew app:run

(Gradle Wrapper included; Java 17+ and JavaFX runtime required per gradle/gradle_scripts/javafx.gradle import.)

Daily commands:

./gradlew app:run

Or build distribution: ./gradlew build then run the app binary in build/distributions/. Desktop app launches with UI; beacon server listens on localhost:21721 (default) for API clients.

• app/src/main/java/io/xpipe/app/Main.java — Application entry point that initializes the XPipe desktop client and orchestrates startup.
• app/src/main/java/io/xpipe/app/beacon/AppBeaconServer.java — Core IPC server handling all beacon protocol requests from CLI/external clients, critical for extensibility.
• app/src/main/java/io/xpipe/app/beacon/impl — Implementation of all beacon exchange protocols (connection mgmt, shell execution, file ops); backbone of external API.
• app/src/main/java/io/xpipe/app/browser/BrowserFullSessionModel.java — Main state model for file browser UI sessions; required reading for UI layer architecture.
• app/build.gradle — Gradle build configuration showing dependency graph, JavaFX setup, and module system configuration.
• app/src/main/java/io/xpipe/app/action/ActionProvider.java — Abstract base for action system allowing plugins/extensions to register custom actions on connections.
• app/src/main/java/io/xpipe/app/beacon/mcp/AppMcpServer.java — Model Context Protocol server integration enabling Claude/LLM tool use with XPipe infrastructure.

Add a New Beacon Protocol Exchange (RPC Handler)

1. Create new exchange implementation class extending BeaconExchange in app/src/main/java/io/xpipe/app/beacon/impl/YourFeatureExchangeImpl.java following naming convention XxxExchangeImpl (app/src/main/java/io/xpipe/app/beacon/impl/YourFeatureExchangeImpl.java)
2. Implement handleRequest() method to parse request message and return response; see ShellExecExchangeImpl.java or FsReadExchangeImpl.java as templates (app/src/main/java/io/xpipe/app/beacon/impl/ShellExecExchangeImpl.java)
3. Register your exchange in BeaconRequestHandler.java by adding it to the exchanges map with a unique identifier (app/src/main/java/io/xpipe/app/beacon/BeaconRequestHandler.java)
4. If large payloads are involved, use BlobManager.java to stream data rather than keeping in memory (app/src/main/java/io/xpipe/app/beacon/BlobManager.java)
5. Document the request/response schema in the exchange class; clients use this for CLI and SDK code generation (app/src/main/java/io/xpipe/app/beacon/impl/YourFeatureExchangeImpl.java)

Add a New File Browser Action (Context Menu Item)

1. Create action provider class extending BrowserActionProvider at app/src/main/java/io/xpipe/app/browser/action/impl/YourActionProvider.java (app/src/main/java/io/xpipe/app/browser/action/impl/YourActionProvider.java)
2. Implement getCategory(), getIcon(), getName(), and areApplicable() methods; see DeleteActionProvider.java or ChmodActionProvider.java as examples (app/src/main/java/io/xpipe/app/browser/action/impl/DeleteActionProvider.java)
3. Implement execute() method to run the action on selected files; use BrowserShellSession to execute commands remotely (app/src/main/java/io/xpipe/app/browser/action/impl/ChmodActionProvider.java)
4. Your provider is auto-discovered via SPI; ensure it's registered and listed in BrowserActionProviders.java (app/src/main/java/io/xpipe/app/browser/action/BrowserActionProviders.java)

Add a New Global Connection Action (Right-Click Menu on Connection)

1. Create action provider class extending ActionProvider at app/src/main/java/io/xpipe/app/action/impl/YourActionProvider.java (app/src/main/java/io/xpipe/app/action/ActionProvider.java)
2. Implement getCategory(), execute(), and applicableClass() methods; define when action is available (see StoreContextAction.java for connection-scoped example) (app/src/main/java/io/xpipe/app/action/StoreContextAction.java)
3. Use ActionUrls.java to register URL schemes (xpipe://action/...) if you want deeplink support (app/src/main/java/io/xpipe/app/action/ActionUrls.java)
4. If action involves serialization for persistence or URLs, extend SerializableAction.java and register Jackson mappers in ActionJacksonMapper.java (app/src/main/java/io/xpipe/app/action/SerializableAction.java)

Expose a New Tool to Claude via MCP

1. Define your tool in McpTools.java by adding it to the tools catalog with name, description, and input schema (app/src/main/java/io/xpipe/app/beacon/mcp/McpTools.java)
2. undefined

No visible test suite: app/src/localTest/java/test/Test.java is a stub; core beacon logic has no tests shown—risk when adding exchanges. JavaFX threading: beacon handlers (BeaconSession, BeaconShellSession) must coordinate with JavaFX UI thread; async calls to CLI tools must not block GUI. Native CLI dependency: app assumes ssh, docker, kubectl, etc. are installed and on PATH locally; no fallback if missing. Beacon protocol versioning: BeaconRequestHandler must maintain backward compatibility; no API versioning visible in file names. Module system: module-info.java in app/src/localTest/java suggests JPMS; ensure your custom code declares proper exports/requires. Password manager integration: AskpassExchangeImpl.java depends on external askpass binaries; SSH_ASKPASS env var must be set correctly.

• Beacon Protocol (Custom REST/RPC) — XPipe's beacon system (AppBeaconServer, BeaconRequestHandler, exchange impls) is a custom request/response protocol allowing external clients to query and control connections. Understanding how requests are routed and serialized (ActionJacksonMapper) is essential for extending the API.
• CLI Tool Abstraction Layer (Wrapper Pattern) — XPipe wraps existing CLI tools (ssh, docker, kubectl) without modifying them. Understanding how each exchange impl (e.g., ConnectionAddExchangeImpl, BeaconShellSession) invokes and parses CLI output is critical for adding new connection types.
• JavaFX GUI Framework with Scene Graph — The desktop UI (Main.java, ActionConfigComp, ActionConfirmComp, ActionPickComp) uses JavaFX's reactive scene graph. UI components must be thread-safe and coordinate with the beacon server's async I/O; misunderstanding this causes deadlocks.
• Plugin Architecture (Service Loader / Registry Pattern) — ActionProvider and likely BeaconRequestHandler use plugin registration to allow modular extensions. Knowing how to register a new action or beacon exchange impl without modifying core code is how XPipe achieves extensibility.
• Gradle Composite Builds / Multi-Module Projects — XPipe uses a monorepo structure with core/, beacon/, and app/ modules, each with build.gradle. Understanding Gradle's dependency resolution (implementation.extendsFrom(javafx), api project(':core')) is necessary for building and testing locally.
• Session-based Connection Lifecycle (BeaconSession, BeaconShellSession) — Connections are not stateless; BeaconSession and BeaconShellSession maintain state across multiple beacon requests. Understanding session creation, caching (AppBeaconCache), and cleanup is crucial for avoiding resource leaks when managing remote shells.
• JSON Serialization with Jackson Custom Mappers — ActionJacksonMapper handles serialization of actions and configurations for the beacon API. Custom serialization logic here determines how actions are passed over the wire; mismatches break API clients.

• teleport/teleport — Similar infrastructure access tool; Teleport is a competitor supporting SSH, K8s, and databases. Understanding its architecture (agent-based vs. XPipe's CLI-wrapping approach) provides context for XPipe's design decisions.
• trufflesecurity/trufflehog — Not a direct competitor but integrates with XPipe's credential/secret scanning workflow; relevant for understanding how XPipe fits into infrastructure tooling.
• ansible/ansible — Infrastructure automation tool that XPipe complements; XPipe can be a discovery/connection front-end for Ansible playbook targets.
• modelcontextprotocol/sdk-python — XPipe depends on MCP SDK (visible in build.gradle); understanding the Model Context Protocol helps extend XPipe with custom clients/servers.
• openvscode-server/openvscode-server — Similar desktop-to-remote bridging approach; XPipe integrates with VS Code as a connection launcher, so this codebase is a consumption point.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for Beacon Exchange implementations in app/src/localTest/java/test/

The beacon module contains 25+ ExchangeImpl classes (ActionExchangeImpl, ConnectionAddExchangeImpl, ShellExecExchangeImpl, etc.) that handle critical server infrastructure operations. Currently, app/src/localTest/java/test/ only has a placeholder Test.java. Adding comprehensive unit tests for these exchange implementations would catch serialization bugs, connection handling errors, and protocol violations early. This is high-value since beacon exchanges are the core API layer for external tool integration.

• [ ] Create test classes in app/src/localTest/java/test/ for core exchanges: ActionExchangeImpl, ConnectionQueryExchangeImpl, ShellStartExchangeImpl, and ShellExecExchangeImpl
• [ ] Add tests verifying Jackson serialization/deserialization for each exchange request/response using ActionJacksonMapper
• [ ] Test error handling paths (invalid connections, auth failures, missing resources) in BeaconRequestHandler flow
• [ ] Add integration tests for BeaconSession state transitions and BlobManager file operations
• [ ] Ensure tests use JUnit 5 (already in dependencies: junit-jupiter-api, junit-jupiter-params)

Add GitHub Actions workflow for JavaFX GUI testing of app module

The app module uses JavaFX (gradle_scripts/javafx.gradle) and has complex UI components (ActionConfirmComp, ActionPickComp, ActionConfigComp). No CI workflow is visible in .github/dependabot.yml for testing GUI code on multiple OS targets. Adding a matrix workflow for Linux/Windows/macOS with headless JavaFX rendering would catch platform-specific UI bugs, especially important for a desktop tool that integrates with OS-specific terminals and SSH clients.

• [ ] Create .github/workflows/app-tests.yml with matrix strategy for ubuntu-latest, windows-latest, and macos-latest
• [ ] Configure Gradle to run app module tests with -Djavafx.platform=headless or similar headless rendering
• [ ] Set up X11/display server for Linux GUI testing (e.g., xvfb-run or similar)
• [ ] Include app/build.gradle test tasks and ensure beacon module tests run as dependencies
• [ ] Add workflow badge to README.md to document test coverage

Create integration tests for Beacon MCP (Model Context Protocol) module in app/src/main/java/io/xpipe/app/beacon/mcp/

The app has a dedicated app/src/main/java/io/xpipe/app/beacon/mcp/ directory (visible in file structure) with MCP integration, and dependencies show 'io.modelcontextprotocol.sdk:mcp-core:1.0.0' is imported. However, no test files are visible for MCP handlers. Given MCP is a complex protocol for AI tool integration, adding tests for MCP request routing, message serialization, and session management would validate that XPipe correctly exposes server infrastructure to AI models without breaking compatibility.

• [ ] Examine app/src/main/java/io/xpipe/app/beacon/mcp/ source files to identify MCP handler classes and entry points
• [ ] Create app/src/localTest/java/test/mcp/ directory with tests for MCP protocol message handling
• [ ] Add tests for MCP tool registration, argument validation, and resource access control (especially for SSH/Docker connections)
• [ ] Test MCP session lifecycle: initialization, tool invocation, error responses, and cleanup
• [ ] Verify Jackson mapper compatibility with MCP message types using ActionJacksonMapper patterns

• Add unit tests for beacon exchange impls. app/src/main/java/io/xpipe/app/beacon/impl/ has ~12 exchanges with zero visible test coverage. Create app/src/test/java/io/xpipe/app/beacon/impl/*ExchangeTest.java mocking BeaconSession and verifying request/response serialization.: Medium
• Document the beacon API contract. Create docs/BEACON_API.md listing all exchange request/response types (e.g., ConnectionAddExchange, ActionExchange, CategoryQueryExchange) with schema examples. Currently only visible in impl classes.: Low
• Extract connection-type-specific logic into a Registry pattern. Currently each connection type (SSH, Docker, K8s) has a dedicated Exchange impl. Refactor to a pluggable ConnectionTypeRegistry where providers register handlers; reduces duplication in beacon/impl/ and eases adding new types (e.g., OpenStack, Proxmox).: High

• High · Incomplete Dependency Declaration in build.gradle — app/build.gradle - MCP SDK dependency definition. The MCP (Model Context Protocol) SDK dependency declaration appears truncated with 'exclude gr' comment incomplete, which could mask excluded transitive dependencies. This may result in unexpected or vulnerable transitive dependencies being included in the build. Fix: Complete the dependency exclusion statement. Verify all transitive dependencies are properly declared and vetted. Add explicit version constraints for all transitive dependencies of mcp-core:1.0.0.
• High · Beacon API Potential Command Injection Risk — app/src/main/java/io/xpipe/app/beacon/impl/ - Shell and Script execution handlers. Multiple beacon exchange implementations (ShellExecExchangeImpl, FsScriptExchangeImpl, ShellStartExchangeImpl) handle shell execution and script execution. Without visible input validation in the file structure, there is risk of command injection attacks when processing user-supplied commands or scripts. Fix: Implement strict input validation and sanitization for all shell commands and scripts. Use parameterized execution APIs instead of string concatenation. Implement allowlists for permitted commands where applicable. Add comprehensive unit tests for command injection scenarios.
• High · Sensitive Data Handling in Beacon Server — app/src/main/java/io/xpipe/app/beacon/ - Credential handling components. The application handles sensitive information including credentials, SSH keys, and passwords (indicated by AskpassExchangeImpl, SecretEncryptExchangeImpl, SecretDecryptExchangeImpl). Risk of credential exposure in logs, memory dumps, or network traffic if not properly protected. Fix: Implement secure credential storage using encrypted vaults. Ensure credentials are cleared from memory immediately after use. Use secure, encrypted communication channels (TLS 1.3+) for all credential transmission. Implement strict access controls and audit logging for credential access.
• Medium · Potential Deserialization Vulnerability — app/src/main/java/io/xpipe/app/action/ActionJacksonMapper.java and related URL providers. ActionJacksonMapper suggests use of Jackson for serialization/deserialization. Combined with ActionUrls and LauncherUrlProvider handling external URLs, there is potential risk of insecure deserialization if untrusted data sources are processed. Fix: Use Jackson's strict deserialization settings. Implement explicit type allowlisting for deserialization. Never deserialize from untrusted sources without validation. Keep Jackson library updated to latest stable version.
• Medium · File System Operations Security — app/src/main/java/io/xpipe/app/beacon/impl/Fs*ExchangeImpl.java files. Multiple components handle file system operations (FsReadExchangeImpl, FsWriteExchangeImpl, FsBlobExchangeImpl). Without visible path validation, there is risk of directory traversal attacks allowing access to arbitrary files on the system. Fix: Implement strict path canonicalization and validation. Enforce directory boundaries using SecurityManager or similar mechanisms. Validate all file paths against an allowlist of permitted directories. Implement comprehensive path traversal testing.
• Medium · Missing Dependency Version Pinning — app/build.gradle - dependency definitions. Multiple flexmark dependencies (version 0.64.8) and other libraries use exact versions, but no global dependency management is visible. This could lead to subtle version mismatches or dependency conflicts in the future. Fix: Implement a dependency management block using 'dependencyManagement' or gradle version catalogs. Pin all transitive dependencies explicitly. Use dependency locking (gradle.lockfile) to ensure reproducible builds. Regularly audit dependencies for known vulnerabilities using tools like OWASP Dependency-Check or Snyk.
• Medium · Flexmark Markdown Processing Security — app/src/main/java/io/xpipe/app/ - any components using flexmark libraries. Extensive use of flexmark library for markdown processing suggests potential for HTML injection or XSS if markdown content from untrusted sources is rendered without proper sanitization. Fix: Implement output encoding and sanitization for all markdown-generated HTML. Use Content Security Policy headers if applicable. Validate markdown content from external sources. Consider using a dedicated HTML sanitizer library (e.g., OWASP Java HTML Sanitizer) in addition to markdown processing.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.