Common Workflows ​

Learn common workflows for CodeBuddy Code.

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 Codebase ​

Getting a Quick Overview of the Codebase ​

Suppose you've just joined a new project and need to quickly understand its structure.

Steps:

  1. Navigate to the project root directory

    bash
    cd /path/to/project

  2. Start CodeBuddy Code

    bash
    codebuddy

  3. Ask for a high-level overview

    > Give me an overview of this codebase

  4. Dive 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 coding conventions and patterns used in the project
  • Request a glossary of project-specific terminology

Finding Relevant Code ​

Suppose you need to locate code related to a specific feature.

Steps:

  1. Ask CodeBuddy to find relevant files

    > Find the files that handle user authentication

  2. Understand how components interact

    > How do these authentication files work together?

  3. Understand the execution flow

    > Trace the login process from frontend to database

Best Practices:

  • Be specific about what you're looking for
  • Use domain language from the project

Fixing Bugs Efficiently ​

Suppose you encounter an error message and need to find and fix its source.

Steps:

  1. Share the error with CodeBuddy

    > I 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 problem and get the stack trace
  • Mention any steps to reproduce the error
  • Let CodeBuddy know if 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 maintaining 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 that changes maintain backward compatibility when needed
  • Refactor in small, testable increments

Using Specialized Subagents ​

Suppose you want to use specialized AI subagents to handle specific tasks more effectively.

Steps:

  1. View available subagents

    > /agents

    This displays all available subagents and lets you create new ones.

  2. Automatic use of subagents CodeBuddy Code automatically delegates appropriate tasks to specialized subagents:

    > Review my recent code changes for security issues
    > Run all tests and fix any failures

  3. Explicitly request specific subagents

    > Use the code review subagent to check the authentication module
    > Have the debugger subagent investigate why users can't log in

  4. Create custom subagents for your workflow

    > /agents

    Then select "Create New Subagent" and follow the prompts to define:

    • Subagent type (e.g., api-designer, performance-optimizer)
    • When to use it
    • What tools it has access to
    • Its specialized system prompt

Best Practices:

  • Create project-specific subagents in .codebuddy/agents/ for team sharing
  • Use descriptive description fields to enable automatic delegation
  • Limit tool access to what each subagent actually needs
  • See the subagents documentation for detailed examples

Using Plan Mode for Safe Code Analysis ​

Plan mode instructs CodeBuddy to create a plan by analyzing the codebase through read-only operations, perfect 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 research the codebase before changing anything
  • Interactive development: When you want to iterate with CodeBuddy on the direction

How to Use Plan Mode ​

Enable plan mode during a session

You can toggle to plan mode during a session using Shift+Tab to toggle permission modes.

If you're in normal mode, Shift+Tab will first toggle to auto-accept mode, showing ⏵⏵ accept edits on at the bottom of the terminal. Pressing Shift+Tab again will toggle to plan mode, showing ⏸ plan mode on.

Start a new session in plan mode

To start a new session in plan mode, use the --permission-mode plan parameter:

bash
codebuddy --permission-mode plan

Run "headless" queries in plan mode

You can also run queries directly in plan mode using -p (i.e., in "headless mode"):

bash
codebuddy --permission-mode plan -p "Analyze the authentication system and suggest improvements"

Example: Planning a Complex Refactoring ​

bash
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:

> What about backward compatibility?
> How should we handle database migrations?

Configure Plan Mode as Default ​

json
// .codebuddy/settings.json
{
  "permissions": {
    "defaultMode": "plan"
  }
}

See the settings documentation for more configuration options.

Working with Tests ​

Suppose you need to add tests for uncovered code.

Steps:

  1. Identify untested code

    > Find functions in NotificationsService.swift that aren't 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:

  • Request tests that cover edge cases and error conditions
  • Request both unit tests and integration tests when appropriate
  • Have CodeBuddy explain the testing strategy

Creating Merge Requests ​

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 the MR

    > Create an MR

  3. Review and refine

    > Enhance the MR description with more context about security improvements

  4. Add test details

    > Add information about how to test these changes

Best Practices:

  • Have CodeBuddy create the MR directly for you
  • Review the CodeBuddy-generated MR before submitting
  • Have CodeBuddy highlight potential risks or considerations

