Try free

Last updated 13 October 2026

Give Claude Code sudo permissions

The challenge of system level permissions

When you use Claude Code to manage a server or configure a local development environment, you will eventually need to run commands with administrative privileges. The agent uses the Bash tool to execute shell commands. This tool operates with the permissions of the user who started the terminal session. If you try to run a command like installing a system package or editing a protected file in the etc directory, the command will fail with a permission denied error. The agent might try to use sudo automatically, but it cannot handle the interactive password prompt that follows. This creates a loop where the agent repeatedly fails to execute the necessary task.

This happens because the terminal environment does not allow the agent to see or type into the password prompt that sudo generates in the background. The Bash tool captures the standard output and error, but the password prompt often bypasses these or waits indefinitely for input that never comes. You might see the agent hang or report that a command timed out. This is a common point of frustration for developers who want to use the agent for full stack deployment or system level configuration. To solve this, you must bridge the gap between the agent need for root access and the security requirements of your operating system.

Configuring passwordless sudo for specific tools

The most effective way to grant access is to modify your sudoers file. This tells your operating system that your user can run specific binaries without a password. Open your terminal and run the command sudo visudo to open the configuration file. Do not edit this file with a regular text editor because a syntax error can lock you out of administrative access. At the bottom of the file, add a line that specifies your username and the full path to the tools you want the agent to use. For example, if you want to allow the agent to use the apt package manager on a Linux system, you would add a line that includes the NOPASSWD tag followed by the path to the apt-get binary.

You can find the full path of any command by typing which followed by the command name in your shell. If you are on macOS and use Homebrew, you might add a line for the brew binary. By restricting this privilege to specific files, you maintain a higher level of security than if you gave the agent full root access to every command. This setup allows the Bash tool to execute these specific commands immediately. The agent will no longer hit a wall when it tries to install dependencies or restart a system service. This is the foundation for a smooth workflow when doing system administration with an agent.

Defining administrative scope in the project instructions

Once the operating system is ready, you must inform the agent about its new capabilities. Use the CLAUDE.md file in your project root for this purpose. This file holds project instructions and is the first place the agent looks for guidance. Create a section titled System Administration or Permissions. In this section, clearly state that the agent has passwordless sudo access for specific commands. List the commands exactly as you configured them in the sudoers file. This prevents the agent from guessing which commands require sudo and which do not.

Tell the agent to prefix installation or system modification commands with sudo and to not expect a password prompt. You should also instruct it on how to verify that a command worked. For example, tell it to check the status of a service after restarting it. If you are working in a specific part of a large repository, you can put a CLAUDE.md file in a subdirectory. This allows you to define different administrative rules for different parts of your project. The agent will follow the instructions in the closest CLAUDE.md file to its current working directory.

Managing tool behavior through permission modes

Claude Code offers different permission modes that change how it interacts with your system. You can cycle through these modes by pressing Shift+Tab inside an active session. The modes are default, acceptEdits, plan, and bypassPermissions. When you are performing risky system changes, it is wise to stay in the default or acceptEdits mode. In these modes, the agent must ask for your permission before it runs any tool. This gives you a final chance to review the sudo command and the specific arguments the agent is using before any changes happen to your system.

If you are confident in your setup and have a long list of routine administrative tasks, you can switch to bypassPermissions. This mode allows the agent to run tools without stopping for your approval. This is useful for automated environment setup or bulk configuration changes. However, you should use this mode with caution. Always review the plan the agent creates before you let it run autonomously. You can use the /permissions slash command to view or change how the agent handles tool execution in your current session. This ensures you have the right balance of speed and safety.

Using local settings for environment specific rules

You might not want to commit your sudo instructions to a shared repository where other developers might have different setups. In this case, use the .claude/settings.local.json file. This file is intended for your own untracked overrides. You can specify permissions and tool behaviors that only apply to your local machine. If you want these rules to apply to every project you work on, you can place your settings in the ~/.claude/settings.json file in your home directory. This global configuration is useful for defining how the agent should handle sudo across all your development work.

The agent respects the hierarchy of these settings files. It checks the project local settings first, then your user level settings. This allows you to have a standard way of working with administrative tasks while still allowing for project specific deviations. For example, you might allow the agent to use sudo for docker commands globally, but restrict it to only read operations in a sensitive production repository. You can use the /config command at any time to see which settings are currently active and where they are being loaded from.

