Setting Up Claude Code in Replit
A step-by-step guide from opening the shell to being ready to use Claude Code—with copy-paste commands and prompts for every step.
Known Gotchas
Running Claude Code inside Replit has a few quirks you should know about:
- Installs get wiped on restart. Replit containers are ephemeral outside
/home/runner/workspace. A normal global install disappears every time your container recycles. - Config and auth get wiped too. Claude Code stores its config (auth tokens, settings, memory) in
~/.claudeby default, which also doesn’t survive restarts. - Port conflicts. Replit manages your server via a workflow on port 5000. If Claude Code tries to start the server or bind to that port, things break.
The steps below solve all of these.
Step 1: Open the Shell
In your Replit workspace, open the Shell tab (not the Console).
Step 2: Install Claude Code to a Persistent Path
Paste this into the shell:
curl -fsSL https://claude.ai/install.sh | bash
Then verify it installed correctly:
/home/runner/workspace/.local/bin/claude --version
This installs Claude Code inside /home/runner/workspace, which is the only directory that survives container restarts.
Step 3: Set the Config Directory Secret
Go to Tools → Secrets in your Replit workspace and add this secret:
| Key | Value |
|---|---|
| CLAUDE_CONFIG_DIR | /home/runner/workspace/.claude_user |
This tells Claude Code to store its auth, settings, and memory inside your workspace instead of ~/.claude, so they persist across restarts.
Step 4: Start Claude Code
Back in the shell, run:
claude
Claude Code will start and prompt you to authenticate. Complete the auth flow, then move on to the next steps—you’ll paste prompts directly into Claude Code to finish the setup.
Step 5: Update the .replit File
Copy and paste this prompt into Claude Code:
Update my .replit file to add the Claude Code binary to the PATH. Add an [env] section with this line:
PATH = "/home/runner/workspace/.local/bin:${PATH}"
IMPORTANT: In TOML, all keys after a [section] header belong to that section until the next header. The [env] block must be placed AFTER all top-level keys (like modules, run, hidden) and BEFORE the next section (like [nix]). If an [env] section already exists, just add the PATH line to it. Don't modify any other parts of the file.
This makes the claude command available in your shell without typing the full path every time.
Type this command into Claude Code:
/init
This analyzes your project’s structure, dependencies, and codebase to generate a smart, project-aware CLAUDE.md file. Review and accept the output.
Step 7: Add Replit-Specific Rules to CLAUDE.md
Now copy and paste this prompt into Claude Code to append the Replit environment rules:
Append the following to the end of my existing CLAUDE.md file. Add a blank line before it to separate it from the existing content:
## Replit Environment Rules
This project runs in Replit. The server is managed by a Replit Workflow on port 5000.
- **Never start or restart the server.** Don't run `npm run dev`, `node server/index.ts`, or any command that binds to port 5000. The Replit Workflow manages the server — not Claude Code.
- **Edit files only.** Make code changes to files but don't try to run or serve the app. Replit handles hot-reloading for frontend changes automatically.
- **Don't use Docker or virtual environments.** Replit uses Nix.
- **Don't modify `package.json`, `vite.config.ts`, or `drizzle.config.ts`** unless intentional — these are managed by the Replit environment.
This adds the Replit-specific rules on top of the project-aware setup that /init created.
Step 8: You’re Ready
Claude Code is now installed, persistent, and configured for Replit. From here you can start using it to edit your project files.
A few things to remember:
- To restart the server, use the Replit Workflow (“Start application” in your workspace). If the port is stuck, free it with
fuser -k 5000/tcp 2>/dev/null; sleep 1and the workflow will restart it automatically. - After a container restart, your Claude Code install and config will still be there. Just open the shell and run
claudeto pick up where you left off. - The
CLAUDE.mdfile persists in your project, so Claude Code will always know the Replit rules—no need to repeat them.