rules/remote-server.md

# Remote Server Access

A remote server is configured for SSH access. Use the `/onremote` command or direct `ssh` via the Bash tool to run operations on it.

## Connection

The remote host and credentials are baked into `~/.claude/commands/onremote.md` at install time. Use SSH via Bash:

```bash
ssh {remote-user}@{remote-host} "command"
```

For file transfers use `scp` or `rsync`.

## When to Use Remote Access

- Checking on long-running services or background processes
- Restarting services that have crashed or stalled
- Viewing logs from remote processes
- Running maintenance tasks (disk cleanup, log rotation)
- Running commands that require the remote machine's hardware or environment

## Rules

- Use `/onremote` for status checks and single commands
- Never start interactive sessions (`ssh -t` with a shell) - output-only commands only
- Do not run destructive operations (rm, shutdown, kill -9) without explicit user confirmation
- For multi-step operations, chain commands with `&&` in a single SSH call rather than multiple round-trips
- Prefer reading log files (`tail -n 50 /path/to/log`) over running verbose diagnostic tools

commands/onremote.md

Uses installer-substituted placeholders -- install via the bash installer, or fill in the __VARS__ after copying.

---
description: Run a task on __REMOTE_ALIAS__ by describing it in plain language
allowed-tools: Agent
---

# /onremote - Remote Server Task Runner

Use the Agent tool to execute this workflow on a cheaper model:

- **model**: haiku
- **description**: remote server task

Pass all workflow instructions and the input to the agent.

After the agent completes, relay its output to the user exactly as received.

---

## Workflow Instructions

Remote server: `__REMOTE_USER__@__REMOTE_HOST__` (__REMOTE_ALIAS__)

### Input

```
$ARGUMENTS
```

### If no arguments - Health Check

Run a health check and present a brief status report:

```bash
ssh __REMOTE_USER__@__REMOTE_HOST__ "uptime"
ssh __REMOTE_USER__@__REMOTE_HOST__ "df -h /"
ssh __REMOTE_USER__@__REMOTE_HOST__ "ps -u __REMOTE_USER__ -o pid,command | grep -Ev '/System/|/usr/lib|/usr/sbin|Contents/MacOS|\.framework' | grep -v PID"
```

Present as:

```
Remote: __REMOTE_ALIAS__ (__REMOTE_HOST__)
Uptime:  {uptime}
Disk:    {df /}

Active processes:
{process list}
```

### If arguments provided - Execute Task

The arguments are a natural language description of what to do on the remote server.

1. Interpret the intent
2. Determine what shell commands are needed to accomplish it
3. Run them via SSH: `ssh __REMOTE_USER__@__REMOTE_HOST__ "..."`
4. Report back in plain language - what you did and what the result was

Examples of how to interpret input:
- "check if myservice is running" → `ps aux | grep myservice`
- "how much disk space is left" → `df -h /`
- "restart ollama" → `brew services restart ollama` (or find the right command)
- "show the last 50 lines of the myservice log" → find the log file and tail it
- "what processes are using the most CPU" → `ps aux | sort -rk3 | head -10`

Use multiple SSH calls if needed. Interpret the task fully - do not ask clarifying questions unless the intent is genuinely ambiguous.

settings.partial.json

Merged into ~/.claude/settings.json -- a fragment, not a replacement.

{
  "permissions": {
    "allow": [
      "Bash(ssh:*)",
      "Bash(scp:*)",
      "Bash(rsync:*)",
      "Bash(ssh-keyscan:*)",
      "Bash(ssh-copy-id:*)"
    ]
  }
}