Working with Documentation ​

Suppose you need to add or update documentation for your code.

Steps:

  1. Identify undocumented code

    > Find functions in the authentication module without proper JSDoc comments

  2. Generate documentation

    > Add JSDoc comments for undocumented functions in auth.js

  3. Review and enhance

    > Improve the generated documentation with more context and examples

  4. Verify documentation

    > Check if the documentation meets our project standards

Best Practices:

  • Specify the documentation style you want (JSDoc, docstrings, etc.)
  • Request examples in the documentation
  • Request documentation for public APIs, interfaces, and complex logic

Working with Images ​

Suppose you need to work with images in your codebase and want CodeBuddy to help analyze image content.

Steps:

  1. Add an image to the conversation You can use any of these methods:

    1. Drag and drop the image into the CodeBuddy Code window
    2. Copy the image and paste it into the CLI with ctrl+v (don't use cmd+v)
    3. Provide CodeBuddy with the image path. For example: "Analyze this image: /path/to/your/image.png"

  2. Have CodeBuddy analyze the image

    > What does this image show?
    > Describe the UI elements in this screenshot
    > Are there any problematic elements in this diagram?

  3. Use images to provide context

    > This is a screenshot of an error. What's causing it?
    > This is our current database schema. 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 could reproduce this component?

Best Practices:

  • Use images when text descriptions are unclear or cumbersome
  • Include screenshots of errors, UI designs, or diagrams for better context
  • You can work with multiple images in a conversation
  • Image analysis works with diagrams, screenshots, mockups, etc.

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

    This includes the full content of the file in the conversation.

  2. Reference a directory

    > What is the structure of @src/components?

    This provides a directory listing with file information.

  3. Reference MCP resources (not yet supported)

    > Show data from @github:repos/owner/repo/issues

    This fetches data from connected MCP servers using the @server:resource format. See MCP resources for details.

Best Practices:

  • File paths can be relative or absolute
  • @ file references add the CODEBUDDY.md from the file's directory and parent directory to the context
  • Directory references show file listings, not content
  • You can reference multiple files in a single message (e.g., "@file1.js and @file2.js")

Using Extended Thinking ​

Suppose you're working on complex architectural decisions, challenging bugs, or multi-step implementation planning that requires deep reasoning.

Note: Thinking mode is disabled by default in CodeBuddy Code. You can enable thinking on-demand using Tab, or with prompts like "think" or "think deeply".

Steps:

  1. Provide context and let CodeBuddy think

    > I need to implement a new authentication system for our API using OAuth2. Think deeply about the best way to implement this in the codebase.

    CodeBuddy will gather relevant information from the codebase and use extended thinking, which will be visible in the interface.

  2. Refine thinking with follow-up prompts

    > Think about potential security vulnerabilities with this approach
    > Think deeply about edge cases we should handle

Tips for getting the most from extended thinking:

Extended thinking is most valuable for complex tasks such as:

  • Planning complex architectural changes
  • Debugging sophisticated issues
  • Creating implementation plans for new features
  • Understanding complex codebases
  • Evaluating trade-offs between different approaches

Use Tab to enable and disable thinking during a session.

The way you prompt for thinking leads to different depths of thinking:

  • "think" triggers basic extended thinking
  • Reinforcing phrases like "think deeply", "think more", "think longer" trigger deeper thinking

Note: CodeBuddy displays its thinking process in italicized gray text above the response.

Resuming Previous Conversations ​

Suppose you've been working on a task with CodeBuddy Code 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 a conversation selector

Steps:

  1. Continue the most recent conversation

    bash
    codebuddy --continue

    This immediately resumes your most recent conversation without any prompts.

  2. Continue in non-interactive mode

    bash
    codebuddy --continue --print "Continue my task"

    Use --print with --continue in non-interactive mode to resume the most recent conversation, perfect for scripts or automation.

  3. Display the conversation selector

    bash
    codebuddy --resume

    This displays an interactive conversation selector with a clear list view showing:

    • Session summary (or initial prompt)
    • Metadata: elapsed time, message count, and git branch

    Use arrow keys to navigate and press Enter to select a conversation. Press Esc to exit.

Best Practices:

  • Conversation history is stored on your local machine
  • Use --continue for quick access to the most recent conversation
  • Use --resume when you need to select a specific past conversation
  • When resuming, you'll see the entire conversation history before continuing
  • Resumed conversations start with the same model and configuration as the original

How it works:

  1. Conversation storage: All conversations are automatically saved locally with complete message history
  2. Message deserialization: When resuming, the entire message history is restored to maintain context
  3. Tool state: Tool usage and results from previous conversations are preserved
  4. Context restoration: The conversation resumes with all previous context intact

Examples:

bash
# Continue the most recent conversation
codebuddy --continue

# Continue the most recent conversation with a specific prompt
codebuddy --continue --print "Show our progress"

# Display the conversation selector
codebuddy --resume

# Continue the most recent conversation in non-interactive mode
codebuddy --continue --print "Run tests again"

Running Parallel CodeBuddy Code Sessions with Git Worktrees ​

Suppose you need to work on multiple tasks simultaneously with complete code isolation between CodeBuddy Code instances.

Steps:

  1. Understand Git worktrees 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.

  2. Create a new worktree

    bash
    # Create a new worktree with a new branch
git worktree add ../project-feature-a -b feature-a

# Or create a worktree with an existing branch
git worktree add ../project-bugfix bugfix-123

    This creates a new directory containing a separate working copy of the repository.

  3. Run CodeBuddy Code in each worktree

    bash
    # Navigate to your worktree
cd ../project-feature-a

# Run CodeBuddy Code in this isolated environment
codebuddy

  4. Run CodeBuddy in another worktree

    bash
    cd ../project-bugfix
codebuddy

  5. Manage your worktrees

    bash
    # List all worktrees
git worktree list

# Remove a worktree when done
git worktree remove ../project-feature-a

Best Practices:

  • Each worktree has its own independent file state, perfect for parallel CodeBuddy Code sessions
  • Changes in one worktree don't affect others, 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 continuing 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 might include:
    • JavaScript projects: Run dependency installation (npm install, yarn)
    • Python projects: Set up virtual environments or install with package managers
    • Other languages: Follow your project's standard setup process

Using CodeBuddy as a Unix-Style Utility ​

Adding CodeBuddy to Validation Workflows ​

Suppose you want to use CodeBuddy Code as a linter or code reviewer.

Add CodeBuddy to build scripts:

json
// package.json
{
    ...
    "scripts": {
        ...
        "lint:codebuddy": "codebuddy -p 'You are a linter. Review changes relative to main and report any issues related to typos. Report filename and line number on one line, and issue description on the second line. Do not return any other text.'"
    }
}

Best Practices:

  • Use CodeBuddy in CI/CD pipelines for automated code reviews
  • 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 get data in a structured format.

Pipe data through CodeBuddy:

bash
cat build-error.txt | codebuddy -p 'Concisely explain the root cause of this build error' > output.txt

Best Practices:

  • Use piping to integrate CodeBuddy into existing shell scripts
  • Combine with other Unix tools for powerful workflows
  • Consider using --output-format for 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)

    bash
    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

    bash
    cat code.py | codebuddy -p 'Analyze this code for bugs' --output-format json > analysis.json

    This outputs a JSON array of messages including metadata (including cost and duration).

  3. Use streaming JSON format

    bash
    cat log.txt | codebuddy -p 'Parse this log file for errors' --output-format stream-json

    This outputs a series 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 if concatenated.

