Last updated 13 October 2026
Fix Claude Code not a tty error
The terminal allocation error indicates a missing interactive shell
You encounter a not a tty error when the environment cannot provide a functional pseudo-terminal for the command you are running. This often happens when you try to run the claude command inside a script, a pipe, or a continuous integration environment. The agent is designed to render an interactive dashboard that requires a terminal capable of processing text input and output in a specific way. When it detects that it is being run as a background process or redirected into a file, it stops and reports that a TTY is not available.
This error is common for developers who use complex shell setups or terminal multiplexers that do not correctly pass the terminal characteristics to sub-processes. If you are using a wrapper or a specific terminal emulator that is not fully compatible with interactive CLI tools, the agent cannot draw its interface. You might see this message if you try to use the agent through a remote execution tool that does not allocate a terminal by default. To fix this, you must either provide a real terminal environment or use a mode that does not require one.
Claude Code requires a pseudo terminal for interactive features
The agent uses the terminal to handle real-time feedback and complex key bindings like Shift+Tab to cycle through permission modes. It also uses the terminal to capture the Escape key for interrupting long-running tasks. If the shell does not provide a TTY, these interactive features cannot function. This is why the standard command fails when it cannot verify that a human is at the other end of the input stream. The agent needs to know it can safely prompt you for permissions or show you the progress of tools like Bash and Edit.
When you run the agent, it initializes a session that maintains context about your files and conversation. This session expects to be the primary focus of the terminal window. If you are nesting shells or using a terminal inside an IDE that has limited capabilities, you might hit this error. You can try to force terminal allocation in your shell settings or move to a native terminal app that supports full interactive features. Native environments are generally more reliable for tools that perform heavy file manipulation and command execution.
Single prompts work in scripts without a terminal
If your goal is to automate a task without human intervention, you should use the claude -p flag. This command runs a single prompt and prints the answer directly to the standard output without launching the interactive interface. Because it does not try to render the dashboard, it does not require a TTY. This is the correct way to use the agent in a cron job, a deployment script, or a CI/CD pipeline where no interactive terminal exists. It allows you to leverage tools like Read or Glob to gather information and output the results as plain text.
Using the -p flag changes how the agent handles permissions. Since you cannot interact with the agent to approve every step, you must ensure your project settings allow the necessary actions. You can configure these in your .claude/settings.json file. For example, if you want the agent to be able to use the Write tool without a terminal, you may need to adjust the permissions key for that project. This allows the agent to finish its task and exit without waiting for a user who is not there.
Configuration files define how the agent behaves
The behavior of the agent is guided by several configuration files located in your project and home directory. The CLAUDE.md file in your repository root holds the primary instructions for the agent. If you have a specific way you want the agent to handle terminal errors or specific tools, you should document it there. You can also place a CLAUDE.md file in a subdirectory if you want different rules for different parts of your code. There is also a global instructions file at ~/.claude/CLAUDE.md that applies to every session you start on your machine.
Settings for the agent itself live in .claude/settings.json within your project or in your home directory. These files control everything from which tools are allowed to run to how the agent handles session data. If you are frequently hitting environment errors, check your settings.local.json file for any overrides that might be causing issues. This file is intended for your own untracked local settings and is a good place to put configurations that are specific to your terminal environment. By managing these files, you ensure the agent knows exactly how to interact with your system.
Diagnostic commands help identify environment issues
If you are unsure why your terminal is failing, you can run the claude doctor command. This utility checks your installation and verifies that your environment meets the requirements for an interactive session. It will look for issues with your path, your permissions, and your connection to the necessary services. This is the first step you should take when the agent behaves unexpectedly or fails to start. It provides a clear report on what might be missing from your shell configuration.
Inside an active session, you can use the /terminal-setup command to inspect your current terminal configuration. This command helps you understand if your shell supports the features the agent needs to display its interface correctly. If you find that your terminal is garbled or not responding to keys like Ctrl+R, this diagnostic tool can point to the cause. You should also make sure you are running the latest version by using the claude update command, as improvements to terminal handling are frequently added to the software.
Permission modes change the need for user input
The agent has four distinct permission modes: default, acceptEdits, plan, and bypassPermissions. You can cycle through these modes by pressing Shift+Tab in an interactive session. The mode you choose determines how often the agent asks for your approval before using a tool like Bash or Write. If you are in a limited terminal environment where input is difficult, switching to a mode like acceptEdits can reduce the number of times you need to interact with the TTY. This makes the session flow better when the terminal is not perfectly responsive.
The bypassPermissions mode is particularly powerful because it allows the agent to run tools without any manual confirmation. This should be used with caution, but it is often necessary when running complex automated tasks. You can set these modes globally or per project in your settings.json file. If you are experiencing TTY errors because the agent is waiting for an input that your terminal cannot send, adjusting these permissions can sometimes bypass the bottleneck. Always ensure your CLAUDE.md file has clear rules to guide the agent when it is running in these more autonomous modes.
Session management allows recovery from terminal crashes
If your terminal session closes unexpectedly due to a TTY error, your work is not lost. You can use the claude --continue command to jump back into the most recent session in your current folder. This is helpful if your shell environment is unstable and you need to restart frequently. If you need to pick from a list of older conversations, use the claude --resume command. This allows you to select a specific session and pick up exactly where you left off, preserving the context window and the history of the conversation.
adhdTerminal is a native app for macOS and Windows that helps manage these sessions effectively. It runs many Claude Code sessions side by side as tiles on a wall. Each tile has a color, a number, and a name, and it shows you the last exchanges of the conversation. This app manages the terminal allocation for each session, which prevents many of the TTY errors that occur in standard shell wrappers. Tiles reopen in the same place after a restart and resume the same session, providing a stable environment for developers who need to keep multiple agents running at once.
Mobile mirroring provides a way to interact remotely
When you are away from your main computer, you can still manage your sessions through a free iPhone app. This app mirrors your wall of tiles over an end to end encrypted link, so you can see if an agent is working, waiting for you, or done. You can use the app to answer a prompt or send the next task to any of your active sessions. This is a great way to keep a long-running task moving without needing to be at your desk or in a terminal session. It bypasses local TTY issues on your mobile device because the agent continues to run on your primary machine.
The system costs 99 dollars once and a single key runs one computer at a time. This key can be moved between machines if you change your primary workstation. There is a 7 day free trial available so you can test how the app handles your specific terminal needs without an account. Using a native app like adhdTerminal ensures that your terminal environment is consistent and that you have a reliable way to monitor your agents. It provides the visual feedback you need to stay productive across multiple projects.
Questions people ask
What should I do if the Escape key does not work in my terminal?
If your terminal does not pass the Escape key correctly, you may not be able to interrupt the agent. Try running the /terminal-setup command to see if your terminal is compatible. You can also use Ctrl+C to quit the session and then use claude --continue to return to it once you have fixed your terminal settings.
How can I run a prompt from a shell script without hitting a TTY error?
Use the claude -p flag followed by your prompt in quotes. This runs the command in a non-interactive mode that does not require a pseudo-terminal. You should also check your .claude/settings.json to ensure that the tools the agent needs to use have the correct permissions for non-interactive execution.
Can I use MCP servers in a non-interactive environment?
Yes, you can manage MCP servers with the claude mcp command even in environments with limited terminal support. If you are using the -p flag, the agent can still access the tools provided by your MCP servers as long as they are configured in your .mcp.json file. Ensure your project instructions in CLAUDE.md tell the agent how to use these tools effectively.
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.