explaingit

izzzzzi/agent-assh

★ 12GoAudience · developerComplexity · 3/5ActiveSetup · easy

TLDR

SSH helper for LLM coding agents that runs remote commands in a tmux session and returns paginated output so the agent does not blow its context window.

Mindmap

mindmap
  root((agent-assh))
    Inputs
      Provider server-info blocks
      Passwords via env vars
      Session ids
    Outputs
      JSON session objects
      Paginated command output
      Hashed audit logs
    Use Cases
      Give Claude Code SSH access
      Run Codex on remote servers
      Token-safe agent automation
    Tech Stack
      Go
      tmux
      SSH
      npm wrapper

Things people build with this

USE CASE 1

Give Claude Code or Codex CLI safe SSH access to a remote server without leaking output

USE CASE 2

Run remote commands in a persistent tmux session and read back only the window you need

USE CASE 3

Parse a hosting provider server-info block into host, user, and password fields automatically

Tech stack

GotmuxSSHnpm

Getting it running

Difficulty · easy Time to first run · 5min

Installs via npm i -g agent-assh which downloads the Go binary; the remote host must be Unix-like since tmux is required.

In plain English

agent-assh, command name assh, is an SSH helper aimed at LLM coding agents like Codex, Claude Code, and OpenCode. The problem it solves is that when an agent runs SSH commands directly, the full output gets dumped back into the agent's context window, which wastes tokens and risks leaking passwords or large logs. The README is in Russian with a link to an English version. It sets up access in one shot with assh connect, which generates or reuses an SSH key at ~/.ssh/id_agent_ed25519, tries to log in with that key first, falls back to a password only if you pass one in via an environment variable, then installs the public key on the server, opens a persistent tmux session for ongoing work, garbage-collects old assh sessions, and writes a small local registry. There is also an assh connect-info command that parses a provider's server-info block from a file or stdin so the agent does not have to extract host, user, and password fields by hand. Once connected, you get back a JSON object with a session id and a next_commands map. From then on the agent uses assh session exec to run a command, assh session read with a sequence number and limit to read just the window of output it wants, and assh session close when done. Other commands include exec for a single remote command, read for paginated reads, capabilities to probe the server, scan for a host inventory, key-deploy, and audit for filtered local logs. Security defaults are tight. Passwords are accepted only through environment variables, never as command-line flags. connect-info reads secrets from stdin or a local file but not from arguments. If key login already works, the password env var is ignored. Password values and command text are not written to audit logs, only hashes. SSH is run non-interactively without pseudo-terminal allocation, and the default host-key policy is accept-new with a strict mode available for hardened setups. Install is npm i -g agent-assh, a thin wrapper that downloads the right Go binary from GitHub Releases. The README includes instruction snippets to paste into Codex, Claude Code, or OpenCode so the agent knows to save provider blocks into a 0600 temp file, call connect-info, delete the file, and never echo passwords back. Limits in v1: tmux requires a Unix-like remote and interactive password prompts are not supported.

Copy-paste prompts

Prompt 1
Set up agent-assh for me to connect to my VPS at [email protected] with a password from the SSH_PASSWORD env var
Prompt 2
Write a small Claude Code instruction snippet that tells the agent to save a provider block to a 0600 temp file and call assh connect-info
Prompt 3
Show me how to use assh session exec and assh session read with pagination to run a long build without flooding my agent context
Prompt 4
Compare strict and accept-new host-key policies in agent-assh and tell me which to use for production
Open on GitHub → Explain another repo

Generated 2026-05-22 · Model: sonnet-4-6 · Verify against the repo before relying on details.