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

4 stars

Watchers

0 watching

Forks

Packages

 
 
 

Contributors

Languages