Scaling system administration with adhdTerminal

System administration often involves waiting for long processes like system updates, large package installations, or complex builds. Managing several of these tasks in different terminal windows can become confusing. This is where adhdTerminal helps. It lets you run many Claude Code sessions side by side as tiles on a wall. Each tile has a colour, a number, and a name. You can see at a glance whether an administrative task in one tile is still working, waiting for your permission, or finished. This layout makes it easy to monitor multiple servers or environments without losing context.

A tile in adhdTerminal also shows the last exchanges of its conversation and any headlines the project publishes. This means you do not have to click into every window to see if a sudo command failed or succeeded. If you need to step away from your computer during a long system upgrade, the free iPhone app mirrors your wall over an end to end encrypted link. You can check the status of your administrative tiles from your phone and even send the next task or answer a prompt. This keeps your system work moving even when you are not at your desk.

Verifying the environment with diagnostic tools

If the agent still struggles to run administrative commands, you can use built in diagnostic tools to find the cause. Run the claude doctor command from your shell or use the /doctor slash command inside a session. These commands check the health of your installation and your environment variables. They can identify if the agent is having trouble accessing the Bash tool or if there are issues with your path configuration. Checking the output of /doctor is often the fastest way to see why a sudo command is being rejected by the system.

Pay close attention to the error messages returned by the Bash tool when a command fails. If you see a message stating that a tty is required to run sudo, it means your operating system security policy is blocking non interactive sudo sessions. You can usually fix this by adding a specific flag to your sudoers file for your user. Adding the !requiretty flag for your username allows the agent to run sudo commands without a traditional terminal interface. This is a common requirement on some Linux distributions like Red Hat or CentOS.

Limiting the blast radius of root access

Giving an agent any form of root access requires a careful approach to security. You should never give the agent full, unrestricted passwordless sudo access to every command on your system. Instead, only grant the NOPASSWD privilege to the specific binaries the agent needs to perform its job. If the agent only needs to manage web services, only allow it to run the commands for starting and stopping those services. You can use the /permissions command to see which tools the agent is allowed to use and adjust your settings.json to restrict the Bash tool if necessary.

You should also avoid putting sensitive information like passwords or API keys directly into your CLAUDE.md or settings files. If a command requires a secret, use environment variables that the agent can read but not modify. Regularly review the session history by pressing Escape twice to see what the agent has done. This allows you to verify that it is following your instructions and not attempting to run unauthorized commands. By combining specific sudoers rules with the permission modes in the agent, you can maintain a secure environment while still benefiting from automated system administration.

Continuing and summarizing complex system tasks

When you complete a complex system configuration, the conversation history can become very long. This consumes the context window and can make the agent less efficient. Use the /compact command to summarize the session. This frees up space while ensuring the agent remembers the administrative steps it has already taken. If you need to stop your work and return to it later, you can use the claude --continue command to resume the most recent session in that folder. The agent will pick up exactly where it left off with all the system context intact.

If you have many different administrative sessions for different projects, use the claude --resume command to see a list of earlier sessions and pick the one you need. In adhdTerminal, your tiles reopen in the same place after a restart and automatically resume the same session. This persistence is vital for long term system maintenance where you might need to check back on a server configuration weeks after the initial setup. Whether you are using a single terminal or a wall of tiles, keeping your administrative sessions organized ensures that your system remains stable and well documented.

Questions people ask

How do I stop a sudo command that is running too long?

Press the Escape key to interrupt what the agent is doing. If you need to revert to a previous state because a command caused an issue, press Escape twice to see your message history and select an earlier point to resume from.

Can I use MCP servers to handle administrative tasks?

Yes, you can manage MCP servers with the 'claude mcp' command or the /mcp slash command. If an MCP server needs to run commands as root, you must configure the underlying system permissions for that server just as you would for the Bash tool.

How can I see how much my system administration tasks are costing?

Use the /cost or /usage commands inside your session to see the financial cost and token usage. This is helpful for tracking the spend on complex tasks that involve reading many system files and running multiple commands.

Read next

More on claude code basics·All posts