Try free

Last updated 13 October 2026

Run Claude Code in a screen session

Connection drops interrupt the development flow

You are halfway through a complex refactor on a remote server. You have spent twenty minutes explaining the architecture to Claude Code. Then your internet connection flutters. Your SSH session hangs. When you finally reconnect, the interactive process is gone. You have to find your place again. This is the primary frustration of working with command line agents on remote infrastructure. The tool is powerful, but it relies on a stable terminal pipe to keep the conversation alive.

The problem is that the claude command runs as a child process of your shell. When the shell terminates because of a timeout or a dropped packet, it sends a hangup signal to everything it started. Claude Code stops immediately. While it saves its progress in the local project folder, the active context and the immediate loop of thought are interrupted. You need a way to keep the process running even when your physical computer is no longer talking to the server.

Using GNU Screen for basic persistence

GNU Screen is a terminal multiplexer that solves this problem by creating a virtual terminal session. You start it by typing screen into your command line. Inside this new session, you run claude just like you normally would. If your SSH connection drops, the screen process continues to run on the server. The agent keeps thinking, reading files, or writing code even if you are not there to watch it. This ensures that long running tasks are not killed by a bad Wi-Fi connection.

To leave a session running, you use the detach command sequence. Usually, this is Ctrl plus A, followed by D. This returns you to your main shell, but the virtual terminal stays active in the background. You can log out of the server entirely and go for lunch. When you come back, you type screen -r to reattach to the session. You will find the interface exactly where you left it, with the history intact and any finished tasks waiting for your review.

Managing Claude Code states with Screen

When you are inside a screen session, you can use the standard Claude Code controls. If you need to interrupt a long running task, you press Escape. If you want to check the current spend, you type /cost. Screen does not interfere with how the agent interacts with your files. It only provides a stable environment for the process to live in. If you have multiple projects, you can name your screen sessions. Use screen -S projectname to keep them organized and easy to find.

Sometimes a session might crash despite using screen. In those cases, Claude Code has built-in recovery. You can use claude --continue to pick up the most recent session in that specific folder. If you need an older session, use claude --resume to see a list of previous conversations. Screen gives you the uptime, and the native flags give you the data persistence. Together, they make a reliable developer environment for long running agent tasks.

Tmux for an organized terminal experience

Many developers prefer tmux over screen for its flexibility and better status bar. You start a new session by typing tmux. Inside, you navigate to your project directory and run the claude command. Tmux handles the terminal window as a persistent object on the server. To detach, you press Ctrl plus B, then D. This leaves the agent running in the background. It is a reliable way to ensure that your agent remains active across different network environments.

One benefit of tmux is the ability to split your window into panes. You can have claude running in one pane and a log viewer or a shell in another. This allows you to watch the agent use the Bash tool or Write tool in real time while you inspect the results elsewhere. To return to your work, you type tmux attach. If you have several sessions running, tmux ls shows them all, and tmux attach -t name brings you back to the specific project you need.

Handling terminal settings and context

Claude Code needs to know about your terminal environment to display colors and interactive elements correctly. Inside a tmux or screen session, you might need to run /terminal-setup if the display looks broken. This command helps the agent calibrate how it draws the interface. If you are using subagents through files in .claude/agents, the persistent session ensures that the main agent can wait for those subagents to finish their tasks without you being present.

The agent might use the Task tool to track its progress over a long period. In a persistent session, you can submit a complex prompt and then detach. The agent will continue to execute the plan. It will read files with the Read tool and propose edits with the Edit tool. When you reattach later, you can review the entire chain of thought. This turns Claude Code from a chat interface into a background worker that respects your project structure and .gitignore rules.

Visualizing multiple agent walls for better oversight

Running many sessions in tmux or screen can become difficult to track. You have to remember which session name belongs to which bug fix or feature. This is where a dedicated management tool like adhdTerminal becomes useful. It acts as a visual layer over your Claude Code sessions. Instead of typing commands to switch between tmux panes, you see each session as a tile on a wall. It allows you to monitor many concurrent threads without losing focus.

Each tile in adhdTerminal shows you the current status of the agent. You can see if a session is idle, working, or waiting for your permission. This is especially helpful when you have five or six different sessions running across different repositories. The app reopens your tiles in the same place after a restart, so you never lose track of your work. It provides a high level view that manual terminal multiplexing often lacks, making it easier to handle a heavy workload.

Permissions and unattended work in persistent sessions

When you leave Claude Code running in a persistent session, you must consider permission modes. By default, the agent asks for permission before it runs a tool or writes a file. If you are not there to click allow, the agent will wait. If you want it to work while you are away, you might use Shift plus Tab to cycle through permission modes. Moving to the bypassPermissions mode allows the agent to work through its task list without your constant input.

Be careful with this approach. Only use bypassPermissions in a safe environment or on a branch where you can easily revert changes. You can also configure specific tool permissions in the .claude/settings.json file. For example, you might allow the Read and Glob tools to run automatically but require manual approval for the Write or Bash tools. This balance lets you use screen or tmux to let the agent do the research while you are away, while still keeping control over the final code changes.

Remote synchronization and mobile monitoring

If you are working on a remote server, you might want to check on your agent from your phone. While tmux and screen are great for persistence, they are hard to use on a small touchscreen. adhdTerminal offers a free iPhone app that mirrors your tile wall. This allows you to see the progress of your persistent sessions through an end to end encrypted link. You can answer a quick prompt or send the next task to the agent while you are away from your desk.

This setup combines the stability of server-side persistence with the convenience of mobile monitoring. You keep the heavy lifting on the server within a tmux session, and use the adhdTerminal wall to stay informed. If the agent hits a roadblock or needs a quick clarification, you can provide it without needing to find a laptop and establish an SSH connection. This workflow keeps your development momentum high and reduces the friction of managing remote AI agents.

Cleaning up and managing session history

Eventually, a persistent session will reach its context limit. You can use the /cost command to see how much the current session has spent. If the conversation has become too long, use /compact. This command summarizes the history and frees up space in the context window. It allows the agent to keep working in the same screen or tmux session without becoming slow or losing focus on the current task.

When you are completely finished with a task, you can use /clear to start over in the same folder or Ctrl plus C to quit the process. If you want to keep a record of what happened, use /export to save the session history. Then you can safely close the tmux pane or kill the screen session. Managing your persistent sessions is just as important as starting them, as it keeps your server resources free and your project history clean.

Questions people ask

What happens if the server reboots while my screen session is running?

If the server reboots, the GNU Screen or tmux process will be killed along with Claude Code. However, you can return to the project directory and run claude --continue to pick up exactly where the agent left off. The session data is saved to your disk, so the only thing you lose is the live running process.

Can I use multiple panes in tmux to run different Claude Code sessions?

Yes, you can run a separate claude command in every tmux pane or window. Each one will maintain its own independent context and history within its respective directory. Just ensure you have enough system memory and API credits to support multiple concurrent agents working at once.

How do I stop an agent that is stuck in a loop inside a detached session?

You must first reattach to the session using screen -r or tmux attach. Once you can see the interface, press Escape to interrupt the current tool use. If the agent is completely unresponsive, you can use Ctrl plus C to kill the claude process entirely and then restart it with the resume flag.

Read next

More on when it goes wrong·All posts