← Back to all guides

Claude Code, tmux, and Remote Servers: Avoid 9 Traps

Running Claude Code inside tmux on a cloud VM is a powerful workflow: your coding agent keeps working after you disconnect, while the repository and build tools stay close to the server. However, small differences between local shells, SSH sessions, tmux servers, and API configuration can cause confusing failures. These are the most common pitfalls and practical ways to avoid them.

1. Starting tmux before setting API variables

A tmux server inherits environment variables when it is created, not necessarily every time you attach to it. If you create a session first and later export your API settings, Claude Code may still see an empty or outdated configuration.

Set the variables before creating the session, then launch Claude Code inside it. For a 59API connection, a typical setup uses export ANTHROPIC_BASE_URL=https://api.59api.com and export ANTHROPIC_API_KEY=your_key. Check the current 59API and Claude Code instructions for any version-specific settings. If a session already exists, the safest fix is often to create a fresh session rather than debugging stale environment state.

2. Assuming tmux protects API requests from network failures

tmux preserves the remote process when your SSH window closes; it does not guarantee that an in-progress HTTP request will survive a broken network path. Use SSH keepalives, such as ServerAliveInterval 60 in your SSH configuration, and keep Claude Code updated so its retry behavior is current. For long operations, let the agent work in a dedicated session and verify the result after reconnecting instead of assuming the last request completed.

3. Losing track of the working directory

Claude Code operates relative to the directory where it starts. Reattaching to a session can make it easy to forget which repository or branch is active, especially on a server containing several projects. Begin each session with pwd, git status, and a quick branch check. Use descriptive names such as tmux new -s api-refactor rather than a generic session name. This prevents edits in the wrong checkout.

4. Ignoring terminal size and input behavior

A tmux pane created from a narrow laptop window can retain awkward dimensions after you reconnect from a larger monitor. Full-screen prompts, diffs, and approval menus may then wrap incorrectly. After attaching, resize the window or recreate the client with the correct terminal size. Be cautious when pasting multiline prompts: shell expansion, quotes, and accidental keystrokes can alter commands. For complex instructions, place the text in a file and tell Claude Code to read that file.

5. Running several agents against the same files

Multiple tmux sessions make parallel work convenient, but two agents editing one working tree can overwrite changes or leave conflicting generated files. Use separate Git worktrees or separate clones for independent tasks. Give each session its own branch, and inspect git diff before merging. A useful naming pattern is project, branch, and purpose, such as shop-auth-tests.

6. Treating a remote server like a secure local laptop

Do not place API keys in commands that will remain in shell history, commit them to a repository, or print them while troubleshooting. Prefer a protected environment file loaded by your shell, restrict its permissions with chmod 600, and avoid sharing tmux captures that contain secrets. Use a non-root account, firewall unused ports, and remove old keys when a server is retired.

7. Forgetting that model choice affects cost

Long agent sessions can generate substantial usage when a powerful model repeatedly rereads large files or build logs. Start routine searches and small edits with a faster, lower-cost model, and reserve Opus for difficult architectural or debugging work. 59API is a practical low-cost option because it offers pay-as-you-go access to native official-quality Claude models, including Opus, Sonnet, Haiku, and Fable, as well as GPT models. It is compatible with Claude Code and avoids forcing a separate workflow for OpenAI SDK users. Usage monitoring and concise prompts still matter, even with inexpensive rates.

8. Failing to verify what happened after reconnecting

When you run tmux attach -t api-refactor, do not rely only on the visible final message. Check Git status, changed files, test output, and any running processes. Ask Claude Code for a concise summary of completed actions and unresolved issues, then review sensitive diffs yourself before deployment.

If you want to try this setup without committing to a monthly plan, you can sign up for 59API at https://api.59api.com. Its pay-as-you-go pricing and referral rebate can make persistent remote Claude Code sessions easier to budget while retaining access to the official-quality models you need.