SSH autocomplete and the companion

SSH autocomplete has more moving parts than local autocomplete because Conduish has to understand a remote shell environment, not just a local one.

How SSH autocomplete works

At a high level, the flow is:

  1. You open an SSH terminal in Conduish.
  2. Conduish probes the remote shell environment.
  3. Conduish checks whether the remote companion is installed and healthy.
  4. If it is missing, Conduish asks before installing it under ~/.conduish.
  5. Conduish uses the remote shell context to decide how much autocomplete support is available.

The remote shell matters because generator execution is only supported on shells Conduish knows how to handle safely.

Why Conduish uses a companion

Conduish wants an SSH terminal to keep feeling like a normal SSH session, not a synthetic command runner.

That matters because a real login can include server-owned startup output such as Last login, MOTD, and other shell startup messages that users expect to see when they connect to a host.

At the same time, SSH autocomplete needs more remote context than local autocomplete. Conduish has to understand the remote shell, detect what support is available, and install the shell hooks that make autocomplete work.

Conduish does not want to get that context by replacing the normal interactive login flow with a brittle exec-style shortcut. Doing that would make the terminal feel less like a real shell session and make it easier to lose normal startup behavior that comes from the server and shell environment.

The companion gives Conduish a controlled integration point under ~/.conduish, so it can detect shell context, install the managed hooks it needs, and participate in autocomplete without treating SSH like a blind text stream.

In practice, the companion exists so Conduish can do both of these at once:

  • keep the SSH session familiar and usable
  • add shell-aware autocomplete that depends on remote context

What the companion does

The Conduish shell companion is the remote integration layer that allows SSH sessions to participate in terminal features that need remote context.

The companion is required for SSH autocomplete

The companion is a prerequisite for SSH autocomplete, not an optional enhancement.

For autocomplete, the companion is part of the path that lets Conduish:

  • detect useful remote shell context
  • work with the remote session environment
  • support SSH autocomplete instead of treating the session like a blind text stream

Supported remote shells

Current remote generator execution support is limited to:

  • bash
  • zsh
  • fish

These are the shells that Conduish currently treats as supported for SSH generator execution.

Unsupported or partial remote shells

Some SSH shells are not treated as fully supported for generator execution. That includes:

  • generic POSIX sh-style shells
  • PowerShell
  • unknown shells

Unsupported shells are a current limit

When the detected remote shell falls outside the supported set, autocomplete may be partial or may not appear at all even though the SSH terminal itself still works.

What to expect

If SSH autocomplete is working, it should feel like a normal terminal feature inside the remote session.

If the companion cannot be installed, cannot be used, or the detected shell is outside the supported set, Conduish falls back to a reduced experience where the terminal still works but autocomplete support may be missing.

If you no longer want the companion on a remote host, follow how to uninstall.