{
  "markdown": "<p align=\"center\">\n  <img src=\"assets/icon.png\" height=\"128\">\n</p>\n\n<h1 align=\"center\">hop</h1>\n\n<p align=\"center\">\n  Stop typing long SSH commands. Just <code>hop prod</code> and you're in.\n</p>\n\n<p align=\"center\">\n  <img src=\"hop.gif\" alt=\"hop TUI dashboard\">\n</p>\n\n## Why hop?\n\n```bash\n# Before: remembering and typing this every time\nssh -i ~/.ssh/work_key deploy@app-server-prod-03.us-east-1.example.com -p 2222\n\n# After\nhop prod\n```\n\n```bash\nhop prod                         # fuzzy match any server\nhop exec production \"uptime\"     # run command on all prod servers\nhop import                       # import your existing ~/.ssh/config\nhop                              # launch the TUI, manage everything\n```\n\n## Install\n\n### Homebrew (macOS/Linux)\n\n```bash\nbrew install danmartuszewski/tap/hop\n```\n\n### Go\n\n```bash\ngo install github.com/danmartuszewski/hop/cmd/hop@latest\n```\n\n### From source\n\n```bash\ngit clone https://github.com/danmartuszewski/hop.git && cd hop && make build\n./bin/hop\n```\n\n### Install with an AI agent\n\nUsing Claude Code, Codex, Cursor, or another coding agent? Paste the block below into your agent and it will pick the right install path for your machine, register hop's MCP server, and verify the install.\n\n```text\nInstall hop on this machine and register its MCP server. Do the steps in order;\nstop and report on the first failure.\n\n1. Pick ONE install method, in this priority:\n   a. Homebrew (macOS or Linux):\n        brew install danmartuszewski/tap/hop\n   b. Go 1.22+ available:\n        go install github.com/danmartuszewski/hop/cmd/hop@latest\n   c. From source (no brew, no Go on PATH):\n        git clone https://github.com/danmartuszewski/hop.git && cd hop && make install\n\n2. Verify the binary is on PATH:\n        hop version\n\n3. Register the MCP server with whichever agent the user is running. Skip\n   clients the user does not use:\n   - Claude Code:  claude mcp add hop -- hop mcp\n   - Codex CLI:    codex mcp add hop -- hop mcp\n   - Claude Desktop / Cursor / Windsurf — add to the client's MCP config:\n        { \"hop\": { \"command\": \"hop\", \"args\": [\"mcp\"] } }\n\n4. (Optional) Seed the config from the user's existing SSH config. Preview\n   first; --yes is required for a non-interactive run:\n        hop import --dry-run\n        hop import --yes\n\n5. Confirm hop's MCP tools are reachable from the agent (e.g. list_connections).\n\nConstraints:\n- Do NOT run bare `hop` — it launches an interactive TUI and will hang a\n  non-interactive session. Use subcommands (`hop version`, `hop list`, …).\n- Do NOT modify ~/.ssh/config. hop reads it via `hop import` only.\n- Do NOT commit secrets or identity files.\n\nAfter step 3, restart the agent so it picks up the new MCP server.\n```\n\n## Features\n\n- **Fuzzy matching** - Type `hop prod` to connect to `app-server-prod-03`\n- **TUI dashboard** - Browse, add, edit, delete connections with keyboard or mouse\n- **SSH config import** - Already have servers in `~/.ssh/config`? Import them in one command\n- **Export** - Export filtered connections to YAML for sharing or backup\n- **Multi-exec** - Run commands across multiple servers at once\n- **Groups & tags** - Organize by project, environment, or custom tags\n- **Jump hosts** - ProxyJump support for bastion servers\n- **Landing directory** - Drop straight into a predefined working directory on connect\n- **MCP server** - Let AI assistants manage your servers — search connections, run commands, check status across projects\n- **Mosh support** - Use [mosh](https://mosh.org/) instead of SSH for roaming and unreliable connections\n- **Zero dependencies** - Single binary, works anywhere\n\n> **See all features in action:** [Demo recordings](demo/DEMOS.md)\n\n## Raycast Extension\n\nLaunch connections directly from Raycast. Fuzzy search, tags, environments - all at your fingertips.\n\n[Install from Raycast Store](https://www.raycast.com/danmartuszewski/hop)\n\n<p align=\"center\">\n  <img src=\"assets/hop1.png\" width=\"32%\">\n  <img src=\"assets/hop2.png\" width=\"32%\">\n  <img src=\"assets/hop3.png\" width=\"32%\">\n</p>\n\n## Configuration\n\nConfig file location: `~/.config/hop/config.yaml`\n\n```yaml\nversion: 1\n\ndefaults:\n  user: admin\n  port: 22\n  # use_mosh: true             # Uncomment to use mosh for all connections\n\nconnections:\n  - id: prod-web\n    host: web.example.com\n    user: deploy\n    identity_file: ~/.ssh/work_key   # Private key for this connection\n    remote_dir: /var/www/myapp       # Land in this directory on connect\n    project: myapp\n    env: production\n    tags: [web, prod]\n\n  - id: prod-db\n    host: db.example.com\n    user: dbadmin\n    port: 5432\n    project: myapp\n    env: production\n    tags: [database, prod]\n\n  - id: staging\n    host: staging.example.com\n    user: deploy\n    project: myapp\n    env: staging\n\n  - id: private-server\n    host: 10.0.1.50\n    user: admin\n    proxy_jump: bastion          # Connect via jump host\n    forward_agent: true          # Forward SSH agent\n\n  - id: remote-dev\n    host: dev.example.com\n    user: dan\n    use_mosh: true               # Use mosh instead of SSH\n\ngroups:\n  production: [prod-web, prod-db]\n  web-servers: [prod-web, staging]\n```\n\n> **Security note:** `forward_agent: true` exposes your SSH keys to anyone with root access on the remote server. Only enable this for servers you fully trust. Consider using `proxy_jump` instead when you just need to reach internal hosts through a bastion.\n\n### Mosh Support\n\n[Mosh](https://mosh.org/) (mobile shell) is useful for connections over unreliable networks — it handles roaming, intermittent connectivity, and high latency gracefully.\n\n**Global default** — enable mosh for all connections:\n\n```yaml\ndefaults:\n  use_mosh: true\n\nconnections:\n  - id: remote-dev\n    host: dev.example.com\n\n  - id: legacy-server\n    host: old.example.com\n    use_mosh: false              # Override: use SSH for this one\n```\n\n**Per-connection** — enable mosh for specific connections:\n\n```yaml\nconnections:\n  - id: remote-dev\n    host: dev.example.com\n    user: dan\n    use_mosh: true\n```\n\n**One-off** — use the `--mosh` flag without changing config:\n\n```bash\nhop connect myserver --mosh\nhop myserver --mosh\n```\n\nPer-connection `use_mosh: false` overrides the global default. SSH options (port, identity file, proxy jump, agent forwarding) are automatically passed to mosh via its `--ssh` flag. Mosh requires both the local `mosh-client` and `mosh-server` on the remote host.\n\n> **Note:** `hop exec` always uses SSH regardless of `use_mosh`, since mosh is designed for interactive sessions.\n\n### Landing Directory\n\nSet `remote_dir` to have a connection drop you straight into a specific directory instead of `$HOME`:\n\n```yaml\nconnections:\n  - id: prod-web\n    host: web.example.com\n    user: deploy\n    remote_dir: /var/www/myapp   # cd here on connect\n\n  - id: my-dev\n    host: dev.example.com\n    remote_dir: ~/projects/api   # ~ is expanded on the remote host\n```\n\nOn connect, hop runs `cd` into the directory and then hands you a normal interactive login shell, so the session behaves exactly like a regular SSH login — just somewhere else. A few details worth knowing:\n\n- **Absolute paths and `~` both work.** `~` and `~user` are expanded by the remote shell.\n- **Forgiving by design.** If the directory is missing or inaccessible, you still land in a shell (in `$HOME`) rather than getting bounced off the host.\n- **Works in new tabs too.** `hop open` carries the landing directory into every terminal it launches.\n\n> **Note:** `remote_dir` is ignored when you pass an explicit command (e.g. `hop connect web -- uptime` or `hop exec`), since those aren't interactive sessions.\n\n## TUI Dashboard\n\nLaunch with `hop` or `hop dashboard`.\n\nWhen you connect to a server from the dashboard (by pressing Enter), the SSH session starts, and **the dashboard automatically returns after the session ends**. This lets you quickly hop between servers without restarting the TUI each time.\n\nFor one-shot connections that exit to your terminal, use:\n```bash\nhop <query>           # fuzzy match and connect\nhop connect <id>      # connect by exact ID\n```\n\n### Keyboard Shortcuts\n\n| Key | Action |\n|-----|--------|\n| `↑/k` | Move up |\n| `↓/j` | Move down |\n| `PgUp/PgDn` | Move by page |\n| `g` | Go to top |\n| `G` | Go to bottom |\n| `/` | Filter connections (supports multi-keyword AND search) |\n| `t` | Filter by tags |\n| `r` | Toggle sort by recent |\n| `Enter` | Connect to selected |\n| `a` | Add new connection |\n| `i` | Import from SSH config |\n| `p` | Paste SSH string (quick add) |\n| `e` | Edit selected |\n| `c` | Duplicate selected (opens a prefilled copy) |\n| `d` | Delete selected |\n| `x` | Export connections to YAML |\n| `y` | Copy SSH command |\n| `T` | Open theme picker |\n| `?` | Show help |\n| `q` | Quit |\n\n### Filtering Connections\n\nPress `/` to filter connections by typing keywords. The filter supports **multi-keyword AND logic** - separate keywords with spaces to find connections matching all terms.\n\n**Examples:**\n- `prod` - matches connections containing \"prod\"\n- `prod web` - matches connections containing both \"production\" AND \"web\"\n- `kaf staging` - matches connections with both \"kafka\" AND \"staging\"\n\nThe filter searches across connection IDs, hosts, projects, environments, and tags.\n\n### Quick Add with Paste\n\nPress `p` and paste any of these formats:\n\n```\nuser@host.com\nuser@host.com:2222\nssh user@host.com -p 2222\nssh://user@host:port\n```\n\nThe connection form opens with fields pre-filled.\n\n### Duplicating a Connection\n\nPress `c` on any connection to create a copy. The add form opens with **every\nfield pre-filled** from the original — including options that aren't shown in\nthe form, like proxy jump and mosh — and a collision-free ID suggestion (e.g.\n`web-prod` → `web-prod-copy`). Adjust whatever you need and save. If you pick an\nID that already exists, the form stays open with your edits intact so you can\nfix it.\n\n### Importing from SSH Config\n\nImport existing connections from your `~/.ssh/config` file:\n\n**From the dashboard:** Press `i` to open the import modal, select which connections to import, and press Enter.\n\n**From the CLI:**\n```bash\nhop import                   # Import from ~/.ssh/config\nhop import --dry-run         # Preview what would be imported\nhop import --file ~/.ssh/config.d/work  # Import from custom path\n```\n\n**What gets imported:**\n- Host alias becomes the connection ID\n- HostName, User, Port, IdentityFile\n- ProxyJump for jump host connections\n- ForwardAgent setting\n\n**What gets skipped:**\n- Wildcard patterns (`Host *`, `Host *.example.com`)\n- Entries without a HostName (alias is used as hostname)\n\n**Conflict handling:** If a connection ID already exists, the imported connection is renamed with `-imported` suffix (e.g., `myserver` → `myserver-imported`).\n\n### Exporting Connections\n\nExport a subset of connections to a YAML file for sharing, backup, or transferring to another machine.\n\n**From the dashboard:** Press `x` to open the export modal. Only currently filtered connections are shown — apply text or tag filters first to narrow the selection. Toggle items with Space, then press Enter to save.\n\n**From the CLI:**\n```bash\nhop export --all                          # Export all to stdout\nhop export --all -o backup.yaml           # Export all to a file\nhop export --project myapp -o myapp.yaml  # Export by project\nhop export --tag database                 # Export by tag\nhop export --env production               # Export by environment\nhop export --id web-1,web-2              # Export specific connections\n```\n\nAt least one filter flag or `--all` is required. Filters combine with AND logic.\n\n### Theming\n\nThe dashboard ships with sixteen color presets — each popular theme has both a dark and a light variant, listed separately so you can pick whichever you want regardless of your terminal background. Press `T` to browse them with live preview: `↑/↓` to navigate, `Enter` to save the choice into your config, `Esc` to revert.\n\n| Family | Dark | Light |\n|---|---|---|\n| Built-in hop | `default-dark` | `default-light` |\n| Everforest | `everforest-dark` | `everforest-light` |\n| Gruvbox | `gruvbox-dark` | `gruvbox-light` |\n| Catppuccin | `catppuccin-mocha` | `catppuccin-latte` |\n| Tokyo Night | `tokyo-night-storm` | `tokyo-night-day` |\n| Solarized | `solarized-dark` | `solarized-light` |\n| Nord | `nord` | `nord-light` |\n| Dracula | `dracula` | `alucard` |\n\nPicking a preset writes a single line to your config:\n\n```yaml\ntheme_preset: everforest-dark\n```\n\nWhen `theme_preset` is unset, hop auto-picks `default-dark` or `default-light` based on your terminal background.\n\n#### Custom overrides\n\nLayer your own colors on top of any preset:\n\n```yaml\ntheme_preset: everforest-dark   # optional; omit to auto-pick default\ntheme:                          # applies to every preset\n  primary: \"#0066cc\"\ntheme_dark:                     # only applies when the preset is a dark variant\n  selection: \"#1f1f28\"\ntheme_light:                    # only applies when the preset is a light variant\n  foreground: \"#1c1f24\"\n```\n\nColor values can be either a quoted ANSI 256 code (`\"39\"`) or a hex string (`\"#bd93f9\"`). ANSI codes adapt to your terminal's palette; hex values are absolute.\n\nAvailable keys: `primary`, `secondary`, `accent`, `success`, `warning`, `error`, `muted`, `selection`, `foreground`. Any key you don't set falls through to the preset, then to the built-in default.\n\n## CLI Commands\n\n```bash\nhop                          # Open TUI dashboard\nhop <query>                  # Fuzzy match and connect\nhop connect <id>             # Connect by exact ID\nhop get <id> <field>         # Print single field value to stdout\nhop get <id> f1,f2,f3        # Print multiple fields tab-separated\nhop get <id>                 # Print all fields as \"key value\" lines\nhop get --help               # Full field list and flags\nhop list                     # List all connections\nhop list --json              # List as JSON\nhop list --flat              # Flat list without grouping\nhop import                   # Import from ~/.ssh/config\nhop import --file <path>     # Import from custom path\nhop import --dry-run         # Preview without importing\nhop export --all             # Export all connections to stdout\nhop export --project <name>  # Export filtered connections\nhop export --tag <tag> -o f  # Export to file\nhop open <target...>         # Open multiple terminal tabs\nhop exec <target> \"cmd\"      # Execute command on multiple servers\nhop resolve <target>         # Test which connections a target matches\nhop mcp                      # Start MCP server (read-only)\nhop mcp --allow-exec         # Start MCP server with remote exec\nhop version                  # Show version\n```\n\n### Targeting\n\nCommands like `exec` and `open` accept a **target** that resolves to one or more connections. The target is matched in this order:\n\n1. **Named group** — an explicit list of connection IDs defined under `groups:` in config\n2. **Project-env pattern** — matches connections by `project` and `env` fields (e.g. `myapp-prod` matches all connections with `project: myapp` and `env: prod`)\n3. **Glob pattern** — wildcard matching on connection IDs (e.g. `web*`, `*-prod-*`)\n4. **Fuzzy match** — falls back to fuzzy matching a single connection ID\n\nYou can also filter any target by tag with `--tag`.\n\nUse `hop resolve` to preview which connections a target will match before running anything:\n\n```bash\nhop resolve production              # see what \"production\" resolves to\nhop resolve \"web*\"                  # test a glob pattern\nhop resolve myapp-prod --tag=web    # combine target + tag filter\n```\n\n### Examples\n\n```bash\n# Fuzzy connect\nhop prod                # matches \"prod-web\", \"prod-db\", etc.\nhop web                 # matches first *web* server\n\n# Multi-exec with different target types\nhop exec production \"uptime\"           # named group\nhop exec myapp-prod \"df -h\"            # project-env pattern\nhop exec \"web*\" \"systemctl status\"     # glob pattern\nhop exec --tag=database \"psql -c '\\\\l'\" # tag filter\n\n# Open multiple tabs\nhop open production                    # named group\nhop open web1 db1 api1                 # specific IDs\nhop open myapp-prod -- \"htop\"          # with initial command\n\n# List connections\nhop list --flat\n```\n\n### Scripting with hop\n\n`hop get` prints connection fields to stdout so you can drop them straight into shell pipelines and command substitutions — think of it as `ssh -G` for your hop config.\n\n```bash\n# Build an ssh invocation from config:\nssh -i \"$(hop get prod identity_file)\" \"$(hop get prod user)@$(hop get prod host)\"\n```\n\n```bash\n# Read multiple fields at once (tab-separated):\nIFS=$'\\t' read -r host port user < <(hop get prod host,port,user)\n```\n\n```bash\n# Fallback when a field is empty:\nhop get prod port --default 22\n```\n\n```bash\n# Strict shells: suppress the trailing newline.\nhop get prod host -n\n```\n\n```bash\n# Dump all non-empty scalar fields (ssh -G style \"key value\" lines):\nhop get prod\n```\n\n```bash\n# Read a single SSH option by key:\nhop get prod options.StrictHostKeyChecking\n```\n\n```bash\n# Structured output for jq and friends:\nhop get prod host,port --json | jq -r .host\n```\n\n**Matching is exact ID only** (not fuzzy) — safer inside scripts. Unknown IDs exit 1 with a \"did you mean\" hint. See `hop get --help` for the full field list.\n\n## MCP Server (AI Assistant Integration)\n\nhop includes a built-in [Model Context Protocol](https://modelcontextprotocol.io/) server that lets AI assistants like Claude Code and Codex manage your servers directly. Ask your assistant to check disk space across production, restart a service on staging, or find which servers belong to a project — it discovers your connections, resolves targets, and executes commands through hop.\n\n<p align=\"center\">\n  <img src=\"assets/mcp.png\" alt=\"Claude Code managing servers through hop's MCP server\">\n</p>\n\n### Setup\n\n**Claude Code:**\n```bash\nclaude mcp add hop -- hop mcp\n```\n\n**Codex CLI:**\n```bash\ncodex mcp add hop -- hop mcp\n```\n\n**Claude Desktop** — add to your config (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n```json\n{\n  \"mcpServers\": {\n    \"hop\": {\n      \"command\": \"hop\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\n**Codex** — add to `~/.codex/config.toml`:\n```toml\n[mcp_servers.hop]\ncommand = \"hop\"\nargs = [\"mcp\"]\n```\n\nOr generate the Claude Desktop config automatically:\n```bash\nhop mcp --print-client-config                  # read-only\nhop mcp --print-client-config --allow-exec     # with remote exec enabled\n```\n\n### Tools\n\nBy default, only read-only tools are exposed:\n\n| Tool | Description |\n|------|-------------|\n| `list_connections` | List connections, filter by project/env/tag |\n| `search_connections` | Fuzzy search across all connections |\n| `get_connection` | Get details for a specific connection |\n| `resolve_target` | Preview how a target pattern resolves |\n| `list_groups` | List all named groups |\n| `get_history` | Connection usage history |\n| `build_ssh_command` | Build the full SSH command string |\n\nTo enable remote command execution, start with `--allow-exec`:\n\n```bash\nclaude mcp add hop -- hop mcp --allow-exec\ncodex mcp add hop -- hop mcp --allow-exec\n```\n\nThis adds the `exec_command` tool, which runs shell commands on matched servers with output limits (64KB/host, 50 hosts max).\n\n### Resources\n\nThe server also exposes browsable resources:\n\n| URI | Description |\n|-----|-------------|\n| `hop://config` | Config summary (counts, projects, environments) |\n| `hop://connections` | All connections |\n| `hop://connections/{id}` | Individual connection details |\n| `hop://groups` | All groups and members |\n\n### Security\n\n- Identity files (SSH key paths) are never exposed through MCP\n- Remote execution is disabled by default and requires explicit `--allow-exec`\n- All logging goes to stderr to keep the JSON-RPC transport clean\n\n## Shell Completions\n\n```bash\n# Bash (Linux)\nhop completion bash | sudo tee /etc/bash_completion.d/hop > /dev/null\n\n# Bash (macOS with Homebrew)\nhop completion bash > $(brew --prefix)/etc/bash_completion.d/hop\n\n# Zsh (add to ~/.zshrc)\nsource <(hop completion zsh)\n\n# Fish\nhop completion fish > ~/.config/fish/completions/hop.fish\n```\n\n## Flags\n\n```bash\n-c, --config <path>    # Use custom config file\n-v, --verbose          # Verbose output\n-q, --quiet            # Suppress non-essential output\n    --dry-run          # Print SSH command without executing\n    --mosh             # Use mosh instead of SSH for this connection\n```\n\n## Building\n\n```bash\nmake build          # Build binary to ./bin/hop\nmake test           # Run tests\nmake test-docker    # Run tests in Docker (isolated)\nmake install        # Install to $GOPATH/bin\nmake docker         # Build Docker image\n```\n\n## Docker\n\n```bash\n# Build image\ndocker build -t hop .\n\n# Run interactively\ndocker run -it --rm hop\n\n# Run tests in container\ndocker build --target tester -t hop-test .\n```\n\n## Project Structure\n\n```\nhop/\n├── cmd/hop/           # Main entry point\n├── internal/\n│   ├── cmd/           # CLI commands (cobra)\n│   ├── config/        # Configuration loading/saving\n│   ├── export/        # Export logic\n│   ├── fuzzy/         # Fuzzy matching\n│   ├── mcp/           # MCP server (tools, resources, types)\n│   ├── picker/        # Connection picker (promptui)\n│   ├── resolve/       # Target resolution logic\n│   ├── ssh/           # SSH connection handling\n│   ├── sshconfig/     # SSH config parsing\n│   └── tui/           # TUI dashboard (bubbletea)\n├── Dockerfile\n├── Makefile\n└── README.md\n```\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n",
  "bytes": 21550,
  "sha": "609b38d115e3b90e21dbe3a777275e802559fc4227a077b076f847d2b69b1699",
  "repo_slug": "danmartuszewski/hop",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_danmartuszewski_hop_777d721e/readme"
}