Installing Claude Code Java: Complete Setup and Configuration Guide
-
Last Updated: May 6, 2026
-
By: javahandson
-
Series
Installing Claude Code Java: Complete Setup and Configuration Guide
Installing Claude Code Java support takes under an hour, but the configuration you do upfront determines how well it performs. This complete guide covers Node.js setup, authentication, Maven and Gradle config, and writing your first CLAUDE.md — the file that teaches Claude Code your Spring Boot project.
- 1. System Requirements
- 2. Installing Node.js
- 3. Installing Claude Code
- 4. Authentication
- 5. First Run Inside a Java Project
- 6. Creating Your CLAUDE.md File
- 7. Configuring Claude Code Runtime Settings
- 8. Maven Project Configuration
- 9. Gradle Project Configuration
- 10. Verifying the Complete Setup
- 11. Common Installation Problems and Fixes
- 12. Conclusion
Getting a new developer tool installed and working inside your actual project is often the most friction-filled part of adopting it. Documentation is sometimes scattered, prerequisites are assumed rather than explained, and when something does not work as expected, you can lose an hour to troubleshooting before you write a single line of productive code.
This article is written to prevent exactly that experience. Here you will find a complete, tested walkthrough of every step required to get Claude Code running in your terminal, authenticated with your Anthropic account, and configured to understand your Java project from the first session. Nothing is assumed. Every command is shown exactly as you should run it. Every common failure mode has a diagnosis and fix.
By the end of this article, you will have Claude Code operational and configured for a typical Java Maven or Gradle project. You will understand the difference between global and project-level settings, know how to use the CLAUDE.md file to give Claude Code the project context it needs, and have a checklist to verify that everything is working correctly before you start using it for real work.
One important thing to clarify before we begin: Claude Code is a Node.js application, not a Java application. Your Java installation is completely separate and unaffected by anything in this guide. The Node.js requirement is only for the Claude Code CLI tool itself. Your project continues to use whatever Java version and build tool it currently uses.
1. System Requirements
Claude Code requires Node.js version 18 or higher. This is because Claude Code is distributed as an npm package and uses modern JavaScript features introduced in Node.js 18. Node.js 20 LTS is the recommended version — it is stable, widely supported, and will remain supported for several years.
You also need an Anthropic account with an active paid subscription or API access. Claude Code is not available on the free tier. If you are using it for professional Java development on a team or in production workflows, Anthropic API access gives you the most control over usage and billing. If you are an individual developer, Claude Pro or Claude Max is the most practical entry point.
The operating system requirements are macOS 12 or later, any modern Linux distribution (Ubuntu 20.04+, Debian 11+, or Fedora 36+), or Windows 10/11 via WSL2. Native Windows without WSL2 technically works, but is not recommended — the Unix-like environment provided by WSL2 makes Claude Code’s command execution capabilities significantly more reliable.
| Requirement | Claude Pro, Claude Max, or API key. Needed for the authentication step. |
| Node.js | Version 18 or higher. Check with: node –version |
| npm | Comes bundled with Node.js. Version 8+ recommended. Check: npm –version |
| Operating System | macOS 12+, Linux (Ubuntu 20.04+, Debian 11+), or Windows 10/11 via WSL2 |
| Anthropic Account | Strongly recommended. Claude Code uses git for context, and you need it for safe rollbacks. |
| Java (your project) | Any version. Claude Code does not require Java — this is just for your project. |
| Git | Strongly recommended. Claude Code uses git for context and you need it for safe rollbacks. |
| Maven or Gradle | Whichever your project uses. Claude Code will run build commands using these. |
2. Installing Node.js
If you do not already have Node.js 18 or higher installed, this section covers the cleanest installation approach for each operating system. The key principle is to install Node.js through a version manager (nvm) rather than directly through your system package manager, because version managers make it easy to install, upgrade, and switch between Node.js versions without touching system-level packages.
2.1 macOS — Using nvm
The Node Version Manager (nvm) is the recommended approach on macOS. It installs Node.js into your home directory, avoids permission issues with global npm installs, and lets you easily upgrade Node.js in the future without affecting your system.
# Step 1: Install nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # Step 2: Close and reopen your terminal, OR run this to activate nvm now: export NVM_DIR="$HOME/.nvm" [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh" # Step 3: Install Node.js 20 LTS (recommended) nvm install 20 nvm use 20 nvm alias default 20 # Make Node.js 20 the default for new terminal sessions # Step 4: Verify node --version # Should print v20.x.x npm --version # Should print 10.x.x or higher
2.2 Linux — Ubuntu and Debian
On Ubuntu or Debian-based distributions, the NodeSource repository provides clean, up-to-date Node.js packages that are more reliable and current than the versions available in the default apt repository. The default apt package for Node.js is often several major versions behind.
# Step 1: Add the NodeSource repository for Node.js 20 curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - # Step 2: Install Node.js sudo apt-get install -y nodejs # Step 3: Verify node --version npm --version
Alternatively, nvm works on Linux the same way it does on macOS. The curl command and subsequent steps are identical. nvm is a good choice on Linux, too, if you want the flexibility of managing multiple Node.js versions.
2.3 Windows — WSL2
On Windows, the strongly recommended approach is to use WSL2 (Windows Subsystem for Linux) and install Node.js inside the Linux environment. Claude Code’s command execution capabilities — running maven builds, reading file output, interacting with shell tools — work much more reliably in a Unix environment than on native Windows.
If WSL2 is not yet set up on your machine, open PowerShell as Administrator and run wsl –install. This installs WSL2 and Ubuntu by default. Once WSL2 is running, launch the Ubuntu terminal and follow the Linux installation instructions from section 2.2 above. Your Java projects on Windows are accessible from WSL2 at /mnt/c/Users/YourName/… so you can work on them directly from the Linux terminal.
If WSL2 is not an option in your environment, you can install Node.js natively on Windows from nodejs.org and run Claude Code in PowerShell or Windows Terminal. The core functionality works, but you may encounter occasional issues with path separators and shell command execution that WSL2 would avoid.
3. Installing Claude Code
With Node.js in place, installing Claude Code is a single npm command. Claude Code is published as a global npm package under the name @anthropic-ai/claude-code. Installing it globally makes the Claude command available from any directory in your terminal.
# Install Claude Code globally via npm npm install -g @anthropic-ai/claude-code # Verify the installation succeeded claude --version
If the install succeeds, running claude –version should print the version number of Claude Code. If you instead see ‘command not found’, the most common reason is that npm’s global binary directory is not in your PATH. This is particularly common on Linux when Node.js was installed via the system package manager.
# Diagnose a 'command not found' error after install: npm bin -g # This prints the path where npm puts global binaries. # Example output: /home/yourname/.npm-global/bin # Linux / WSL2 — add to ~/.bashrc: echo 'export PATH="$PATH:/home/yourname/.npm-global/bin"' >> ~/.bashrc source ~/.bashrc # macOS (zsh) — add to ~/.zshrc: echo 'export PATH="$PATH:/home/yourname/.npm-global/bin"' >> ~/.zshrc source ~/.zshrc # Windows PowerShell (native, no WSL2): # System Properties → Advanced → Environment Variables → edit PATH # Verify: claude --version
If you installed Node.js via nvm, the PATH is automatically managed for you, and this problem usually does not occur. This is another reason nvm is the recommended installation approach.
4. Authentication
The Claude Code package is installed, but it cannot do anything yet because it is not connected to your Anthropic account. The authentication step establishes that connection. Run the following command to begin.
claude login
This command opens your default browser to an OAuth authentication page hosted by Anthropic. You log in to your claude.ai account (or create one if you do not have one). You authorise Claude Code to access the API on your behalf. Once authorisation is complete, Claude Code stores a secure token on your machine in ~/.claude/ and subsequent invocations will authenticate automatically without prompting you again.
The stored token is tied to your Anthropic account and is subject to your subscription tier. If you are on Claude Pro, Claude Code will use your Pro allocation. If you are on Claude Max or using an API key, the corresponding limits apply.
4.1 API Key Authentication
If you are setting up Claude Code in a headless environment — a remote server, a Docker container, or a CI/CD pipeline — the browser-based OAuth flow is not practical. In these environments, use API key authentication instead. Create an API key in the Anthropic Console at console.anthropic.com and set it as an environment variable.
# API key authentication for headless or server environments
export ANTHROPIC_API_KEY="sk-ant-your-key-here"
# Make it permanent — choose your environment:
# Linux / WSL2:
echo 'export ANTHROPIC_API_KEY="sk-ant-your-key-here"' >> ~/.bashrc && source ~/.bashrc
# macOS (zsh):
echo 'export ANTHROPIC_API_KEY="sk-ant-your-key-here"' >> ~/.zshrc && source ~/.zshrc
# Windows PowerShell (native):
# Set for current session (immediate effect):
$env:ANTHROPIC_API_KEY = 'sk-ant-your-key-here'
# Windows PowerShell (native):
# Set permanently for all future sessions:
[System.Environment]::SetEnvironmentVariable('ANTHROPIC_API_KEY','sk-ant-your-key-here','User')
# Verify Claude Code can reach the API:
claude --version # Should respond without auth error
Never commit your API key to version control. If you are using API keys in CI/CD systems, use your platform’s secret management — GitHub Actions Secrets, GitLab CI Variables, Jenkins Credentials — rather than hard-coding the key in configuration files.
4.2 Verifying Authentication
After either authentication method, do a quick verification to confirm that Claude Code can successfully communicate with Anthropic’s servers. Launch Claude Code and ask it something trivial.
# Launch Claude Code claude # Inside the session, type: > What Java version is recommended for Spring Boot 3.3? # You should get a direct answer. If you get an authentication error, # the token or API key is not configured correctly.
5. First Run Inside a Java Project
Once Claude Code is installed and authenticated, navigate to your Java project root and launch it. From this point forward, the experience is a conversation in your terminal.
# Navigate to your Java project cd /path/to/your/spring-boot-project # Launch Claude Code claude
At this point, Claude Code is running but knows nothing specific about your project. It will read files on demand as you give it tasks. A good first task for any new project is to ask Claude Code to explore and summarise what it sees.
> Explore this project and give me: 1. A high-level overview of what it does 2. The main architectural layers and how they are structured 3. The technology stack (Java version, Spring version, build tool, database) 4. A list of all @RestController classes and their endpoint counts
Watch what Claude Code does in response. You will see it listing the directory structure, reading pom.xml, or build.gradle, opening a few source files to understand patterns, and checking the test directory. The summary it produces tells you two useful things: what it understands about your project, and where its initial understanding may be incomplete or slightly off.
This exploration step is valuable even beyond the first session. Whenever you come back to a project after a time away, asking Claude Code to re-summarise the current state of a specific area gives you a quick reorientation and surfaces any drift between your mental model of the project and its actual state.
6. Creating Your CLAUDE.md File
The most impactful configuration step after installation is creating a CLAUDE.md file at the root of your project. This file provides the Claude Code project-specific context that persists across all sessions. Without it, Claude Code re-discovers the same information every time. With it, Claude Code starts each session already aligned with your project’s conventions.
Here is a practical CLAUDE.md template for a Spring Boot project that you can adapt immediately. Article 08 covers every section in depth, but this gives you something to work on day one.
# CLAUDE.md # Place this file at the root of your Java project. # Commit it to version control — it is project documentation. ## Project Overview [Brief description: what the service does, who consumes it] Java 21, Spring Boot 3.3, Maven 3.9, PostgreSQL 15 ## Build Commands - Full build: mvn clean install - Unit tests only: mvn test - Integration tests: mvn verify -P integration - Run locally: mvn spring-boot:run - Lint: mvn checkstyle:check ## Package Structure com.example.[project].controller — REST controllers com.example.[project].service — Business logic services com.example.[project].repository — JPA repositories com.example.[project].model — JPA entities com.example.[project].dto — Request/Response DTOs (use records) com.example.[project].config — Spring configuration ## Coding Conventions - Java 21: use records, pattern matching, text blocks where appropriate - Constructor injection ALWAYS — never @Autowired on fields - Logging: SLF4J only, never System.out.println - DTOs: Java records for immutability ## Testing Standards - JUnit 5 + Mockito + AssertJ - Test naming: methodName_condition_expectedResult - @ExtendWith(MockitoExtension.class) for unit tests - @WebMvcTest for controller tests (not @SpringBootTest) ## Do Not - Do NOT modify existing Flyway migration files - Do NOT add Maven dependencies without asking first - Do NOT use @Transactional on controller methods
7. Configuring Claude Code Runtime Settings
Claude Code has a configuration system that controls its runtime behaviour — which model it uses, how it handles permissions for file writes and command execution, and various other preferences. You interact with this system using the Claude config command.
# View all current settings claude config # View a specific setting claude config get model claude config get permissions.write # Set the model (use current recommended model) claude config set model claude-sonnet-4-20250514 # Configure permission behaviour # 'ask' = require explicit approval each time (default, safest) # 'auto' = proceed without asking claude config set permissions.write ask claude config set permissions.execute ask
The permission settings are the most important runtime configuration for most developers. The default ‘ask’ mode for both file writes and command execution is the right starting point — it keeps you in control and prevents Claude Code from making unexpected changes. As you develop confidence in Claude Code’s behaviour for specific, well-understood tasks, you might relax the execution permission to ‘auto’ for build and test commands while keeping write permission on ‘ask’ for file modifications. This reduces the number of approval prompts during tasks that involve many build iterations.
7.1 Global vs Project-Level Settings
Claude Code supports both global settings that apply to all your projects and project-level settings that apply only when you are working in a specific directory. Project-level settings are stored in a .claude/settings.json file at your project root and take precedence over global settings when that project is active.
This separation is useful in practice. You might have a global setting that requires confirmation for all file writes. But for a new greenfield project where you are comfortable with more automation, you can set a project-level override that allows auto-approval for specific action types. For a legacy project where mistakes are costly, you can set project-level settings that require even more caution than your global defaults.
// .claude/settings.json — project-level settings
// Place this at your project root alongside CLAUDE.md
// Commit it to version control so the whole team shares it
{
"model": "claude-sonnet-4-20250514",
"permissions": {
"write": "ask",
"execute": "ask",
"net": "deny"
}
}
8. Maven Project Configuration
For Maven-based Java projects, there are a few specifics worth configuring to get the best experience. The most important thing is making sure Claude Code knows exactly which Maven commands to run, because a wrong command in CLAUDE.md leads to confused build output that Claude Code will misinterpret.
If your project uses the Maven Wrapper (mvnw file at the root), always use ./mvnw in your CLAUDE.md rather than mvn. The Maven Wrapper guarantees the correct Maven version is used regardless of what is installed system-wide. For multi-module Maven projects, specify which module context commands should run in. If some operations apply to specific modules, note that explicitly.
## Maven Build Commands (add to CLAUDE.md) - Full build: ./mvnw clean install - Skip tests (fast build): ./mvnw clean install -DskipTests - Unit tests: ./mvnw test - Integration tests: ./mvnw verify -P integration-tests - Single module tests: ./mvnw test -pl user-service - Dependency tree: ./mvnw dependency:tree - Check for updates: ./mvnw versions:display-dependency-updates ## Maven Module Structure (if multi-module) parent/ user-service/ — User management order-service/ — Order processing notification-service/ — Notifications shared-lib/ — Shared domain types When creating new classes, confirm which module they belong to.
9. Gradle Project Configuration
For Gradle projects, the configuration approach in CLAUDE.md is similar but with Gradle-specific commands. Always use the Gradle Wrapper (./gradlew) rather than a direct gradle invocation to ensure build reproducibility.
## Gradle Build Commands (add to CLAUDE.md) - Full build: ./gradlew clean build - Unit tests: ./gradlew test - Integration tests: ./gradlew integrationTest - Run Spring Boot app: ./gradlew bootRun - Dependency insight: ./gradlew dependencies - Bootjar (fat jar): ./gradlew bootJar ## Gradle Multi-Project Structure settings.gradle defines these subprojects: :api-gateway :user-service :order-service :shared-lib To run tests for a specific subproject: ./gradlew :user-service:test
10. Verifying the Complete Setup
Before you start using Claude Code for real tasks, run through this verification checklist. It only takes a few minutes and confirms that every component is working correctly end-to-end.
# VERIFICATION CHECKLIST # 1. Claude Code is installed and the correct version claude --version # 2. Authentication is working claude config # Should display your settings without auth errors # 3. Navigate to your Java project cd /path/to/your/java-project # 4. Claude Code can understand your project structure # Launch and ask: claude > List all @Service classes in this project and their primary responsibilities # Verify the response is accurate # 5. Claude Code can run build commands > Run the unit tests and report how many pass # Verify it runs the correct test command from CLAUDE.md # 6. Claude Code can create and write files > Create a simple Java utility class StringUtils with one static method: isBlank(String s) that returns true if null or whitespace. Place it in the correct utility package and write a unit test. # Review the proposed files, approve, and confirm the test passes
If all three active tests pass — accurate project description, correct test command execution, and proper file creation with passing test — your setup is complete and ready for productive use.
| Interview Insight: When discussing AI tooling in technical interviews, mentioning that you configure your AI tools with project-specific context files, keep those files in version control, and verify the tool’s understanding before using it on real tasks demonstrates a senior engineering mindset. It shows you treat AI tools with the same rigour as any other tool in your stack — not as magic, but as software that requires thoughtful configuration and validation. |
11. Common Installation Problems and Fixes
Even with clear instructions, something can go wrong. Here are the most common problems you may encounter and exactly how to fix each one.
11.1 ‘claude: command not found’ After Successful npm Install
This means the npm global binary directory is not in your PATH. Run npm bin -g to find the directory, then add it to your shell profile as described in Section 3. If you used nvm for installation, try closing and reopening your terminal — nvm modifies PATH in your shell profile, and the change does not take effect until the profile is re-sourced.
11.2 Permission Denied During npm Install -g
This typically occurs on macOS or Linux when Node.js is installed system-wide using sudo and the global npm directory is owned by root. The correct fix is not to use sudo with npm — instead, configure npm to use a user-owned directory, or reinstall Node.js using nvm, which puts everything in your home directory and avoids this issue entirely.
# Fix npm global install permission issues without sudo: mkdir -p ~/.npm-global npm config set prefix ~/.npm-global # Linux / WSL2: echo 'export PATH="$PATH:$HOME/.npm-global/bin"' >> ~/.bashrc && source ~/.bashrc # macOS (zsh): echo 'export PATH="$PATH:$HOME/.npm-global/bin"' >> ~/.zshrc && source ~/.zshrc # Windows PowerShell (native): # System Properties → Advanced → Environment Variables → edit PATH # Now reinstall Claude Code npm install -g @anthropic-ai/claude-code
11.3 Authentication Browser Does Not Open
In some terminal environments, particularly SSH sessions or terminals inside IDEs, the browser may not open automatically. In this case, Claude Code will print the authentication URL to the terminal. Copy the URL and open it manually in your browser. The OAuth flow completes in the browser, and Claude Code receives the token automatically once you authorise access.
11.4 Claude Code Gives Wrong Build Command Results
If Claude Code runs the wrong build command or misreads the build output, the most common cause is that CLAUDE.md is either missing or does not clearly specify the build commands. Check that your CLAUDE.md exists at the project root and that the build commands section matches exactly what works in your terminal. Also check that you launched claude from the project root directory where CLAUDE.md lives.
11.5 API Key Not Found or Invalid
If you are using API key authentication and getting authentication errors, verify that the environment variable is set correctly in the current shell session. Run echo $ANTHROPIC_API_KEY to confirm the variable is set and non-empty. If it is empty, the export command may not have been added to your shell profile, or you may need to reload it — run source ~/.bashrc on Linux/WSL2, source ~/.zshrc on macOS, or open a new PowerShell window on Windows native.
12. Conclusion
With Node.js installed, Claude Code configured, authentication working, and a CLAUDE.md file in place, you have everything you need to start using Claude Code productively on your Java project. The setup investment is small — under an hour for most developers — and the return starts immediately.
The most important habit to establish from day one is using version control as your safety net. Before any significant Claude Code session, make sure your working directory is clean or your changes are committed. After Claude Code makes changes, review the git diff before approving the commit. This practice makes it safe to give Claude Code real tasks on real code, which is where its value is greatest.
The next article goes deep on the CLAUDE.md file — what to include for different types of Java projects, how to write instructions that Claude Code reliably follows, the advanced techniques that separate a basic CLAUDE.md from a truly effective one, and a complete template you can adapt for your own codebase today.