Best Practices:

  • Use --output-format text for simple integrations that only need CodeBuddy's response
  • Use --output-format json when you need the complete conversation log
  • Use --output-format stream-json for real-time output per conversation turn

Creating Custom Slash Commands ​

CodeBuddy Code supports custom slash commands that you can create to quickly execute specific prompts or tasks.

See the slash commands reference page for more details.

Creating Project-Specific Commands ​

Suppose you want to create reusable slash commands for your project that all team members can use.

Steps:

  1. Create a commands directory in your project

    bash
    mkdir -p .codebuddy/commands

  2. Create a Markdown file for each command

    bash
    echo "Analyze this code for performance and suggest three specific optimizations:" > .codebuddy/commands/optimize.md

  3. Use the custom command in CodeBuddy Code

    > /optimize

Best Practices:

  • Command names come from the filename (e.g., optimize.md becomes /optimize)
  • You can organize commands in subdirectories (e.g., .codebuddy/commands/frontend/component.md creates /component with "(project:frontend)" shown in the description)
  • Project commands are available to everyone who clones the repository
  • The Markdown file content 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 $ARGUMENTS placeholder

    bash
    echo 'Find and fix issue #$ARGUMENTS. Follow these steps: 1. Understand the issue described in the ticket 2. Locate 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 an issue number In a CodeBuddy session, use the command with an argument.

    > /fix-issue 123

    This replaces $ARGUMENTS in the prompt with "123".

