Getting started with Claude Code on Perlmutter¶

Claude Code is Anthropic's agentic coding tool for software development. It reads and changes code in your working directory and can run local commands according to its configured permissions.

Claude Code requires a Pro, Max, Team, Enterprise, or Console account; the free Claude.ai plan does not include Claude Code access. See the official Quickstart page for more information on Claude Code, and our Overview page with general information and best practices for using AI coding agents on NERSC systems.

Installation¶

There are several Claude Code surfaces, but only the ones that run on Perlmutter are appropriate for NERSC work: the CLI, the IDE extensions backed by that CLI, and the desktop app connected to Perlmutter over SSH.

Warning

If you want to run Claude Code on your local machine and also give it access to Perlmutter, we recommend using the desktop app's Perlmutter SSH connection. The claude process itself runs on Perlmutter through the SSH connection, like running claude directly on a Perlmutter login node. If Claude Code has access to Perlmutter through another surface (for example, an MCP SSH tool or letting it run ssh perlmutter...) it appears as you the user on Perlmutter and is not subject to the system safeguards we have put in place. You therefore run a higher risk of Claude Code performing actions on your behalf that violate NERSC's Appropriate Use Policy.

CLI¶

Because the CLI runs in the terminal, it is the easiest surface to use on Perlmutter. Note that if you use VS Code on Perlmutter, you can use the Claude Code CLI in the VS Code integrated terminal.

To install the Claude Code CLI on Perlmutter, run the following from your $HOME directory:

curl -fsSL https://claude.ai/install.sh | bash

You can check the install with claude --version, or with claude doctor, the latter providing detailed read-only diagnostics on the health of your install and settings.

To authenticate, run claude and follow the prompts. On a Perlmutter login node there is no local browser, so Claude Code uses its headless login flow:

