Use --init-only to Run Setup Hooks Without Starting a Session
The --init-only flag runs your initialization hooks and then exits immediately, without starting an interactive session or processing any prompt. This is useful for CI pipelines and setup scripts where you need Claude's hooks to prepare the environment but do not need a conversation.
claude --init-only
If you have SessionStart hooks configured in your settings, they will fire as normal. For example, you might have a hook that loads environment variables, validates tool versions, or syncs configuration:
{
"hooks": {
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": ".claude/hooks/setup-env.sh"
}
]
}
]
}
}
Running claude --init-only triggers that hook, runs the script, and exits with the appropriate status code. This lets you reuse your Claude Code hook infrastructure for general setup tasks.
There is also --init (without the -only suffix), which runs initialization hooks and then starts interactive mode. Use --init when you want to ensure hooks run before a normal session. Use --init-only when you only need the hooks.
# Run hooks then start interactive mode
claude --init
# Run hooks then exit
claude --init-only
Reuse your Claude Code hooks as a lightweight task runner, no session required.
Log in to leave a comment.
When Claude writes error messages, button labels, validation text, or onboarding flows, it defaults to generic developer-speak. Add a "Users" section to your CLAUDE.md describing who your actual users are — their technical level, industry jargon, and what they care about — so Claude writes copy that makes sense to THEM, not to developers.
Use the --agent flag with custom markdown files in .claude/agents/ to launch purpose-built Claude sessions with restricted tools and scoped system prompts.
Every project has traps — the billing module that silently fails if you forget to queue the job, the legacy table with column names that don't match the model, the config value that must be set before tests run. Document these gotchas in your CLAUDE.md so Claude avoids the same mistakes your team spent days debugging.