Skip to content

zyx1121/fde

v0.2.0MIT

Agent-driven client POCs: shared skills, MCP tools, and scripts for live demo environments.

CI Claude Code License

English | 繁體中文 | 简体中文

Use FDE to switch the current demo to a light theme, and sync it when you finish.

FDE stands for Forward Deployed Engineer, and also for Fastest Development Environment. It lets Codex and Claude Code work on a client demo that already runs. The skill holds the workflow, 3 MCP tools do the work, and you never type a CLI command.

Features

  • Reads the demo's health: the systemd service, PostgreSQL and the HTTP health URL, without changing anything.
  • Syncs your code: rsync over SSH, which protects .env files, dependencies, build output and persistent data.
  • Takes snapshots: the deployed source, the database and the uploads, with SHA-256 checksums.
  • Keeps the client's design: the theme, navigation, accounts and login settings stay as the project has them.

Quick start

claude plugin marketplace add zyx1121/marketplace
claude plugin install fde@zyx1121

Codex: codex plugin marketplace add zyx1121/marketplace, then codex plugin add fde@zyx1121.

Copy examples/fde.config.example.json to ~/.config/fde/config.json and set your workspace, SSH alias and service. Open a new session and use the skill: /fde:fde in Claude Code or $fde in Codex. Ask "What is the status of the demo?".

The plugin needs Node.js 22 or later, SSH and rsync. The MCP server ships bundled in dist/.

Usage

ToolDoesChanges
fde_statusreads the workspace, the service, PostgreSQL and HTTP healthnothing
fde_synccopies local source to the demo over SSH and rsyncremote source. It deletes remote files only when sync.delete is on
fde_snapshotbacks up the deployed source, the database and the uploadsa new private snapshot directory on the remote

Each tool takes an optional project. Without it, the tools use defaultProject from the profile. The remote requirements and limits are in skills/fde/references/operations.md.

For a personal page with the zyx shell, install task-web. FDE has no template dependency.

Configuration

~/.config/fde/config.json holds one entry per project. FDE_CONFIG_PATH and XDG_CONFIG_HOME move it.

KeySets
workspacethe local source directory
sshHost, remotePaththe SSH alias and the remote directory
servicethe systemd unit
database, uploadsPath, backupPathwhat a snapshot copies, and where it writes
healthUrlthe URL that fde_status requests
sync.delete, sync.excludewhether sync deletes remote files, and what it skips

The profile, SSH keys, runtime state and client data stay out of this repo and out of the plugin cache.

How it works

The skill decides the steps. The MCP server (dist/server.mjs) runs each operation from scripts/lib/, which works over SSH. A snapshot copies the source, the database and the uploads one after another, so it is not atomic.

Limits

  • FDE does not create VMs or scaffold a new app.
  • It does not promote a demo to production. Each project keeps its own deploy flow.
  • A snapshot is sequential, not atomic.

For AI agents

Facts for coding agents and LLM tools. The rules for changing the code are in AGENTS.md.

  • Summary: Plugin with a skill and 3 MCP tools that read, sync and snapshot a running Next.js or Node client demo over SSH.
  • Type: plugin
  • Interfaces: MCP fde (stdio, dist/server.mjs) with fde_status, fde_sync, fde_snapshot. Skill fde.
  • Install: claude plugin install fde@zyx1121, after claude plugin marketplace add zyx1121/marketplace
  • Run: the host starts the MCP server
  • Verify: call fde_status and expect the service and health results
  • Config: ~/.config/fde/config.json, FDE_CONFIG_PATH
  • Secrets: none in the plugin. SSH keys stay in SSH config, and the remote .env stays on the remote.
  • Limits: no VM creation, no scaffold, no promotion. Snapshots are not atomic.

Development

npm ci
npm run check

plugin.json and mcp.json are the manifest sources. The build writes the Claude-compatible files and dist/server.mjs, and CI fails when the committed copies are stale. docs/architecture.md records why FDE is its own plugin.

License

MIT