Skip to content

marshawcoco/remote-ssh-dev

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

2 Commits
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Remote SSH Dev for Claude Code

EN: Use Claude Code on large remote Linux projects over SSH when your local machine does not have enough memory to run them comfortably.

中文: 当你的本机内存不足以顺畅运行大型项目时,通过 SSH 让 Claude Code 直接在远端 Linux 项目上工作。

remote-ssh-dev is a focused Claude Code skill for a common real-world problem: your local machine is too memory-constrained for a large project, but the real development environment already exists on a remote Linux host.

remote-ssh-dev 解决的是一个非常常见的现实问题:你的本机内存不足以顺畅运行大型项目,但真实可用的开发环境已经存在于一台远端 Linux 主机上。

Why this exists / 为什么会有这个项目

EN: Many real projects do not fit comfortably on a local machine. The repository may be large, the dependency graph heavy, the build expensive, or the test suite memory-hungry. In practice, the real working environment often already lives on a remote Linux host with more RAM, CPU, storage, or data access.

中文: 很多真实项目并不适合直接在本机上舒适运行:仓库可能很大,依赖链很重,构建成本高,测试也非常吃内存。实际工作中,真正可用的开发环境往往已经存在于一台拥有更多内存、CPU、存储或数据访问能力的远端 Linux 主机上。

EN: remote-ssh-dev exists to make that setup practical for Claude Code: keep Claude local, keep the project remote, and work through SSH with a focused and safer workflow.

中文: remote-ssh-dev 的目标,就是让 Claude Code 在这种场景下真正可用:让 Claude 留在本地,让项目留在远端,并通过一套更聚焦、更安全的 SSH 工作流完成开发。

What it does / 它能做什么

  • EN: Runs focused commands in a remote repository through SSH
    中文: 通过 SSH 在远端仓库中执行聚焦命令
  • EN: Reads remote files with line numbers for precise reasoning
    中文: 带行号读取远端文件,方便精确分析
  • EN: Writes remote files atomically
    中文: 以原子方式写回远端文件
  • EN: Encourages narrow verification before broad test/build commands
    中文: 鼓励先做小范围验证,再做更大范围的测试或构建
  • EN: Makes safety boundaries and real side effects explicit
    中文: 明确强调安全边界和真实副作用

What is included / 仓库包含内容

  • skill/SKILL.md — Claude Code skill definition / Claude Code skill 定义
  • skill/scripts/run_remote.sh — run a command in the remote repo / 在远端仓库中执行命令
  • skill/scripts/read_remote.sh — read a remote file with line numbers / 带行号读取远端文件
  • skill/scripts/write_remote.sh — atomically replace a remote file / 原子替换远端文件
  • install/install_claude_skill.sh — install the skill locally / 本地安装脚本
  • examples/ — SSH config and invocation examples / SSH 配置与调用示例

Safety model / 安全模型

EN: This skill is designed for real servers, not a mock environment.

中文: 这个 skill 面向真实服务器,而不是模拟环境。

It explicitly instructs the agent to / 它会明确要求 agent:

  • treat the remote machine as having real side effects / 把远端机器视为具有真实副作用的环境
  • avoid destructive operations unless the user confirms them / 未经用户确认不要做破坏性操作
  • prefer narrow verification before broad test/build commands / 先做小范围验证,再扩大测试或构建范围
  • stop when SSH auth is interactive or the host is unreachable / SSH 认证交互或主机不可达时立即停止
  • assume repo-relative paths unless given absolute paths / 默认把路径视为相对仓库路径,除非明确给出绝对路径

EN: Start on a non-production host first.

中文: 建议先在非生产环境主机上使用。

Best-supported setup / 最佳支持环境

EN: The most battle-tested setup right now is:

  • local Claude Code on Windows with Git Bash-style shell paths, or another Unix-like shell environment
  • remote Linux host over SSH

中文: 当前最成熟、验证最多的使用方式是:

  • 本地使用 Claude Code,运行在 Windows + Git Bash 风格路径环境,或其他类 Unix shell 环境
  • 通过 SSH 连接远端 Linux 主机

EN: The helper scripts themselves are simple POSIX-style shell scripts, but the most battle-tested workflow so far is local shell + remote Linux.

中文: 辅助脚本本身是简单的 POSIX 风格 shell 脚本,但目前经过最多实际验证的组合仍然是“本地 shell + 远端 Linux”。

Prerequisites / 前置要求

Local machine / 本地机器

  • Claude Code with skill support / 支持 skill 的 Claude Code
  • ssh available in your shell / shell 中可用的 ssh
  • a shell environment that can run the helper scripts / 能运行这些辅助脚本的 shell 环境
  • access to your Claude skills directory, commonly ~/.claude/skills / 可访问你的 Claude skills 目录,通常是 ~/.claude/skills

Remote machine / 远端机器

  • reachable over SSH / 可通过 SSH 访问
  • sh and bash / 提供 shbash
  • a checked-out repository on disk / 磁盘上已有检出的代码仓库
  • standard Unix tools such as nl, awk, mktemp, and mv / 常见 Unix 工具,如 nlawkmktempmv

