Last updated 13 October 2026
Run Claude Code on a different port
Port conflicts stop the developer loop
When you run the claude command and see an error about an address already in use, your workflow breaks immediately. This usually happens because another process on your machine occupies the local network port that Claude Code needs to communicate with its internal components or local servers. You might be running a local web application, a database, or another development tool that claimed the same port number by default. This error is common in modern development environments where many tools rely on local network sockets to pass information between processes.
The interruption is frustrating because it often occurs right when you are ready to start a new task or resume an existing one. Claude Code relies on these connections to maintain its interactive interface and to coordinate with any subagents or tools it needs to run. If the port is blocked, the agent cannot establish the secure local bridge required to operate. You need to resolve this conflict before you can continue with your coding session or run any commands that require the full interactive environment.
Locate the process holding the port
You need to find out exactly which application is blocking the way. On macOS or Linux, you can use the lsof command to see which process is listening on a specific port. Run the command with the hyphen i flag followed by a colon and the port number mentioned in the error message. This command shows the process name and the process ID, which is often abbreviated as PID. Having the PID allows you to decide whether the blocking application is something you can safely stop or if you need to move your current project to a different configuration.
On a Windows machine, the netstat command is the standard tool for this task. You should run netstat with the flags hyphen a, hyphen n, and hyphen o to see all active connections and their associated process IDs. You can pipe this output into the findstr command to search for the specific port number. Once you identify the PID, you can open the Task Manager to see which application it belongs to. If the process is a leftover from a previous session that did not close correctly, terminating it will free the port and allow you to start the agent again.
Adjusting settings in the configuration files
Claude Code looks for its configuration in several specific JSON files. The primary place for project-specific settings is the .claude/settings.json file in your root directory. If you are experiencing persistent network issues, you should also check the global settings in your home directory under ~/.claude/settings.json. There is also a .claude/settings.local.json file for your own untracked overrides. These files control how the tool interacts with your local environment and can be used to manage permissions for various tools.
While you cannot always force the main agent to a specific port through a simple command flag, you can use the /config command inside a session to view your current setup. This command displays the active configuration and helps you understand which settings are currently in effect. If you find that a specific tool or subagent is consistently trying to use a blocked port, you might need to modify the settings.json file to change how that tool is invoked. Understanding the hierarchy of these configuration files ensures that your changes apply only where they are needed, whether that is for a single project or for every session on your computer.
Handling MCP server port collisions
The Model Context Protocol allows the agent to use external tools through local servers. These servers are managed via the claude mcp command and are defined in the .mcp.json file. Each MCP server typically runs as a separate process and often communicates over a network port. If you have multiple projects that use the same MCP server definitions, they might both try to claim the same port when the agent starts up. This lead to a conflict where one session works perfectly while the other fails with a network error.
To resolve this, you should check the .mcp.json file in your project root. This file contains the configuration for every server the agent can access. If a server requires a specific port, you may need to update its startup command or configuration to use a different one. You can use the /mcp command inside a session to check the status of your connected servers. If a server is listed as disconnected or failing, it is often due to a port conflict. Adjusting these values ensures that each project has its own dedicated communication channel, preventing one agent from interfering with another.
Using project instructions to avoid conflicts
The CLAUDE.md file is a powerful way to give the agent context about your local network environment. You should create a CLAUDE.md file in the root of your repository to list every port your application uses. For example, specify that your development server runs on port 3000 and your database runs on port 5432. The agent uses the Read tool to parse this file at the start of a session. When the agent knows which ports are already reserved for your application, it is less likely to suggest commands or run tests that would cause a conflict.
You can also place CLAUDE.md files in subdirectories if different parts of your project use different network resources. The agent respects the instructions in the directory where it is currently working. If you are working on a microservices project, this hierarchical approach is very effective. By documenting your port usage in plain text within these markdown files, you provide a clear roadmap for the agent. This prevents the agent from accidentally trying to use a port that your system needs for background tasks or other critical services.
Managing many sessions simultaneously
Running multiple instances of Claude Code across different projects can lead to a cluttered terminal where you lose track of which session is using which network resource. The adhdTerminal app provides a native solution for macOS and Windows that organizes these sessions into a wall of tiles. Each tile represents a separate session with its own name, color, and number. You can see at a glance if a session is working, waiting for you, or idle. This visual organization makes it much easier to manage multiple projects without getting confused by overlapping windows or hidden port conflicts.
The app also includes a free iPhone companion that mirrors your wall over an end to end encrypted link. This allows you to monitor the progress of long running tasks or answer a prompt from your phone while you are away from your desk. Since adhdTerminal keeps your sessions organized and persists them through restarts, you do not have to worry about manually re-running the claude --resume command for every project every time you reboot. It manages the underlying terminal sessions for you, providing a stable environment where you can focus on writing code instead of managing window tabs.
Cleaning up after a session crash
Sometimes a session ends abruptly because of a system crash or because you used Ctrl+C to quit. In these cases, the agent might leave behind orphaned processes that continue to hold network ports open. If you try to start a new session in the same folder and get a port error, it is likely that the previous process is still running in the background. You should use the claude doctor command to diagnose the health of your installation. This command checks for common environment issues and can help identify if something is preventing the agent from starting correctly.
If you are already inside a session and things seem sluggish, the /status command gives you a snapshot of the current agent state. If you find that a port is truly stuck and the doctor command cannot fix it, you will need to use the PID you found earlier to manually kill the process. Once the old process is gone, the port is freed for the new session. Regularly updating the tool with the claude update command also ensures you have the latest fixes for process management and network handling, which can reduce the frequency of these hanging processes.
Verifying network permissions and hooks
Claude Code uses a permission system to control what it can do on your machine. These permissions are stored in your settings.json file under the permissions key. You can cycle through different modes like default, plan, and acceptEdits by pressing Shift+Tab. In acceptEdits mode, the agent has more freedom to run tools like Bash, which might include starting servers that use network ports. If you are troubleshooting a conflict, check your permissions to ensure the agent is not trying to perform network actions that you have restricted.
The agent also supports various hook events like SessionStart and PreToolUse. If you have custom hooks configured in your settings, they might be executing commands that claim ports before the main agent is ready. You can use the /hooks command to see which hooks are currently active. If a port conflict happens every time you start a new session, a startup hook is a likely culprit. Reviewing these settings ensures that your automated workflows are not tripping over the network requirements of the agent itself.
Resuming work after a resolution
Once you have cleared the port or updated your configuration, you can return to your work. Use the claude --continue command to carry on with the most recent session in your current folder. If you had to close several windows to find the port conflict, the claude --resume command offers a list of earlier sessions so you can pick exactly where you left off. This saves you from having to repeat your initial prompts or explain the project context to the agent again.
If your session history is full of error messages from your troubleshooting efforts, the /compact command is very useful. It summarizes the conversation so far, which frees up space in the context window and removes the noise of the network errors. If you want a completely fresh start while staying in the same project folder, use the /clear command. This wipes the current conversation but keeps you in the interactive environment. These commands help you maintain a clean and focused workspace once the technical hurdles of port management are behind you.
Questions people ask
Can I specify a custom port when I run the claude command?
The current version of the tool does not provide a direct flag like hyphen hyphen port to set a specific network port for the main agent. It manages its own internal networking automatically. To avoid conflicts, you should ensure that other common development ports are free or documented in your CLAUDE.md file.
What is the difference between /clear and /compact when fixing errors?
The /clear command removes the entire conversation history from the current session so you can start fresh without previous context. The /compact command creates a summary of the conversation to save space in the context window. Use /compact if you want the agent to remember the port fix you just applied, and use /clear if you want to move on to a completely different task.
Does Claude Code work with VPNs or proxies that might block ports?
Yes, but you may need to configure your environment variables for the tool to communicate through a proxy. The claude doctor command is the best way to check if your network environment is blocking the agent's ability to reach its servers. If a VPN is active, it might change how local ports are addressed, so verify your settings if you see connection errors.
Read next
- Access git submodules in Claude CodeFix issues where Claude Code cannot see or modify code located inside nested git submodules within your main repository.
- Allow Claude Code to run shell scriptsResolve tool execution errors by adjusting permission settings to let Claude Code execute local bash or powershell scripts in your terminal.
- Break a linter error loop in ClaudeWhat to do when Claude Code fixes one linting error only to create another, leading to a circular set of edits.
- Change the Node version for Claude CodeResolve compatibility issues by switching the Node.js version used by Claude Code without breaking your other local development tools.