IBM Bob
Tutorials

Start a project with /init and AGENTS.md in Bob Shell

Run the Bob Shell /init command to generate AGENTS.md, a project context file Bob loads in every conversation, and learn how to keep that context current.

The /init command scans a project and generates a structured summary file called AGENTS.md that Bob uses as persistent context in every conversation. The /init command is how you give Bob knowledge about a project's structure, conventions, and codebase, without requiring Bob to re-read every file at the start of each interaction.

Large language models are stateless. Each new conversation starts with no memory of previous interactions. Without explicit project context, Bob must discover the codebase with every new interaction, which is inefficient and becomes impractical at scale.

In this tutorial, you initialize Bob Shell in a demo application's root directory, explore the context that Bob gains about the application, and learn how Bob Shell loads AGENTS.md files.

Prerequisites

To complete this tutorial, you need the following:

Bob Shell

Install Bob Shell v2.x or later and sign in.

Git

Install Git to clone the example repository.

  • If you do not already have it, clone the Galaxium Travels demo code. The clone command also checks out the bob-learning-path-branch that contains the code you use in the tutorials. 
    git clone -b bob-learning-path-branch https://github.com/IBM/galaxium-travels
    •
  • While not required, consider reading Starting an interactive session to familiarize yourself with Bob Shell's interface and features.
    •

Start Bob Shell in the project

Change to the Galaxium Travels root directory:

cd galaxium-travels

Start an interactive session:

bob chat --mode agent

The --mode agent flag starts the session in Agent mode, which has the tools Bob needs to read files and write AGENTS.md.

If Bob Shell asks whether you trust the folder, trust it so Bob can work in the project. To learn more, refer to Trusted folders.

Generate AGENTS.md with /init

Enter the /init command at the prompt:

/init

Bob reads the relevant files in the project.

When Bob asks to use a tool, such as reading files or writing AGENTS.md, the approval dialog appears. Select Approve for each request.

Bob generates the main AGENTS.md file in the Galaxium Travels root directory. It also generates mode-specific context files in .bob/rules-agent/AGENTS.md, .bob/rules-ask/AGENTS.md, and .bob/rules-plan/AGENTS.md.

Explore AGENTS.md files

The AGENTS.md file is onboarding documentation for Bob. It is a concise, actionable summary that provides everything Bob needs to understand the project's structure and conventions.

Ask Bob to show you the file:

 
Show me the contents of @AGENTS.md

The @ symbol references a file in your project, so Bob reads it before responding. You can also open another terminal and view the file directly:

 
cat AGENTS.md

The AGENTS.md file typically contains the following components:
  • Project overview and purpose
    •
  • Directory structure and key file locations
    •
  • Technology stack and dependencies
    •
  • Architectural patterns and conventions
    •
  • Development workflows
    •

To see every file that /init created, run git status in the Galaxium Travels directory:

 
git status

How Bob Shell loads AGENTS.md files

Bob Shell automatically loads context files such as AGENTS.md at the start of every task.
  1. Global context: ~/.bob/AGENTS.md applies to all projects.
    2.
  2. Project context: AGENTS.md in the project root and parent directories applies to the project.
    3.
  3. Local context: AGENTS.md in subdirectories applies to that subdirectory, for component-specific instructions.
    4.

To give Bob instructions for a single mode, add mode-specific rules in .bob/rules-<mode>/ directories, such as .bob/rules-plan/ for Plan mode.

Maintain the AGENTS.md files

Re-run /init after the following changes:
  • Adding new modules or services
    •
  • Changing the directory structure
    •
  • Adopting new technologies or frameworks
    •
  • Onboarding new team members who use Bob
    •

You can also manually edit AGENTS.md to add context that Bob's automated scan might not capture, such as business rules, deployment conventions, or team-specific practices. Commit AGENTS.md to version control so your team shares the same context.

Next steps

In this tutorial, you learned the following:
  • Large language models are stateless. Running the /init command solves this issue by generating AGENTS.md, which is a persistent context file Bob reads at the start of every conversation.
    •
  • Re-run /init after major project changes to keep the context current.
    •

Advance to Write effective prompts for Bob Shell to learn how to write prompts that reliably produce the output you want.

How is this topic?

Introduction to Bob Shell

Learn to use Bob Shell, IBM Bob's AI coding agent for the terminal, in hands-on tutorials that build and extend the Galaxium Travels demo app.

Write effective prompts for Bob Shell

Write effective prompts for Bob Shell by adding a role, context, and examples, then refine a vague request into documented Python code with error handling.

On this page

PrerequisitesStart Bob Shell in the projectGenerate AGENTS.md with /initExplore AGENTS.md filesHow Bob Shell loads AGENTS.md filesMaintain the AGENTS.md filesNext steps