{"id":50984664,"url":"https://github.com/yxhpy/remotecc-claude-session","last_synced_at":"2026-06-19T18:01:35.288Z","repository":{"id":352334262,"uuid":"1214759858","full_name":"yxhpy/remotecc-claude-session","owner":"yxhpy","description":"Session-first remote Claude Code orchestration over SSH, tmux, and rsync, with Codex skill integration.","archived":false,"fork":false,"pushed_at":"2026-04-19T02:52:11.000Z","size":44,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-19T04:28:33.361Z","etag":null,"topics":["claude-code","codex","python","remote-development","rsync","ssh","tmux"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yxhpy.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-19T02:27:09.000Z","updated_at":"2026-04-19T02:51:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yxhpy/remotecc-claude-session","commit_stats":null,"previous_names":["yxhpy/remotecc-claude-session"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/yxhpy/remotecc-claude-session","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yxhpy%2Fremotecc-claude-session","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yxhpy%2Fremotecc-claude-session/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yxhpy%2Fremotecc-claude-session/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yxhpy%2Fremotecc-claude-session/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yxhpy","download_url":"https://codeload.github.com/yxhpy/remotecc-claude-session/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yxhpy%2Fremotecc-claude-session/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34542467,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-19T02:00:06.005Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","codex","python","remote-development","rsync","ssh","tmux"],"created_at":"2026-06-19T18:01:31.060Z","updated_at":"2026-06-19T18:01:35.280Z","avatar_url":"https://github.com/yxhpy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# remotecc\n\n![Python](https://img.shields.io/badge/python-3.10%2B-0f172a?style=flat-square)\n![Workflow](https://img.shields.io/badge/workflow-ssh%20%2B%20tmux%20%2B%20rsync-1d4ed8?style=flat-square)\n![Status](https://img.shields.io/badge/status-mvp-0f766e?style=flat-square)\n![CI](https://img.shields.io/github/actions/workflow/status/yxhpy/remotecc-claude-session/ci.yml?branch=main\u0026style=flat-square)\n![License](https://img.shields.io/github/license/yxhpy/remotecc-claude-session?style=flat-square)\n\nSession-first remote orchestration for Claude Code over SSH.\n\n`remotecc` mirrors a local project to a remote machine, starts Claude Code inside a persistent `tmux` session, routes model choice explicitly, and pulls changes back with a simple, auditable workflow.\n\nThis repository is both:\n\n- the Python package in [src/remotecc](./src/remotecc)\n- the Codex skill root via [SKILL.md](./SKILL.md)\n\n## Highlights\n\n- Session-first by design. A local registry keeps remote workspace, `tmux`, model, and auth state explicit.\n- Skill-ready. `ready --json` and `models --json` provide stable machine interfaces for upstream skills and automations.\n- Pragmatic transport. Uses `rsync + ssh + tmux` instead of pretending a remote filesystem mount is reliable enough for agent workflows.\n- Human-bootstrap compatible. Password-auth sessions are supported through SSH control master without storing the password.\n- Model-aware. Supports `haiku`, `sonnet`, `opus`, `opusplan`, and profile-based routing.\n\n## Architecture\n\n```mermaid\nflowchart LR\n    local[\"Local project\"]\n    registry[\"Local session registry\u003cbr/\u003e~/.remotecc/sessions.json\"]\n    ssh[\"SSH / control master\"]\n    tmux[\"Remote tmux session\"]\n    claude[\"Claude Code\"]\n\n    local --\u003e|\"rsync push / pull\"| tmux\n    registry --\u003e tmux\n    ssh --\u003e tmux\n    tmux --\u003e claude\n```\n\n## Why This Exists\n\nRemote-agent workflows usually fail in boring places: broken reconnects, invisible session state, unclear model routing, or ad hoc shell tabs that nobody can recover later.\n\n`remotecc` chooses a narrower path on purpose:\n\n- one explicit remote workspace per session\n- one durable `tmux` session per task lane\n- one local registry as the operational source of truth\n- one predictable sync model instead of live remote mounts\n\nThat makes the MVP easier to reason about, easier to automate, and easier to recover.\n\n## Installation\n\n### Install the CLI locally\n\n```bash\npython3 -m pip install -e .\n```\n\nOr run directly from the repo root:\n\n```bash\npython3 scripts/remotecc.py --help\n```\n\n### Install as a Codex skill\n\nManual clone:\n\n```bash\ngit clone https://github.com/yxhpy/remotecc-claude-session.git ~/.codex/skills/remotecc-claude-session\n```\n\nVia `skill-installer`:\n\n```bash\npython3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py --repo yxhpy/remotecc-claude-session --path . --name remotecc-claude-session --method git\n```\n\nNotes:\n\n- `--path .` is required because the repository root is the skill root.\n- `--method git` is the reliable fallback when Python download mode hits local SSL certificate issues.\n- Restart Codex after installation so the skill is discovered.\n\n## Requirements\n\nLocal machine:\n\n- `ssh`\n- `rsync`\n- Python 3.10+\n\nRemote machine:\n\n- `bash`\n- `tmux`\n- `rsync`\n- `claude` CLI installed and already authenticated\n\nThe sync flags stay conservative so the CLI works with the older `rsync` implementation that ships on macOS.\n\n## Quick Start\n\nCreate a session:\n\n```bash\npython3 scripts/remotecc.py create demo user@host --local-dir . --profile standard\n```\n\nBootstrap with password-auth when the first connection needs a password or key passphrase:\n\n```bash\npython3 scripts/remotecc.py create demo user@host --local-dir . --profile standard --password-auth\n```\n\nCheck non-interactive readiness:\n\n```bash\npython3 scripts/remotecc.py ready demo --json\n```\n\nIf Claude is blocked on a workspace-trust prompt or an edit/bash approval prompt, `ready --json` returns `ready: false` and includes `blocker_kind` plus `blocker_reason`.\n\nStart Claude Code:\n\n```bash\npython3 scripts/remotecc.py start demo\n```\n\nSend one request:\n\n```bash\npython3 scripts/remotecc.py send demo --text \"Inspect this repo and summarize the entrypoint.\"\n```\n\nIf Claude stops at an interactive approval screen, `send` exits with code `2` and prints a `blocked:` message instead of silently reporting success.\n\nApprove a blocker:\n\n```bash\npython3 scripts/remotecc.py approve demo\npython3 scripts/remotecc.py approve demo --mode session\n```\n\nFor longer or noisier work, submit asynchronously and observe only a short pane tail:\n\n```bash\npython3 scripts/remotecc.py send demo --text \"Implement the change.\" --no-wait\npython3 scripts/remotecc.py observe demo\npython3 scripts/remotecc.py observe demo --follow\n```\n\nPull changes back:\n\n```bash\npython3 scripts/remotecc.py pull demo\n```\n\nClose the session:\n\n```bash\npython3 scripts/remotecc.py close demo --drop-remote\n```\n\n## Use From Codex\n\nAfter skill installation, Codex can invoke:\n\n```text\n$remotecc-claude-session\n```\n\nExample prompt:\n\n```text\nUse $remotecc-claude-session to create a remote Claude session on user@host for /abs/project, use the standard profile, start it, and report whether it is ready for non-interactive use.\n```\n\n## Session Lifecycle\n\nEach session tracks:\n\n- local working directory\n- SSH target\n- remote workspace path\n- remote `tmux` session name\n- Claude command\n- model alias and profile\n- lifecycle timestamps\n\nLocal state is stored in:\n\n```text\n~/.remotecc/sessions.json\n```\n\nRecommended operational flow:\n\n1. `create`\n2. `ready --json`\n3. `start`\n4. `send`, or `send --no-wait` + `observe`\n5. `pull`\n6. `close`\n\nWhile Claude Code is actively editing, treat the remote workspace as the active writer.\n\n## Authentication Posture\n\nThere are two intended modes:\n\n- key-based SSH for unattended use\n- `--password-auth` for human bootstrap\n\n`--password-auth` does not store passwords. It opens a session-scoped SSH control master so later `ssh` and `rsync` calls can reuse the same authenticated channel.\n\nIf the control socket expires:\n\n```bash\npython3 scripts/remotecc.py connect demo\n```\n\nFor skills and automations, the rule is simple:\n\n- a human may bootstrap\n- automation should only continue when `ready --json` says the session is usable\n- for longer tasks, automation should prefer `send --no-wait` plus `observe --json` over repeatedly calling `capture`\n\n## Claude Model Routing\n\nAsk for machine-readable guidance:\n\n```bash\npython3 scripts/remotecc.py models --json\n```\n\nDefault profiles:\n\n- `simple` -\u003e `haiku`\n- `standard` -\u003e `sonnet`\n- `complex` -\u003e `opus`\n- `plan` -\u003e `opusplan`\n- `long` -\u003e `sonnet[1m]`\n\nPractical guidance:\n\n- `haiku` or `hk`: listing, grep, summaries, tiny low-risk edits\n- `sonnet`: everyday implementation, common bug fixes, medium refactors\n- `opus`: architecture, risky migrations, ambiguous debugging, deep review\n- `opusplan`: planning-first workflows where plan quality matters most\n\nExamples:\n\n```bash\npython3 scripts/remotecc.py models --json\npython3 scripts/remotecc.py create demo user@host --local-dir . --profile standard\npython3 scripts/remotecc.py start demo --model opus\npython3 scripts/remotecc.py set-model demo --profile complex\npython3 scripts/remotecc.py send demo --profile simple --text \"Summarize this folder.\"\n```\n\n## Operational Notes\n\nClaude Code itself may still prompt on first use for:\n\n- workspace trust\n- edit approval\n\nThat is separate from SSH auth. Clear those prompts once during bootstrap, or choose a deliberately permissive Claude command only when that tradeoff is acceptable:\n\n```bash\npython3 scripts/remotecc.py create demo user@host --local-dir . --model opus --claude-command \"claude --dangerously-skip-permissions\"\n```\n\n## Scope and Limits\n\n- No live mounted filesystem\n- No automatic conflict resolution\n- No remote sandboxing\n- Pane-based output capture rather than a structured Claude API\n\nThis is an MVP session layer, not a distributed development environment.\n\n## Project Status\n\nThe project is intentionally narrow and operational:\n\n- repo-root skill packaging is in place\n- remote session bootstrap and recovery are implemented\n- model routing is explicit and machine-readable\n- basic closed-loop validation has been completed\n\n## Repository Layout\n\n- [SKILL.md](./SKILL.md): Codex skill instructions\n- [agents/openai.yaml](./agents/openai.yaml): skill UI metadata\n- [scripts/remotecc.py](./scripts/remotecc.py): repo-root launcher\n- [references/command-cookbook.md](./references/command-cookbook.md): command patterns and common failures\n- [src/remotecc](./src/remotecc): Python implementation\n- [README.zh-CN.md](./README.zh-CN.md): Chinese guide\n- [CONTRIBUTING.md](./CONTRIBUTING.md): contribution workflow\n- [SECURITY.md](./SECURITY.md): security reporting\n- [CHANGELOG.md](./CHANGELOG.md): release history\n\n## Community and Governance\n\n- [LICENSE](./LICENSE)\n- [CONTRIBUTING.md](./CONTRIBUTING.md)\n- [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)\n- [SECURITY.md](./SECURITY.md)\n- [SUPPORT.md](./SUPPORT.md)\n- [CHANGELOG.md](./CHANGELOG.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyxhpy%2Fremotecc-claude-session","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyxhpy%2Fremotecc-claude-session","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyxhpy%2Fremotecc-claude-session/lists"}