Try free

Last updated 13 October 2026

Use Claude Code via SSH connections

Maintain context over fragile connections

Working on a remote server through SSH often means dealing with latency and unexpected disconnections. When you run Claude Code directly in a standard SSH shell, a network hiccup can kill the terminal process and leave the agent in an undefined state. This is frustrating because you lose the immediate interactive history and have to reconnect to figure out if the last tool execution finished. You need a way to keep the process running on the server regardless of your local machine's connection state.

Claude Code performs intensive tasks like Bash, Read, and Write operations that take time to complete. If your SSH session drops while the agent is midway through a multi-step Edit operation, you might end up with corrupted files or partial changes. A stable environment is not just a convenience; it is a requirement for maintaining the integrity of your codebase when an autonomous agent is making changes. You must ensure that the shell persists even when the transport layer fails.

Use terminal multiplexers for persistence

The most reliable way to run the claude command on a remote host is inside a terminal multiplexer like tmux or screen. These tools allow you to start a session, detach from it, and reattach later from a different connection. If your SSH client closes, the multiplexer keeps the Claude Code process alive on the server. You can return to your work by reattaching to the session and find the agent exactly where you left it, whether it is waiting for your input or still processing a task.

Inside a tmux session, you can run claude to start a new interaction. If you lose your connection, simply log back into the server via SSH and use the command to list and attach to your existing sessions. This ensures that the context window and the current state of the conversation remain intact. It also prevents the agent from being interrupted during a critical Write or Edit tool call, which could otherwise require manual cleanup of the file system.

Configure environment variables and settings

Your remote environment needs specific configuration to handle the agent efficiently. Ensure your shell environment correctly exports the necessary API keys and paths so the claude command works without manual intervention every time. You can check the health of your installation by running claude doctor on the remote machine. This command verifies that the environment is ready and that the agent can access the tools it needs to function correctly without permission errors.

Project specific settings should be placed in .claude/settings.json within the root of your repository on the server. You can also use .claude/settings.local.json for configurations that you do not want to commit to version control, such as specific user preferences or local paths. If you have instructions that should apply to every project on that server, place them in ~/.claude/CLAUDE.md. The agent reads these files to understand the rules and standards of your remote development environment before it starts working.

Control tool execution and permissions

When working remotely, you might want more or less oversight depending on the task. Use Shift+Tab to cycle through permission modes like default, acceptEdits, plan, and bypassPermissions. In the plan mode, the agent will describe what it intends to do without executing the tools, which is useful for verifying complex changes over a slow connection. If you are confident in the environment, bypassPermissions allows the agent to run tools like Bash and Edit without asking for confirmation every time.

You can refine these permissions in your .claude/settings.json file under the permissions key. This allows you to allow or deny specific tools globally or per project. For example, you might want to allow Read and Glob tools automatically but require manual approval for Write or Bash commands. This granular control is vital when you are managing the session through a remote interface where continuous clicking of approval buttons can be sluggish.

Manage context and session history

Remote sessions can grow large and consume significant memory or tokens. Use the /compact command to summarize the conversation so far and free up space in the context window. This is especially helpful during long SSH sessions where you have performed many iterations. If the conversation becomes too cluttered or the agent seems confused by old information, use /clear to start fresh in the same folder without losing your configuration or tool history.

To pick up where you left off after a planned disconnect, use claude --continue or claude -c to resume the most recent session in your current directory. If you need to switch between different tasks you were working on earlier, claude --resume or claude -r will provide a list of previous sessions to choose from. This history is stored on the server, so you can access it from any computer you use to SSH into that host, maintaining a continuous workflow across different machines.

Optimize repository access for the agent

Claude Code respects your .gitignore file, which is crucial when working on remote servers that might contain build artifacts or large datasets. Ensure your .gitignore is up to date to prevent the agent from wasting time and tokens reading unnecessary files. You can further guide the agent by creating a CLAUDE.md file in the root of your remote repository. This file should contain project specific instructions, build commands, and coding standards to improve the agent's accuracy.

If the project is large, the agent uses the Glob and Grep tools to find relevant files. You can help it by providing clear entry points in your CLAUDE.md. If you are working on a specific subdirectory, you can place a secondary CLAUDE.md there to provide localized context. This hierarchy ensures the agent spends less time searching and more time executing the Task or Edit operations you requested, which reduces the total data transmitted over your SSH connection.

Monitor costs and performance remotely

Running an agent on a remote server can lead to unexpected resource usage if not monitored. Use the /cost command frequently to see the financial impact of your current session. The /usage command provides more detail on how many tokens have been consumed and how many are remaining in your current limits. Keeping an eye on these numbers ensures that a long running remote task does not exceed your budget while you are away from the terminal.

If the agent becomes unresponsive or hangs during a tool execution, use the Escape key to interrupt it. Pressing Escape twice will show you a list of earlier messages, allowing you to jump back to a previous state in the conversation. This is a powerful way to recover from errors without having to restart the entire session. If you need to exit the session entirely and return to your server shell, use Ctrl+C to quit the claude process safely.

Visualize multiple remote sessions

Managing several SSH connections to different servers can become overwhelming. This is where adhdTerminal becomes a useful addition to your workflow. adhdTerminal is a native app for macOS and Windows, made by MINDBALANCER OU in Estonia, not affiliated with Anthropic. It runs many Claude Code sessions side by side, each one a tile on a wall. A tile has a colour, a number and a name, shows whether it is working, waiting for you, done or idle, shows the last exchanges of its conversation, and can show numbers and headlines the project publishes.

Tiles reopen in the same place after a restart and resume the same session, which provides a stable dashboard for your remote work. A free iPhone app mirrors the wall over an end to end encrypted link and can answer a prompt or send the next task. This is particularly helpful when you are running a long Task on a remote server and need to check its progress away from your computer. The software costs 99 dollars once, and one key runs one computer at a time and can be moved. There is a 7 day free trial and no account is required.

Advanced remote integration and hooks

For complex workflows, you can utilize hook events like SessionStart or PostToolUse to trigger external scripts on your server. These hooks allow you to integrate Claude Code with your existing remote CI/CD pipelines or notification systems. Custom slash commands can also be defined as markdown files in the .claude/commands directory, giving you the ability to create server specific shortcuts for common tasks that the agent can execute on your behalf.

If you need the agent to interact with external services or databases from the remote host, use claude mcp to manage MCP servers. This allows you to extend the capabilities of the agent with specialized tools designed for your server environment. You can configure these servers in the .mcp.json file. By combining these advanced features with a persistent SSH setup, you turn your remote server into a highly capable development environment that maintains its state regardless of your local connection.

Questions people ask

How do I update Claude Code on a remote server?

Run the claude update command directly in your remote terminal. This ensures you have the latest improvements and tool fixes from Anthropic. You should also run claude doctor afterward to verify that the update did not disrupt your environment settings or tool permissions.

Can I use specific editors like Vim through the agent remotely?

Yes, you can use the /vim slash command to open a Vim interface within the agent session. This allows you to manually edit files alongside the agent without needing a second SSH connection. If you prefer your local editor, the /ide command can help configure that bridge, although it depends on your specific SSH port forwarding setup.

What happens if the server restarts while a session is active?

The active session will be terminated, but the history is saved to the local disk of the server. Once the server is back online, you can log in and use claude --continue to pick up exactly where you left off. The agent will read the previous conversation state and be ready to continue the task.

Read next

More on when it goes wrong·All posts