Try free

Last updated 13 October 2026

Initialise a project with /init

The challenge of onboarding an agent to your codebase

Starting a new project with a coding agent often feels like teaching a junior developer from scratch. You spend the first thirty minutes explaining where the source code lives, which build tools you prefer, and how to run the test suite. If you do not provide this context immediately, the agent might use the wrong package manager or ignore your specific linting rules. This manual process is repetitive and prone to errors that waste your time and context window on incorrect attempts. Every time you start a new session in a different folder, you find yourself repeating the same instructions about your architectural preferences.

Without a formal set of instructions, the agent relies on its general knowledge of software patterns. This is often not enough for specialized or proprietary projects. You might have a specific way of handling error responses or a custom directory structure that does not follow standard conventions. If the agent makes a mistake because it lacks this knowledge, you have to spend more time correcting the output than you would have spent writing the code yourself. A functional project requires a bridge between the agent's general capabilities and your specific local environment.

Automating project discovery with the init command

The /init command is the primary tool for bridging the gap between a fresh terminal session and a fully contextualized development environment. When you run /init inside a Claude Code session, the agent begins an automated discovery process. It uses tools like Bash, Read, and Glob to scan your current directory for structural clues. It looks for manifest files like package.json, requirements.txt, pyproject.toml, or go.mod to identify your tech stack. This discovery phase is thorough and seeks to understand not just what language you are using, but also which frameworks and libraries are currently active in your repository.

During this process, the agent also identifies your testing frameworks and build scripts. It checks for the existence of directories like tests, spec, or internal to determine where new code should be placed. By the time the command finishes, the agent has a high-level map of your project. It then uses the Write tool to create a CLAUDE.md file in your project root. This file serves as the permanent documentation that the agent will read at the start of every future session in that folder, ensuring you never have to repeat the basic setup steps again.

The structure and role of the project markdown file

The CLAUDE.md file generated by the /init command is a standard markdown document designed for machine consumption. It usually contains three main sections which include build commands, test commands, and code style guidelines. The build section lists the exact Bash commands needed to compile or run your application. The test section provides the specific commands for running the full suite or individual test files. These are not just descriptions but actual command strings the agent can execute using the Bash tool when you ask it to verify its work.

The code style section is perhaps the most important for long-term maintenance. It documents your preferences for naming conventions, directory organization, and architectural patterns. For example, it might specify that you prefer functional components over class components in React, or that you use specific types of dependency injection in a Go project. Because this file sits in your repository root, it is picked up automatically every time you start a session. It ensures that the agent's output remains consistent with the existing codebase regardless of how long the conversation becomes.

Customizing instructions for specific project needs

While the /init command provides a great starting point, the generated CLAUDE.md file is meant to be edited by you. You can open the file in your editor or use the Edit tool within the session to refine the instructions. If the agent missed a specific deployment script or a complex linting command, you should add it manually. Adding a section for common tasks helps the agent understand how to perform routine maintenance in your environment. You can even include examples of well-written code directly in the markdown to serve as a reference for the agent's future Write operations.

You should also consider adding project-specific constraints that might not be obvious from the file structure. If your project has strict security requirements or performance targets, documenting them in CLAUDE.md ensures the agent keeps them in mind during the planning phase. The agent reads this file at the beginning of every session, so any changes you make will have an immediate impact on its behavior. This makes the file a living document that evolves as your project grows and your requirements change.

Managing global and local instructions

Project-specific rules live in the repo root, but you might have personal preferences that apply to every project you touch. Claude Code allows you to maintain a global instruction file at ~/.claude/CLAUDE.md. This is the place for your general coding philosophy, your preferred editor settings, or even your favorite jokes. When you start a session, the agent combines the instructions from your home directory with the ones found in the project root. This layered approach allows you to maintain a consistent personal experience while respecting the unique needs of different codebases.

If you are working on a very large monorepo, you can even place CLAUDE.md files in subdirectories. The agent will prioritize the instructions in the directory where it is currently working. This is useful when one part of your repository uses a different language or framework than another. For instance, a repository might have a Python backend and a TypeScript frontend. Placing a specific guide in each subdirectory ensures the agent uses the correct tools and style guides for the specific task at hand without getting confused by the broader project context.

Visualizing multiple project contexts with adhdTerminal

When you are managing multiple projects that have each been initialized with their own unique rules, keeping track of different terminal windows becomes a cognitive burden. adhdTerminal is a native app for macOS and Windows that solves this by organizing your Claude Code sessions into a visual wall of tiles. Each tile represents a different project session, complete with its own color, name, and number. Because adhdTerminal allows you to run many sessions side by side, you can see at a glance which project is idle and which is currently running a complex task like a full test suite.

The benefit of using adhdTerminal in conjunction with the /init command is the ability to maintain state across restarts. When you restart the app, your tiles reopen in the same place and resume the same sessions. This means the specific context established by your CLAUDE.md files is always visible and ready for interaction. You do not have to remember which directory you were in or which project-specific rules were active. The visual layout provides a persistent map of your ongoing work, making it much easier to switch between different initialized environments without losing your momentum.

Permissions and tool safety during initialization

Running /init involves the agent executing several tools to probe your environment. By default, the agent will ask for your permission before running Bash commands or reading sensitive files. You can manage these permissions in your settings.json file under the permissions key. If you are in a trusted environment and want the process to be faster, you can use Shift+Tab to cycle through permission modes like acceptEdits or plan. However, staying in the default mode is generally safer when you are initializing a project for the first time, as it allows you to see exactly what the agent is looking at.

The agent uses the Bash tool extensively during initialization to check for installed versions of runtimes like Node.js or Python. It might also use Grep to find specific patterns in your code that indicate which libraries are being used. If you want to restrict the agent from reading certain parts of your project during this phase, it is important to know that Claude Code respects your .gitignore file. If a directory is ignored by git, the agent will typically not scan it unless you specifically tell it to do so using the /add-dir command later in the session.

Maintaining a clean session over long development cycles

As you work on an initialized project, the conversation history grows and consumes more of the context window. You can use the /cost and /usage commands to keep track of how much you are spending on a particular project session. When the conversation becomes too long for the agent to track effectively, the /compact command is your best option. It summarizes the work done so far and frees up space while keeping the core project instructions from your CLAUDE.md file intact. This allows you to keep working in the same session without the performance degradation that comes with a full context window.

If you find that the project structure has changed significantly, you can run /init again to refresh the CLAUDE.md file. Alternatively, if a session has become too cluttered with old ideas, you can use /clear to start over in the same folder. Because the project instructions are stored in a file and not just in the session memory, clearing the session does not mean losing your project context. The agent will read the instructions again immediately, allowing you to start fresh with all the knowledge of your build commands and style guides still available.

Questions people ask

What happens if I already have a CLAUDE.md file and I run the init command again?

The agent will read the existing file and suggest updates based on its current scan of the project. It typically asks for permission before overwriting your existing instructions, allowing you to merge new build or test commands into your current setup. This ensures that any manual customizations you have made are not lost during a refresh.

Can I use the init command to create custom slash commands?

No, the /init command specifically manages the CLAUDE.md file and project context. If you want to create custom slash commands, you should create markdown files inside the .claude/commands directory. Each markdown file in that folder becomes a new slash command that you can use to automate specific workflows unique to your team.

Does the init command work in subdirectories that are not git repositories?

Yes, you can run /init in any folder on your system. While it is most effective in the root of a project, it will scan any directory to understand the local context and create a CLAUDE.md file there. This is useful for organizing scripts or documentation folders that might not be part of a larger git repository.

Read next

More on claude code basics·All posts