Best Practices:

  • The $ARGUMENTS placeholder is replaced by any text after the command
  • You can place $ARGUMENTS anywhere in your command template
  • Other useful applications: generating test cases for specific functions, creating documentation for components, reviewing code in specific files, or translating content to specified languages

Creating Personal Slash Commands ​

Suppose you want to create personal slash commands that work across all your projects.

Steps:

  1. Create a commands directory in your home directory

    bash
    mkdir -p ~/.codebuddy/commands

  2. Create a Markdown file for each command

    bash
    echo "Review this code for security vulnerabilities, focusing on:" > ~/.codebuddy/commands/security-review.md

  3. Use your personal custom command

    > /security-review

Best Practices:

  • When listed with /help, personal commands show "(user)" in the description
  • Personal commands are only available to you and not shared with the team
  • Personal commands work across all projects
  • You can use these commands to maintain consistent workflows across different codebases

Having CodeBuddy Code Help with Configuration Directly ​

Suppose you need to configure Bash timeouts, create custom Skills, set up Git Hooks, or adjust various CodeBuddy behaviors, but don't want to spend time looking up documentation or manually editing configuration files.

Steps:

  1. Directly ask how to configure

    > Referring to the CodeBuddy Code official documentation, how do I configure the timeout for Bash commands?

    CodeBuddy will consult the official documentation and explain the specific configuration method, including:

    • Location of the configuration file
    • Specific configuration item names and formats
    • Available configuration options and defaults
    • How the configuration takes effect

  2. Have CodeBuddy complete the configuration for you

    > Referring to the CodeBuddy Code official documentation, change the Bash timeout to 30 minutes

    CodeBuddy will:

    • Find the current configuration file
    • Modify the configuration according to official recommendations
    • Verify the configuration syntax is correct
    • Indicate how the configuration takes effect (e.g., if restart is needed)

  3. Adjust output language and format

    > Referring to the CodeBuddy Code official documentation, how do I adjust the output to Chinese?

    CodeBuddy will explain:

    • How to configure language preferences in user-level or project-level CODEBUDDY.md
    • Specific configuration examples and syntax
    • Configuration priority and inheritance rules
    • How to verify if the configuration is effective
    > Referring to the CodeBuddy Code official documentation, how can I make CodeBuddy's responses more concise?

  4. Create custom Skills

    > Referring to the CodeBuddy Code official documentation, help me create a PDF processing Skill

    CodeBuddy will:

    • Create the .codebuddy/skills/pdf/ directory
    • Generate a SKILL.md file that complies with official specifications
    • Configure appropriate tool permissions
    • Add necessary metadata and descriptions
    • Provide usage examples

  5. Configure Git Hooks

    > Referring to the CodeBuddy Code official documentation, configure a Git pre-commit code check Hook

    CodeBuddy will create appropriate Hook configurations based on your project type, including:

    • Hook trigger timing and conditions
    • Specific commands executed by the Hook
    • Error handling and logging
    • How to temporarily skip the Hook

  6. Configure MCP servers

    > Referring to the CodeBuddy Code official documentation, how do I configure a GitHub MCP server?

    CodeBuddy will:

    • Explain how MCP works
    • Generate configuration files
    • Configure authentication information
    • Test if the connection is working

  7. Verify configuration

    > Referring to the CodeBuddy Code official documentation, check if my Bash timeout configuration is correct
    > Referring to the CodeBuddy Code official documentation, verify my MCP server configuration