Start a session with claude. If the browser does not open automatically, press c to copy the login URL to your clipboard.
Open that URL in a browser on your local machine and sign in.
If the browser shows a login code instead of redirecting, paste it back into the terminal at the Paste code here if prompted prompt. (This is expected over SSH, where the browser cannot reach Claude Code's local callback server.)

If interactive login isn't practical, you can instead authenticate with a token or API key:

Run claude setup-token on a machine that has a browser to generate a one-year OAuth token, then set it on Perlmutter as CLAUDE_CODE_OAUTH_TOKEN.
Set ANTHROPIC_API_KEY (a key created in the Claude Console) to authenticate against the API with Console billing. When this variable is set, Claude Code prompts you once to approve the key instead of opening a browser.

For more details, see the Claude Code documentation on installation and authentication.

VS Code IDE Extension¶

First, install the Claude Code CLI on Perlmutter using the instructions above; the extension drives that CLI.

If you have not already done so, set up the VS Code Remote-SSH extension for Perlmutter. We recommend using sshproxy to generate a valid SSH key. By default, VS Code will connect to a login node, which is where you will typically use Claude Code.

Once you are connected to Perlmutter through the Remote-SSH extension, install the Claude Code extension from the VS Code Marketplace (anthropic.claude-code) on the remote host. You can also run code --install-extension anthropic.claude-code. The extension adds inline diffs, @-mentions, and plan review on top of the CLI.

See the documentation on IDE integrations for more details.

Desktop app with a Perlmutter SSH connection¶

You can use the Claude Code desktop app on your local machine and connect to Perlmutter over SSH. With an SSH connection, the claude session runs on the Perlmutter login node with access to its files and tools, while the desktop app serves as your interface. The app installs Claude Code on Perlmutter automatically the first time you connect, so you do not need to install the CLI there yourself.

To do so, you will use NERSC's sshproxy to authenticate the SSH connection to Perlmutter.

Install and sign in to the desktop app on your local Mac or Windows machine (Linux is in beta), then open the Code tab. The desktop app requires a Pro, Max, Team, or Enterprise subscription.
Run sshproxy to generate a short-lived NERSC SSH key (by default ~/.ssh/nersc, valid for about 24 hours). Optionally, add a Perlmutter alias to your local machine's ~/.ssh/config, for example:
```
Host perlmutter
    Hostname perlmutter.nersc.gov
    User <username>
    IdentityFile ~/.ssh/nersc
```
Confirm that ssh perlmutter (or ssh <username>@perlmutter.nersc.gov) connects successfully from your local machine after authenticating with sshproxy.
In the Code tab, click the environment dropdown before starting a session and select + Add SSH connection. Fill in the dialog:
- Name: a friendly label such as Perlmutter
- SSH Host: <username>@perlmutter.nersc.gov, or a host alias defined in ~/.ssh/config (e.g. perlmutter)
- SSH Port: leave empty to use 22 (or the port from your SSH config)
- Identity File: the sshproxy key, e.g. ~/.ssh/nersc (leave empty to use your SSH config default)
Select the new connection from the environment dropdown, choose a project folder on Perlmutter, and start your session. Once connected, SSH sessions support permission modes, connectors, plugins, and MCP servers.

Because sshproxy keys are short-lived, rerun sshproxy (typically once a day) whenever the connection can no longer authenticate.

See the documentation on SSH sessions for more details.

Session and Context Management¶

Start a Claude Code session with claude. Resume the most recent session in the current directory with claude --continue (or claude -c), or pick a session to resume with claude --resume (or claude -r), which shows an interactive picker; pass a session ID or name to resume it directly. Once in a session, you can also resume a previous one with /resume.

Although Claude Code manages context automatically, clearing older tool outputs and summarizing the conversation as you approach the limit, you should also manage context manually. Use /clear to clear the context and screen and start a fresh conversation. Use /compact to condense the current conversation into a summary and keep working; you can pass focus instructions, e.g. /compact focus on the Slurm job scripts. Use /context to visualize how much of the context window is in use.

Use @path/to/file to point Claude Code at specific code. The @ syntax tab-completes file and directory paths. By default Claude Code can access files in your working directory and its subdirectories; use /add-dir <path> to grant access to directories outside it.

Tip

Limited context lengths mean AI agents cannot keep long conversations in their working memory. We therefore recommend asking agents to create external files, typically Markdown files, that preserve important information from your session so that it persists beyond the current session and does not get lost during automatic context management. For example, if Claude Code gives useful insights while analyzing some log files, you can tell it: "Take the details from our discussion analyzing the log files and add them to a Markdown file at the top of this directory."

In Claude Code, a project CLAUDE.md file and its auto memory survive compaction and reload from disk each session, so they are good places to keep durable project instructions and conventions. Run /init to generate a starting CLAUDE.md, and use /memory to view and edit memory files.

CLAUDE.md¶

Create CLAUDE.md files to keep durable project instructions and conventions. The contents of these files are automatically loaded as user instructions and context into Claude Code's sessions. If you find yourself telling Claude Code the same thing repeatedly when you start new sessions, you should add that to a CLAUDE.md file.

For project-specific instructions and conventions, add a CLAUDE.md file in the top directory of that project. If you are using the Claude Code CLI on Perlmutter, this will be the same directory you launch claude from. Run /init in Claude Code from the project directory to have Claude Code create the project-specific CLAUDE.md for you. If needed, you can further modify and refine this file, or just create it yourself from scratch.

For more general default context for all of your projects on Perlmutter, create ~/.claude/CLAUDE.md. The contents of this file are added to Claude Code's context for every session you run on Perlmutter. This is where you should provide Claude Code with details for running on Perlmutter.

Tip

We recommend using our NERSC-managed ~/.claude/CLAUDE.md file as a baseline template for using Claude Code on Perlmutter. It provides useful context and guidelines for orienting Claude Code on Perlmutter. You can add personal preferences and conventions at the end.

Warning

The NERSC-managed ~/.claude/CLAUDE.md file provides Claude Code instructions for running safely on Perlmutter, but this does not guarantee correct behavior. We have started deploying system-wide safeguards to prevent more troublesome behavior from AI coding agents, but you are still responsible for monitoring Claude Code and not permitting it to take actions that violate the Appropriate Use Policy.

NERSC coding agent tools

Permissions and Sandboxing¶

Claude Code has three related but distinct mechanisms that govern what it is allowed and not allowed to do: permission modes set how autonomously Claude may act, permission rules decide which specific tools and commands are allowed, and an optional OS-level sandbox enforces filesystem and network boundaries on shell commands.

Permission modes control how much Claude does without asking. Cycle through them during a session with Shift+Tab, or set one at startup with --permission-mode:

default (shown as Manual): read-only baseline. Claude runs a built-in set of read-only commands (ls, cat, git status, …) without asking and prompts before anything that modifies your system. It can only write within the folder where it was started and its subfolders.
acceptEdits: auto-approves file edits and common filesystem commands within scope.
plan: Claude explores and proposes a plan but does not edit files.
auto: reduces prompts, with a background classifier reviewing actions before they run.
bypassPermissions (equivalent to --dangerously-skip-permissions): disables prompts and safety checks entirely.

Permission rules are allow, ask, and deny entries that decide what a given tool call can do, e.g. Bash(git commit:*), Edit, or Read(./.env). Rules are evaluated in the order deny → ask → allow, and the first match wins. Manage them interactively with /permissions.

Rules live in JSON settings files, which apply in this precedence order (highest first): managed (organization) settings → command-line flags → .claude/settings.local.json (personal, gitignored) → .claude/settings.json (project, shared) → ~/.claude/settings.json (user). The permissions.defaultMode, permissions.allow/ask/deny, and permissions.additionalDirectories keys are the main controls.

Sandboxing is Claude Code's OS-level boundary. On Linux (and macOS/WSL2), it isolates the filesystem and network access of Bash commands and their child processes, so you define which paths and domains commands may touch and the operating system enforces it. Configure it interactively with /sandbox, or via the sandbox.enabled, sandbox.filesystem, and sandbox.network settings.

Tip

We recommend using the default Manual permission mode on NERSC systems and reviewing Claude Code's proposed actions. Avoid bypassPermissions or --dangerously-skip-permissions, both of which remove all safety checks. Enabling the sandbox adds a defense-in-depth boundary that is well suited to Perlmutter's Linux environment. See our recommended best practices for coding agents at NERSC.