Each task in this document includes clear instructions, example commands, and best practices to help you get the most out of CodeBuddy Code.
Understanding a New Code Repository
Quickly Understanding the Code Repository Overview
Suppose you have just joined a new project and need to quickly understand its structure.
Steps:
1. Navigate to the project root directory.
2. Start CodeBuddy Code.
3. Ask for a high-level overview.
Give me an overview of this codebase.
4. Dive deeper into specific components.
Explain the main architectural patterns used here.
What are the key data models?
How is authentication handled?
Best Practices:
Start with macro-level questions, then narrow down to specific areas.
Ask about the coding standards and patterns used in the project.
Request a glossary of project-specific terms.
Finding Relevant Code
Suppose you need to locate code related to a specific feature.
Steps:
1. Ask CodeBuddy to find relevant files.
Find the file that handles user authentication.
2. Understand how components interact.
How do these authentication files work together?
3. Understand the execution flow.
Trace the login process from the frontend to the database.
Best Practices:
Be specific about what you are looking for.
Use the domain language of the project.
Efficiently Fixing Bugs
Suppose you encounter an error message and need to find and fix its source.
Steps:
1. Share errors with CodeBuddy.
You see an error when running npm test.
2. Ask for fix suggestions.
Suggest several ways to fix the @ts-ignore in user.ts.
3. Apply the fix.
Update user.ts to add the null check you suggested.
Best Practices:
Tell CodeBuddy the command to reproduce the issue and obtain a stack trace.
Mention any steps to reproduce the error.
Let CodeBuddy know whether the error is intermittent or persistent.
Refactoring Code
Suppose you need to update legacy code to use modern patterns and practices.
Steps:
1. Identify legacy code that needs refactoring.
Find deprecated API usage in the codebase.
2. Get refactoring suggestions.
Suggest how to refactor utils.js to use modern JavaScript features.
3. Apply changes safely.
Refactor utils.js to use ES2024 features while preserving the same behavior.
4. Verify the refactoring.
Run tests for the refactored code.
Best Practices:
Ask CodeBuddy to explain the benefits of modern approaches.
Request changes that maintain backward compatibility when needed.
Refactor in small, testable increments.
Using Dedicated Subagents
Suppose you want to use specialized AI subagents to handle specific tasks more effectively.
Steps:
1. View available subagents.
This displays all available subagents and allows you to create new ones.
2. Use subagents automatically.
3. CodeBuddy Code automatically delegates appropriate tasks to specialized subagents:
Review my recent code changes for security issues.
Run all tests and fix any failures.
4. Explicitly request a specific subagent.
Use the code-reviewer subagent to check the authentication module.
Have the debugger subagent investigate why the user cannot log in.
5. Create a custom subagent for your workflow.
Then select "Create New Subagent" and define it as prompted:
Subagent type (such as api-designer or performance-optimizer)
When to use it
What tools can it access?
Its dedicated system prompt
Best Practices:
Create project-specific subagents in .codebuddy/agents/ for team sharing.
Use a descriptive description field to enable automatic delegation.
Limit tool access to what each subagent actually needs.
Using Plan Mode for Safe Code Analysis
Plan mode instructs CodeBuddy to analyze the codebase through read-only operations to create a plan, making it ideal for exploring codebases, planning complex changes, or safely reviewing code.
When to Use Plan Mode
Multi-step Implementation: When your feature requires editing many files
Code Exploration: When you want to thoroughly investigate the codebase before making any changes
Interactive Development: When you want to iterate with CodeBuddy on direction
How to Use Plan Mode
Enable plan mode during the session.
You can use a shortcut to switch permission modes during a session to switch to plan mode:
On all platforms: Press Shift+Tab (Windows also supports Alt+M).
If you are in normal mode, pressing the shortcut first switches to auto-accept mode, and the bottom of the terminal displays ⏵⏵ accept edits on. Pressing the shortcut again switches to plan mode and displays ⏸ plan mode on.
Start a new session in plan mode.
To start a new session in plan mode, use the --permission-mode plan parameter:
codebuddy --permission-mode plan
Run "headless" queries in plan mode.
You can also use -p to run queries directly in plan mode (that is, in "headless mode"): codebuddy --permission-mode plan -p "Analyze the authentication system and suggest improvements"
Example: Planning a Complex Refactoring
codebuddy --permission-mode plan
> I need to refactor our authentication system to use OAuth2. Create a detailed migration plan.
CodeBuddy will analyze the current implementation and create a comprehensive plan. Use follow-up questions to refine it:
What about backward compatibility?
How should we handle database migration?
Configuring Plan Mode as Default
{
"permissions": {
"defaultMode": "plan"
}
}
Handling Tests
Suppose you need to add tests for uncovered code.
Steps:
1. Identify untested code.
Find functions in NotificationsService.swift that are not covered by tests.
2. Generate test scaffolding.
Add tests for the notification service.
3. Add meaningful test cases.
Add test cases for edge conditions in the notification service.
4. Run and verify tests.
Run the new tests and fix any failures.
Best Practices:
Require tests that cover edge cases and error conditions.
Request unit tests and integration tests when appropriate.
Have CodeBuddy explain the testing strategy.
Creating a Merge Request
Suppose you need to create a well-documented merge request for your changes.
Steps:
1. Summarize your changes.
Summarize the changes I made to the authentication module.
2. Use CodeBuddy to generate a merge request.
Create an mr.
3. Review and refine.
Enhance the MR description with more context about the security improvements.
4. Add test details.
Add information about how to test these changes.
Best Practices:
Let CodeBuddy create an MR for you directly.
Review the MR generated by CodeBuddy before submitting it.
Have CodeBuddy highlight potential risks or considerations.
Handling Documentation
Suppose you need to add or update documentation for the code.
Steps:
1. Identify undocumented code.
Find functions in the authentication module that lack proper JSDoc comments.
2. Generate documentation.
Add JSDoc comments to undocumented functions in auth.js.
3. Review and enhance.
Improve the generated documentation with more context and examples.
4. Validate documentation.
Check whether the documentation meets our project standards.
Best Practices:
Specify the documentation style you want (JSDoc, docstrings, and so on).
Require examples in the documentation.
Request documentation for public APIs, interfaces, and complex logic.
Handling Images
Suppose you need to process images in a codebase and want CodeBuddy to help analyze the image content.
Steps:
1. Add an image to the conversation by using one of the following methods:
Drag and drop the image into the CodeBuddy Code window.
Copy the image and paste it into the CLI using ctrl+v (do not use cmd+v).
Provide the image path to CodeBuddy. For example: "Analyze this image: /path/to/your/image.png".
2. Ask CodeBuddy to analyze the image
Check whether the documentation meets our project standards.
What does this image show?
Describe the UI elements in this screenshot.
Are there any problematic elements in this chart?
3. Use images to provide context
This is an incorrect screenshot. What caused it?
This is our current database architecture. How should we modify it for the new feature?
4. Get code suggestions from visual content
Generate CSS that matches this design mockup.
What HTML structure can reproduce this component?
Best Practices:
Use images when text descriptions are unclear or cumbersome.
Include screenshots of errors, UI designs, or diagrams to provide better context.
You can work with multiple images in a conversation.
Image analysis applies to diagrams, screenshots, prototypes, and more.
Referencing Files and Directories
Use @ to quickly include files or directories without waiting for CodeBuddy to read them.
Steps:
1. Reference a single file
Explain the logic in @src/utils/auth.js.
By default, file content is included in the conversation. If the file is too large, the original @file is retained so you can continue reading it later with Read or Grep. If the content is long, only the first section may be included along with a prompt to continue reading.
2. Reference a directory
What is the structure of @src/components?
This provides a directory listing with file information.
3. Reference MCP resources (not currently supported)
Display data from @github:repos/owner/repo/issues.
This retrieves data from connected MCP servers using the @server:resource format. For details, see MCP Resources. Best Practices:
File paths can be relative or absolute.
@ File references add the CODEBUDDY.md files from the file directory and its parent directories to the context.
Directory references display a file list rather than content. When a directory is too large, the remaining entries that are not shown are collapsed.
You can reference multiple files in a single message (for example, "@file1.js and @file2.js").
Using Extended Thinking
Suppose you are working on complex architectural decisions, challenging bugs, or multi-step implementation plans that require deep reasoning.
Note:
Thinking mode is disabled by default in CodeBuddy Code. You can press Tab to enable thinking on demand, or use prompts such as "think" or "think deeply".
Steps
1. Provide context and let CodeBuddy think.
I need to implement a new authentication system that uses OAuth2 for our API. Think deeply about the best way to implement this in the codebase.
CodeBuddy will collect relevant information from the codebase and use extended thinking, which will be visible in the interface.
2. Refine thinking with follow-up prompts.
Consider the potential security vulnerabilities of this approach.
Think deeply about the edge cases we should handle.
Tips for getting the most out of extended thinking:
Extended thinking is most valuable for complex tasks, such as:
Plan complex architectural changes.
Debug complex issues.
Create an implementation plan for the new feature.
Understand complex codebases.
Evaluate the trade-offs between different approaches.
Use Tab to enable and disable thinking during a session.
The way you prompt thinking can lead to different depths of thought:
"Thinking" triggers basic extended thinking.
Intensifying phrases such as "think deeply," "think more," "think harder," or "think longer" trigger deeper thinking.
Note:
CodeBuddy displays its thinking process above the response in italic gray text.
Resuming a Previous Conversation
Suppose you have been using CodeBuddy Code to work on a task and need to continue your previous work in a later session.
CodeBuddy Code provides two options for resuming previous conversations:
--continue automatically continues the most recent conversation.
--resume displays the conversation picker.
Steps:
1. Continue the most recent conversation
This immediately resumes your most recent conversation without any prompts.
2. Continue in non-interactive mode
codebuddy --continue --print "Continue my task"
Using --print with --continue in non-interactive mode to resume the most recent conversation is ideal for scripts or automation.
3. Display the conversation picker
This displays an interactive conversation picker that provides a clear list view showing:
Conversation summary (or initial prompt)
Metadata: elapsed time, number of messages, and git branch.
Use the arrow keys to navigate and press Enter to select a conversation. Press Esc to exit.
Best Practices:
Conversation history is stored on the local computer.
Use --continue to quickly access the most recent conversation.
Use --resume when you need to select a specific past conversation.
When resuming, you will see the entire conversation history before continuing.
A resumed conversation starts with the same model and configuration as the original.
How it works:
1. Conversation storage: All conversations are automatically saved locally with their complete message history.
2. Message deserialization: When a restore operation is performed, the entire message history is restored to maintain context.
3. Tool state: Preserves tool usage and results from previous conversations.
4. Context restoration: The conversation is fully restored with all previous context.
Example:
codebuddy --continue
codebuddy --continue --print "Show our progress"
codebuddy --resume
codebuddy --continue --print "Run the tests again"
Running Parallel CodeBuddy Code Sessions with Git Worktrees
Suppose you need to handle multiple tasks concurrently and completely isolate code between CodeBuddy Code instances.
Steps:
1. Learn about Git worktrees.
2. Git worktrees allow you to check out multiple branches of the same repository into separate directories. Each worktree has its own working directory and isolated files while sharing the same Git history. Learn more in the official Git worktree documentation. 3. Create a new worktree.
git worktree add ../project-feature-a -b feature-a
git worktree add ../project-bugfix bugfix-123
This creates a new directory that contains a separate working copy of the repository.
4. Run CodeBuddy Code in each worktree.
cd ../project-feature-a
codebuddy
5. Run CodeBuddy in another worktree.
cd ../project-bugfix
codebuddy
6. Manage your worktrees.
git worktree list
git worktree remove ../project-feature-a
Best Practices:
Each worktree has its own independent file state, making it ideal for parallel CodeBuddy Code sessions.
Changes in one worktree do not affect other worktrees, preventing CodeBuddy instances from interfering with each other.
All worktrees share the same Git history and remote connections.
For long-running tasks, you can let CodeBuddy work in one worktree while you continue development in another.
Use descriptive directory names to easily identify which task each worktree is for.
Remember to initialize the development environment in each new worktree according to your project setup. Depending on your tech stack, this may include:
JavaScript projects: Run dependency installation (npm install, yarn).
Python projects: Set up a virtual environment or use a package manager for installation.
Other languages: Follow the project's standard setup process.
Using CodeBuddy as a Unix-Style Utility
Adding CodeBuddy to Your Validation Workflow
Suppose you want to use CodeBuddy Code as a linter or code reviewer.
Add CodeBuddy to your build script:
{
...
"scripts": {
...
"lint:codebuddy": "codebuddy -p 'You are a linter. Review the changes relative to main and report any issues related to spelling errors. Report the file name and line number on one line, and the issue description on the second line. Do not return any other text.'"
}
}
Best Practices:
Use CodeBuddy in CI/CD pipelines for automated code review.
Customize prompts to check for project-specific issues.
Consider creating multiple scripts for different types of validation.
Piping Input and Output
Suppose you want to pipe data to CodeBuddy and obtain the data in a structured format.
Pipe data through CodeBuddy:
cat build-error.txt | codebuddy -p 'Concisely explain the root cause of this build error' > output.txt
Best Practices:
Integrate CodeBuddy into existing shell scripts using pipes.
Combine with other Unix tools to enable powerful workflows.
Consider using --output-format to obtain structured output.
Controlling Output Format
Suppose you need CodeBuddy's output in a specific format, especially when integrating CodeBuddy Code into scripts or other tools.
Steps:
1. Use text format (default).
cat data.txt | codebuddy -p 'Summarize this data' --output-format text > summary.txt
This outputs only the plain text response from CodeBuddy (default behavior).
2. Use JSON format.
cat code.py | codebuddy -p 'Analyze this code for bugs' --output-format json > analysis.json
This outputs a JSON array of messages that includes metadata such as cost and duration.
3. Use streaming JSON format.
cat log.txt | codebuddy -p 'Parse errors from this log file' --output-format stream-json
This outputs a stream of JSON objects in real time as CodeBuddy processes the request. Each message is a valid JSON object, but the entire output is not valid JSON when the messages are concatenated.
Best Practices:
For simple integrations that only need a response from CodeBuddy, use --output-format text.
When you need complete conversation logs, use --output-format json.
For real-time output of each conversation turn, use --output-format stream-json.
Creating Custom Slash Commands
CodeBuddy Code supports custom slash commands that you can create to quickly run specific prompts or tasks.
Creating Project-Specific Commands
Suppose you want to create reusable slash commands for your project so that all team members can use them.
Steps:
1. Create a commands directory in your project.
mkdir -p .codebuddy/commands
2. Create a Markdown file for each command.
echo "Analyze the performance of this code and suggest three specific optimizations:" > .codebuddy/commands/optimize.md
3. Use custom commands in CodeBuddy Code.
Best Practices:
Command names are derived from file names. For example, optimize.md becomes /optimize.
You can organize commands in subdirectories. For example, .codebuddy/commands/frontend/component.md creates /component, which is displayed as "(project:frontend)" in the description.
Project commands are available to everyone who clones the repository.
The content of the Markdown file becomes the prompt sent to CodeBuddy when the command is invoked.
Adding Command Arguments with $ARGUMENTS
Suppose you want to create flexible slash commands that can accept additional user input.
Steps:
1. Create a command file with the $ARGUMENTS placeholder.
echo 'Find and fix issue #$ARGUMENTS. Follow these steps: 1. Understand the problem described in the ticket 2. Locate the relevant code in the codebase 3. Implement a solution that addresses the root cause 4. Add appropriate tests 5. Prepare a concise MR description' > .codebuddy/commands/fix-issue.md
2. Use the command with the issue number.
3. In a CodeBuddy session, use the command with parameters.
This replaces $ARGUMENTS in the prompt with "123".
Best Practices:
The $ARGUMENTS placeholder is replaced by any text that follows the command.
You can place $ARGUMENTS anywhere in the command template.
Other useful applications: generate test cases for specific functions, create documentation for components, review code in specific files, or translate content into a specified language.
Creating Personal Slash Commands
Suppose you want to create personal slash commands that work across all projects.
Steps:
1. Create a commands directory in your home directory.
mkdir -p ~/.codebuddy/commands
2. Create a Markdown file for each command.
echo "Review this code for security vulnerabilities, focusing on:" > ~/.codebuddy/commands/security-review.md
3. Use your personal custom commands.
Best Practices:
When listed with /help, personal commands display "(user)" in the description.
Personal commands are available only to you and are not shared with your team.
Personal commands are valid across all projects.
You can use these commands to maintain consistent workflows across different codebases.
Letting CodeBuddy Code Configure It for You
Suppose you need to configure Bash timeouts, create custom Skills, set up Git Hooks, or adjust various CodeBuddy behaviors, but you don't want to spend time looking up documentation or manually editing configuration files.
Steps:
1. Ask directly about the configuration method.
Refer to the official CodeBuddy Code documentation. How do you configure the timeout for Bash commands?
CodeBuddy will consult the official documentation and explain the specific configuration methods, including:
Location of the configuration file
Specific configuration item names and formats
Available configuration options and default values
How the configuration takes effect
2. Let CodeBuddy handle the configuration for you.
Refer to the official CodeBuddy Code documentation and change the Bash timeout to 30 minutes.
CodeBuddy will:
Find the current configuration file.
Modify the configuration as officially recommended.
Verify that the configuration syntax is correct.
How the configuration takes effect (for example, whether a restart is required)
3. Adjust the output language and format.
Refer to the official CodeBuddy Code documentation to learn how to set the output language to Chinese.
CodeBuddy will explain:
How to configure language preferences in a user-level or project-level CODEBUDDY.md file
Specific configuration examples and syntax
Configuration priority and inheritance rules
How to verify whether the configuration has taken effect
Refer to the official CodeBuddy Code documentation to learn how to make CodeBuddy's responses more concise.
4. Create a custom Skill.
Create a Skill for PDF processing by referring to the official CodeBuddy Code documentation.
CodeBuddy will:
Create the .codebuddy/skills/pdf/ directory.
Generate a SKILL.md file that complies with official specifications.
Configure appropriate tool permissions.
Add the necessary metadata and descriptions.
Provide usage examples.
5. Configure Git Hook.
Configure a pre-commit code check Hook by referring to the official CodeBuddy Code documentation.
CodeBuddy creates the corresponding Hook configuration based on your project type, including:
Trigger timing and conditions for the Hook
The specific command that the Hook runs.
Error handling and logging.
How to temporarily skip a Hook
6. Configure MCP Server.
How do I configure a GitHub MCP server by referring to the official CodeBuddy Code documentation?
CodeBuddy will:
Explain how MCP works.
Generate the configuration file.
Configure authentication information.
Test whether the connection is normal.
7. Verify the configuration.
Refer to the official CodeBuddy Code documentation and check whether my Bash timeout configuration is correct.
Refer to the official CodeBuddy Code documentation and verify my MCP server configuration.
Best Practices:
Tell CodeBuddy directly what you want, and add the prefix "Refer to the official CodeBuddy Code documentation" to ensure you get accurate information.
Have CodeBuddy generate the configuration file instead of writing it manually to avoid syntax errors.
After the configuration is complete, have CodeBuddy verify whether it is correct to ensure the configuration takes effect.
Ask about configuration priority and inheritance rules to understand complex configuration scenarios.
Only when CodeBuddy cannot resolve the issue do you need to consult more in-depth documentation or contact technical support.
Common configuration examples:
Refer to the official CodeBuddy Code documentation and help me create a user-level Skill for code review.
Refer to the official CodeBuddy Code documentation to learn how to set the default permission mode to plan mode.
Refer to the official CodeBuddy Code documentation and create a custom slash command to run tests.
Refer to the official CodeBuddy Code documentation to learn how to use Git Worktree with CodeBuddy Code.
Refer to the official CodeBuddy Code documentation to learn how to configure a custom model provider.
Refer to the official CodeBuddy Code documentation to learn how to disable the use of certain tools.
Refer to the official CodeBuddy Code documentation to learn how to configure a proxy server.
Refer to the official CodeBuddy Code documentation to learn how to customize keyboard shortcuts for tool usage.
Asking About CodeBuddy Features
CodeBuddy has built-in access to its official documentation and can answer questions about its features, limitations, and best practices. Add the prefix "Refer to the official CodeBuddy Code documentation" when asking questions to ensure you get accurate official information.
Feature query examples:
Refer to the official CodeBuddy Code documentation to learn whether CodeBuddy Code can create merge requests.
Refer to the official CodeBuddy Code documentation to learn how CodeBuddy Code handles permissions.
Refer to the official CodeBuddy Code documentation to learn what slash commands are available.
Refer to the official CodeBuddy Code documentation to learn how to use MCP in CodeBuddy Code.
Refer to the official CodeBuddy Code documentation to learn how to configure CodeBuddy Code for Amazon Bedrock.
Refer to the official CodeBuddy Code documentation to learn about the limitations of CodeBuddy Code.
Configuration and integration queries:
Refer to the official CodeBuddy Code documentation to learn how to set the output language to Chinese.
Refer to the official CodeBuddy Code documentation to learn how to configure a proxy server.
Refer to the official CodeBuddy Code documentation to learn which model providers are supported.
Refer to the official CodeBuddy Code documentation to learn how to use CodeBuddy Code in CI/CD.
Refer to the official CodeBuddy Code documentation to learn how to configure enterprise deployment.
Advanced feature queries:
Refer to the official CodeBuddy Code documentation to learn how the subagent system works.
Refer to the official CodeBuddy Code documentation to learn how to create a custom Skill.
Refer to the official CodeBuddy Code documentation to learn which events the Hook system supports.
Refer to the official CodeBuddy Code documentation to learn how to use thinking mode.
Refer to the official CodeBuddy Code documentation to learn the differences between plan mode and normal mode.
Workflow and Best Practices Queries:
Refer to the official CodeBuddy Code documentation to learn the best practices for working with large codebases.
Refer to the official CodeBuddy Code documentation to learn how to optimize token usage.
Refer to the official CodeBuddy Code documentation to learn how to share configurations within a team.
Refer to the official CodeBuddy Code documentation to learn how to handle sensitive information.
Refer to the official CodeBuddy Code documentation to learn the best way to run multiple sessions in parallel.
Best Practices:
Use the prefix "Refer to the official CodeBuddy Code documentation" to ensure you get accurate official information.
CodeBuddy always has access to the latest CodeBuddy Code documentation, regardless of the version you are using.
Ask specific questions to get detailed answers. You can ask about:
Features and usage
Configuration options and syntax
Best practices and considerations
Limitations and known issues
Integration and extension methods
CodeBuddy can explain complex features such as MCP integrations, enterprise configurations, and advanced workflows.
You can not only ask "what it is" but also directly ask CodeBuddy to help you "do something".
If you are unsure about a feature, consult the official documentation before you start configuration.