Best Practices:

  • Directly tell CodeBuddy what you want, with the "Referring to the CodeBuddy Code official documentation" prefix to ensure accurate information
  • Let CodeBuddy generate configuration files rather than writing them manually to avoid syntax errors
  • Have CodeBuddy verify correctness after configuration to ensure it takes effect
  • Ask about configuration priority and inheritance rules to understand complex configuration scenarios
  • Only consult more in-depth documentation or contact technical support if CodeBuddy can't resolve it

Common configuration examples:

> Referring to the CodeBuddy Code official documentation, help me create a user-level Skill for code review
> Referring to the CodeBuddy Code official documentation, how do I set the default permission mode to plan mode?
> Referring to the CodeBuddy Code official documentation, create a custom slash command to run tests
> Referring to the CodeBuddy Code official documentation, how do I use Git Worktree with CodeBuddy Code?
> Referring to the CodeBuddy Code official documentation, how do I configure custom model providers?
> Referring to the CodeBuddy Code official documentation, how do I disable certain tool usage?
> Referring to the CodeBuddy Code official documentation, how do I configure a proxy server?
> Referring to the CodeBuddy Code official documentation, how do I customize tool usage keyboard shortcuts?

Asking CodeBuddy About Its Features ​

CodeBuddy has built-in access to its official documentation and can answer questions about its own capabilities, limitations, and best practices. When asking, include the "Referring to the CodeBuddy Code official documentation" prefix to ensure you get accurate official information.

Feature query examples:

> Referring to the CodeBuddy Code official documentation, can CodeBuddy Code create merge requests?
> Referring to the CodeBuddy Code official documentation, how does CodeBuddy Code handle permissions?
> Referring to the CodeBuddy Code official documentation, what slash commands are available?
> Referring to the CodeBuddy Code official documentation, how do I use MCP in CodeBuddy Code?
> Referring to the CodeBuddy Code official documentation, how do I configure CodeBuddy Code for Amazon Bedrock?
> Referring to the CodeBuddy Code official documentation, what are CodeBuddy Code's limitations?

Configuration and integration queries:

> Referring to the CodeBuddy Code official documentation, how do I adjust the output to Chinese?
> Referring to the CodeBuddy Code official documentation, how do I configure a proxy server?
> Referring to the CodeBuddy Code official documentation, which model providers are supported?
> Referring to the CodeBuddy Code official documentation, how do I use CodeBuddy Code in CI/CD?
> Referring to the CodeBuddy Code official documentation, how do I configure enterprise deployment?

Advanced feature queries:

> Referring to the CodeBuddy Code official documentation, how does the subagent system work?
> Referring to the CodeBuddy Code official documentation, how do I create custom Skills?
> Referring to the CodeBuddy Code official documentation, what events does the Hook system support?
> Referring to the CodeBuddy Code official documentation, how do I use thinking mode?
> Referring to the CodeBuddy Code official documentation, what's the difference between plan mode and normal mode?

Workflow and best practice queries:

> Referring to the CodeBuddy Code official documentation, what are the best practices for handling large codebases?
> Referring to the CodeBuddy Code official documentation, how do I optimize token usage?
> Referring to the CodeBuddy Code official documentation, how do I share configurations within a team?
> Referring to the CodeBuddy Code official documentation, how do I handle sensitive information?
> Referring to the CodeBuddy Code official documentation, what's the best way to run multiple sessions in parallel?

Best Practices:

  • Use the "Referring to the CodeBuddy Code official documentation" prefix to ensure accurate official information
  • CodeBuddy always has access to the latest CodeBuddy Code documentation, regardless of the version you're using
  • Ask specific questions to get detailed answers, you can ask about:
    • Features and how to use them
    • Configuration options and syntax
    • Best practices and considerations
    • Limitations and known issues
    • Integration and extension methods
  • CodeBuddy can explain complex features like MCP integration, enterprise configuration, and advanced workflows
  • You can ask not only "what is it" but also directly have CodeBuddy help you "do it"
  • If you're unsure about a feature, ask the official documentation first before starting configuration

Next Steps ​

CLI Reference - Complete command-line arguments and options Interactive Mode - Master keyboard shortcuts and tips Slash Commands - Learn about built-in commands Skills System - Extend AI specialized capabilities MCP Integration - Extend tool capabilities

Master these workflows to make CodeBuddy Code your most capable development assistant