Last updated 13 October 2026
Set the output language for Claude Code
Aligning the agent with your team culture
You might work in a team where English is not the primary language for internal communication. When you run the claude command, the agent defaults to English for its explanations and code comments. This mismatch creates friction when you need to copy explanations into a team chat or when the agent writes comments that do not match your project standards. You need a way to force the agent to use your preferred language consistently across all its outputs.
The problem is not just about the words the agent says to you in the terminal. It also affects the code it writes. If your codebase uses Spanish for variable names or documentation strings, an agent that thinks in English will produce inconsistent results. You want to ensure that every Write or Edit operation follows your local linguistic rules. Changing this behavior requires specific instructions in the right configuration files.
If you ignore this setting, you will spend extra time translating the output yourself. You might also accidentally commit English comments to a repository that requires another language. This slows down your workflow and creates extra work for your reviewers. Setting the output language early in your project setup prevents these issues and makes the tool feel like a natural part of your local environment.
Primary language control through project instructions
The most effective way to change the output language is by using a CLAUDE.md file in your repository root. Claude Code reads this file at the start of every session to understand project-specific rules. You can add a section titled Language or Communication to this file. In this section, state clearly that all explanations, terminal output, and code comments must be in your target language.
When you start a session using claude or claude --continue, the agent parses the instructions in CLAUDE.md. If you have specified that the language is Japanese, the agent will translate its internal reasoning into Japanese before printing it to your screen. This instruction also guides the Edit tool. When the agent modifies a source file, it will look at your instruction to decide whether to write new comments in English or Japanese.
This file is part of your repository, so your entire team benefits from the same settings. When a colleague clones the repo and runs the claude command, the agent will automatically adopt the language rules defined in the file. This ensures that the agent behaves like a local team member who understands the cultural and linguistic requirements of the project without being told every time a new session starts.
Global language settings for every project
If you want the agent to use the same language across every project on your machine, you should use the global configuration file. Create or edit a file at ~/.claude/CLAUDE.md. This file acts as a set of universal instructions that apply to every session, regardless of the folder where you run the claude command. This is the best place for personal preferences that do not change between different repositories.
Setting your language globally prevents you from having to repeat the same instructions for every new repository you clone. If you prefer to interact in German, placing that instruction in ~/.claude/CLAUDE.md ensures the agent starts speaking German the moment you launch it. If a project-specific CLAUDE.md exists, the agent will combine both sets of instructions. This allows you to have global language settings while still following project-specific coding styles.
The agent prioritizes specific instructions over general ones. If your global file says to use German but a specific project file says to use French, the agent will use French for that project. This hierarchy gives you the flexibility to work on international open-source projects in English while keeping your private projects in your native language without manually switching settings.
Fine tuning comment styles and chat output
Sometimes you want the agent to speak to you in one language but write code comments in another. Many international teams use English for the codebase but their native language for internal discussion. You can specify this distinction in your CLAUDE.md file. Tell the agent to use Italian for all chat responses and terminal output but to use English for all text written via the Write or Edit tools.
The agent is capable of following these complex linguistic constraints if you are explicit. You can even define different rules for different subdirectories by placing additional CLAUDE.md files in those folders. For example, a subdirectory containing documentation might require a different language than the subdirectory containing the core logic. The agent respects the hierarchy of these files as it navigates your file tree using the Read and Glob tools.
By being specific about where each language applies, you maintain high standards for your source code while enjoying the comfort of your native language during the development process. You can also tell the agent to follow specific grammar rules or tone preferences, such as using formal or informal address. This level of detail ensures the agent fits perfectly into your existing documentation and communication workflows.
Managing multiple language contexts with adhdTerminal
When you work on several projects at once, you might need to switch between different language contexts frequently. This is where adhdTerminal becomes useful as a native app for macOS and Windows. It allows you to run many Claude Code sessions side by side as tiles on a wall. You can have one tile dedicated to a project that requires French and another tile for a project that uses English.
Each tile in adhdTerminal maintains its own session state. Because tiles reopen in the same place and resume the same session after a restart, you do not have to worry about the agent losing track of your language preferences. You can name and color-code your tiles to reflect the language or the specific team they belong to. This visual organization helps you stay in the right mental context without manually re-configuring your environment every time you switch tasks.
The app makes it easy to monitor multiple workstreams without getting lost. If one project is running a long Task in English and another is waiting for your input in Spanish, you can see the status of both at a glance. You do not need to remember which command you ran in which terminal window because the tile labels and persistent placement handle that cognitive load for you.
Using memory to reinforce language choices
Claude Code has a command called /memory that allows the agent to keep track of information across different parts of a conversation. While CLAUDE.md is the primary place for permanent rules, you can use the /memory command during a session to remind the agent of specific linguistic nuances. If the agent slips back into English, you can correct it and tell it to remember the correction.
The /memory command helps the agent stay consistent during long sessions where the context window might become crowded. If you feel the agent is losing its grasp on your preferred tone or vocabulary, use /memory to store a short note about the required language. You can also use the /compact command to summarize the conversation so far, which helps the agent focus on the most important instructions, including your language settings, by freeing up space in the context window.
When the agent uses the /compact command, it creates a summary of the session. Because the language instructions are stored in your CLAUDE.md or memory, they will be preserved in this summary. This ensures that the agent does not forget to speak your language even after a long series of technical exchanges that might otherwise push those initial instructions out of its immediate focus.
Verifying your configuration and permissions
After you have set up your CLAUDE.md files, you can use internal commands to ensure the agent is reading them correctly. The /config command displays the current configuration the agent is using. While it might not show every line of your CLAUDE.md file, it confirms which files are being loaded. If the agent is not following your language rules, use /doctor to check if there are any issues with the installation or file access permissions.
The permission system also plays a role in how the agent applies your language settings. If you are in plan mode, the agent will describe its intended changes in your preferred language before it executes them. This gives you a chance to see if the agent has understood your linguistic requirements. If the plan shows English comments for a project that should be in Spanish, you can deny the permission and clarify your instructions before any files are modified.
You can switch between permission modes like default, acceptEdits, and plan by using Shift-Tab inside a session. This is particularly useful when testing new language settings. By staying in plan mode, you can safely verify that the agent is using the correct grammar and terminology in its proposals before allowing it to use the Write tool to commit changes to your local files.
Adjusting language for subagents and hooks
If you use custom subagents defined in .claude/agents, you must ensure those subagent files also include language instructions. A subagent is a specialized version of the agent that follows its own markdown-based instructions. If your primary agent speaks Portuguese but your subagent instructions are in English, the subagent may revert to English during its tasks. Copy your language requirements into the subagent markdown files to maintain consistency.
Hook events like SessionStart or UserPromptSubmit can also be used to reinforce language settings. For example, you can create a hook that triggers a reminder about the language every time a session starts. This is done by configuring hooks in your settings.json file. Most users will find that consistent instructions in CLAUDE.md and subagent files are sufficient for daily work without needing to rely on complex hook configurations.
If you find yourself frequently using the /clear command to start over, the agent will re-read your CLAUDE.md file immediately. This is the fastest way to apply a new language preference if you have just edited your configuration. The agent will greet you in the new language as soon as the session restarts, confirming that the change was successful and that the project instructions are being followed correctly.
Handling updates and session resets
When you run claude update to get the latest version of the tool, your configuration files like CLAUDE.md and settings.json will remain intact. You do not need to re-configure your language settings after an update. However, if you use the /clear command to start a fresh session in the same folder, the agent will re-read the CLAUDE.md file from scratch. This is a good way to apply new language rules if you have just edited the configuration.
If you need to move between different computers, remember that your settings are tied to the files on your disk. Using adhdTerminal can help here because one key allows you to move your setup between computers. While the app itself does not sync your local CLAUDE.md files, it provides a consistent interface on both macOS and Windows for managing your various language-specific tiles. This makes it easier to maintain your workflow as you move between different development environments.
The agent is designed to be highly adaptable to your local environment. Whether you are using specialized tools like Grep and Glob to search your code or using WebSearch to find documentation, your language settings act as a filter for how that information is presented back to you. By taking the time to configure your CLAUDE.md files correctly, you ensure that Claude Code remains an efficient and comfortable tool for your specific regional and professional context.
Questions people ask
Can I set the language using a command line flag when I start the agent?
No, there is no specific flag like --lang for the claude command. You must set the language by adding instructions to your CLAUDE.md file or by using the /memory command once the session has started. The agent looks at these files and its internal memory to determine which language to use for its output.
Does changing the language affect the cost or token usage?
The language itself does not change the price of the service, but different languages use different numbers of tokens to express the same idea. Some languages are more token-dense than others, which might slightly change the context window usage. You can monitor your spend and token usage at any time by using the /cost and /usage commands inside your session.
Will the agent translate existing English comments in my code into my target language?
The agent will only translate existing comments if you specifically ask it to do so using the Edit tool. By default, it will respect the existing language in a file. If you want a full translation, you should provide a prompt asking the agent to rewrite the comments in your preferred language while following the instructions in your CLAUDE.md file.
Read next
- Add build instructions to your CLAUDE.md fileImprove project context by adding specific build commands and environment requirements to your CLAUDE.md file for the AI to follow.
- Add common error fixes to CLAUDE.mdImprove project memory by adding a section for common errors and their fixes to your CLAUDE.md configuration file.
- Add custom shell aliases for Claude CodeSpeed up your workflow by creating shell aliases for common Claude Code invocations and project-specific startup commands.
- Add test commands to a CLAUDE.md fileUnderstand how to define specific test runners and environment flags in your CLAUDE.md file so the tool runs the correct test suite.