Install / 安装

Quick install / 快速安装

From the repository root / 在仓库根目录执行:

./install/install_claude_skill.sh

By default this installs to / 默认安装到:

$HOME/.claude/skills/remote-ssh-dev

Override the target directory if needed / 如有需要可以覆盖目标目录:

CLAUDE_SKILLS_DIR="$HOME/.claude/skills" ./install/install_claude_skill.sh

EN: The installer copies the helper scripts and renders skill/SKILL.md with absolute local script paths so Claude Code can invoke them.

中文: 安装脚本会复制辅助脚本,并把 skill/SKILL.md 中的占位路径渲染成你本机上的绝对路径,方便 Claude Code 直接调用。

Manual install / 手动安装

  1. Copy skill/scripts/*.sh into your local skill directory.
    skill/scripts/*.sh 复制到你本地的 skill 目录。
  2. Copy skill/SKILL.md into that same directory.
    skill/SKILL.md 复制到同一个目录。
  3. Replace __REMOTE_SSH_DEV_ROOT__ in SKILL.md with the absolute path to this repository on your machine.
    SKILL.md 里的 __REMOTE_SSH_DEV_ROOT__ 替换成这个仓库在你本机上的绝对路径。

Usage / 用法

Invoke the skill with / 使用方式:

/remote-ssh-dev <ssh-host-or-alias> <remote-repo-path> <task...>

Example / 示例:

/remote-ssh-dev rustfs /root/project fix src/lib.rs formatting issue and run the smallest relevant test

The skill expects / 参数含义:

  • argument 1 = SSH host or alias / 参数 1 = SSH 主机或别名
  • argument 2 = remote repository path / 参数 2 = 远端仓库路径
  • argument 3+ = the task description / 参数 3 及以后 = 任务描述

Recommended SSH setup / 推荐 SSH 配置方式

EN: Prefer a named host alias in ~/.ssh/config instead of repeatedly typing raw IPs and ports.

中文: 建议优先使用 ~/.ssh/config 中的主机别名,而不是反复输入裸 IP 和端口。

See / 参考:examples/ssh_config_example.txt

Helper script behavior / 辅助脚本行为

run_remote.sh

  • EN: Connects over SSH, changes into the remote repo path, and runs the requested command via bash -lc
    中文: 通过 SSH 连接到远端,切换到仓库目录,并用 bash -lc 执行命令

read_remote.sh

  • EN: Accepts a repo-relative or absolute remote file path, prints line-numbered output, and optionally limits the line range
    中文: 接受相对仓库路径或绝对远端路径,输出带行号内容,并可选限制读取行范围

write_remote.sh

  • EN: Accepts file content on stdin, writes to a temporary remote file first, and then atomically moves it into place
    中文: 从标准输入接收文件内容,先写入远端临时文件,再原子替换到目标路径

Non-goals / 非目标

EN: This repo is intentionally narrow. It is not trying to be:

  • a general remote shell framework
  • a deployment tool
  • a remote IDE replacement
  • a multi-agent orchestration layer

中文: 这个仓库刻意保持聚焦。它并不打算成为:

  • 通用远程 shell 框架
  • 部署工具
  • 远程 IDE 替代品
  • 多 agent 编排层

EN: The goal is simply to make large remote-project workflows practical for Claude Code when local memory is limited.

中文: 它的目标很简单:当本机内存有限时,让 Claude Code 也能真正实用于大型远端项目工作流。

Why a standalone repo / 为什么做成独立仓库

EN: This project is published as a standalone repository because that gives the clearest install story, documentation surface, and reuse path for other people.

中文: 这个项目之所以做成独立仓库,是因为这样最利于安装、文档组织和他人复用。

Compared with the main alternatives / 与其他常见形式相比:

  • standalone repo: best for broad adoption and a clear public artifact
    独立仓库:最适合公开传播和形成清晰的公共产物
  • template repo: better when users are expected to fork and customize heavily
    模板仓库:适合用户大量 fork 后自行改造
  • personal config subdirectory: easiest for one user, weakest for discoverability
    个人配置子目录:对单个用户最方便,但最不利于被发现和复用
  • lightweight one-off publish: fast, but usually undersells the workflow and safety model
    轻量一次性发布:速度快,但通常会低估这套工作流和安全模型的价值

Suggested first-use checklist / 首次使用建议清单

  • test against a disposable or non-production host
    先在可丢弃或非生产主机上测试
  • make sure SSH auth is already working non-interactively
    确保 SSH 认证已经能无交互工作
  • inspect repo state before editing
    编辑前先检查仓库状态
  • start with narrow commands like pwd, git status --short --branch, or a single targeted test
    pwdgit status --short --branch 或单个聚焦测试这类小命令开始
  • confirm any destructive action explicitly
    对任何破坏性操作都显式确认

License / 许可证

MIT License.

About

A Claude Code skill for working in large remote Linux repositories over SSH when your local machine does not have enough memory to run the project comfortably.

Topics

Resources

License

Stars

Watchers

Forks

Packages

 
 
 

Contributors

Languages