Documentation 2025-10-20 21:02 UTC to 2025-10-21 00:04 UTC

129 129 

130### Dependency management130### Dependency management

131 131 

132Configure automatic dependency installation using the `sessionStart` hook:132Configure automatic dependency installation using [SessionStart hooks](/en/docs/claude-code/hooks#sessionstart). This can be configured in your repository's `.claude/settings.json` file:

133 133 

134```json theme={null}134```json theme={null}

135{135{

136 "hooks": {136 "hooks": {

137 "sessionStart": [137 "SessionStart": [

138 {138 {

139 "matcher": "",139 "matcher": "startup",

140 "hooks": [140 "hooks": [

141 {141 {

142 "type": "command",142 "type": "command",

143 "command": "./scripts/install_pkgs.sh"143 "command": "\"$CLAUDE_PROJECT_DIR\"/scripts/install_pkgs.sh"

144 }144 }

145 ]145 ]

146 }146 }

149}149}

150```150```

151 151 

152This ensures dependencies are installed automatically when a new session starts with proper network access.152Create the corresponding script at `scripts/install_pkgs.sh`:

153 

154```bash theme={null}

155#!/bin/bash

156npm install

157pip install -r requirements.txt

158exit 0

159```

160 

161Make it executable: `chmod +x scripts/install_pkgs.sh`

162 

163#### Local vs remote execution

164 

165By default, all hooks execute both locally and in remote (web) environments. To run a hook only in one environment, check the `CLAUDE_CODE_REMOTE` environment variable in your hook script.

166 

167```bash theme={null}

168#!/bin/bash

169 

170# Example: Only run in remote environments

171if [ "$CLAUDE_CODE_REMOTE" != "true" ]; then

172 exit 0

173fi

174 

175npm install

176pip install -r requirements.txt

177```

178 

179#### Persisting environment variables

180 

181SessionStart hooks can persist environment variables for subsequent bash commands by writing to the file specified in the `CLAUDE_ENV_FILE` environment variable. For details, see [SessionStart hooks](/en/docs/claude-code/hooks#sessionstart) in the hooks reference.

153 182 

154## Network access and security183## Network access and security

155 184 

430 459 

431## Best practices460## Best practices

432 461 

4331. **Use Claude Code hooks**: Configure [sessionStart hooks](/en/docs/claude-code/hooks#sessionstart) to automate environment setup, dependency installation, and network configuration4621. **Use Claude Code hooks**: Configure [sessionStart hooks](/en/docs/claude-code/hooks#sessionstart) to automate environment setup and dependency installation.

4342. **Document requirements**: Clearly specify dependencies and commands in your `CLAUDE.md` file. If you have an `AGENTS.md` file, you can source it in your `CLAUDE.md` using `@AGENTS.md` to maintain a single source of truth.4632. **Document requirements**: Clearly specify dependencies and commands in your `CLAUDE.md` file. If you have an `AGENTS.md` file, you can source it in your `CLAUDE.md` using `@AGENTS.md` to maintain a single source of truth.

435 464 

436## Related resources465## Related resources

203 203 

204Runs when Claude Code starts a new session or resumes an existing session (which204Runs when Claude Code starts a new session or resumes an existing session (which

205currently does start a new session under the hood). Useful for loading in205currently does start a new session under the hood). Useful for loading in

206development context like existing issues or recent changes to your codebase.206development context like existing issues or recent changes to your codebase, installing dependencies, or setting up environment variables.

207 207 

208**Matchers:**208**Matchers:**

209 209 

212* `clear` - Invoked from `/clear`212* `clear` - Invoked from `/clear`

213* `compact` - Invoked from auto or manual compact.213* `compact` - Invoked from auto or manual compact.

214 214 

215#### Persisting environment variables

216 

217SessionStart hooks have access to the `CLAUDE_ENV_FILE` environment variable, which provides a file path where you can persist environment variables for subsequent bash commands.

218 

219**Example: Setting individual environment variables**

220 

221```bash theme={null}

222#!/bin/bash

223 

224if [ -n "$CLAUDE_ENV_FILE" ]; then

225 echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"

226 echo 'export API_KEY=your-api-key' >> "$CLAUDE_ENV_FILE"

227 echo 'export PATH="$PATH:./node_modules/.bin"' >> "$CLAUDE_ENV_FILE"

228fi

229 

230exit 0

231```

232 

233**Example: Persisting all environment changes from the hook**

234 

235When your setup modifies the environment (e.g., `nvm use`), capture and persist all changes by diffing the environment:

236 

237```bash theme={null}

238#!/bin/bash

239 

240ENV_BEFORE=$(export -p | sort)

241 

242# Run your setup commands that modify the environment

243source ~/.nvm/nvm.sh

244nvm use 20

245 

246if [ -n "$CLAUDE_ENV_FILE" ]; then

247 ENV_AFTER=$(export -p | sort)

248 comm -13 <(echo "$ENV_BEFORE") <(echo "$ENV_AFTER") >> "$CLAUDE_ENV_FILE"

249fi

250 

251exit 0

252```

253 

254Any variables written to this file will be available in all subsequent bash commands that Claude Code executes during the session.

255 

256<Note>

257 `CLAUDE_ENV_FILE` is only available for SessionStart hooks. Other hook types do not have access to this variable.

258</Note>

259 

215### SessionEnd260### SessionEnd

216 261 

217Runs when a Claude Code session ends. Useful for cleanup tasks, logging session262Runs when a Claude Code session ends. Useful for cleanup tasks, logging session

778* **Environment**: Runs in current directory with Claude Code's environment823* **Environment**: Runs in current directory with Claude Code's environment

779 * The `CLAUDE_PROJECT_DIR` environment variable is available and contains the824 * The `CLAUDE_PROJECT_DIR` environment variable is available and contains the

780 absolute path to the project root directory (where Claude Code was started)825 absolute path to the project root directory (where Claude Code was started)

826 * The `CLAUDE_CODE_REMOTE` environment variable indicates whether the hook is running in a remote (web) environment (`"true"`) or local CLI environment (not set or empty). Use this to run different logic based on execution context.

781* **Input**: JSON via stdin827* **Input**: JSON via stdin

782* **Output**:828* **Output**:

783 * PreToolUse/PostToolUse/Stop/SubagentStop: Progress shown in transcript (Ctrl-R)829 * PreToolUse/PostToolUse/Stop/SubagentStop: Progress shown in transcript (Ctrl-R)