Learn how to use the Codebuff CLI effectively with these common workflows and best practices. These patterns will help you get the most out of AI-powered development.
Interactive Coding Sessions Starting a New Feature When beginning work on a new feature, follow this workflow:
Start in your project directory
Navigate to your project:
Launch Codebuff
Start the CLI: Or with an initial prompt: codebuff "I need to add user authentication"
Describe your goal
Give the agent context about what you want to build: Add JWT-based authentication to the API. Users should be able to register, login, and access protected endpoints with bearer tokens.
Iterate and refine
Review the agent’s changes and provide feedback: Add token expiration after 24 hours
Add unit tests for the auth middleware
Test the changes
Use bash commands to test: Debugging Issues When you encounter a bug:
Describe the problem
Include symptoms and context: The login endpoint returns 500 when the password is incorrect. It should return 401 with an error message.
Share error messages
Paste error output directly: Error: Cannot read property 'hash' of undefined at compare (/src/auth.js:45:23)
Let the agent investigate
The agent will:
Read relevant files
Identify the root cause
Propose a fix
Make the necessary changes
Verify the fix
Test that the issue is resolved: Refactoring Code For large refactoring tasks, use MAX mode:
Then describe the refactoring:
Refactor the database connection logic to use connection pooling. The current implementation creates a new connection for each query.
Refactoring best practices:
Start with a clear description of what you want to change and why
Let the agent analyze the current structure first
Request tests before making changes to ensure behavior preservation
Review changes incrementally rather than accepting everything at once
Creating and Testing Custom Agents Initial Setup
Initialize project
Create the agent directory structure: This creates:
knowledge.md - Project context.agents/ - Agent directory.agents/types/ - TypeScript types
Fill in knowledge.md
Add project-specific information: # Project knowledge ## Quickstart - Setup: `npm install` - Dev: `npm run dev` - Test: `npm test` ## Architecture - Key directories: `/src/api` , `/src/models` , `/src/utils` - Data flow: API → Controller → Service → Repository ## Conventions - Use async/await, not callbacks - All functions should have JSDoc comments - Prefer functional programming patterns
Create your first agent
Ask Codebuff to help you create an agent: Create a custom agent that reviews pull requests and checks for: - Missing unit tests - Hardcoded credentials - Console.log statements - Missing error handling
Testing Custom Agents Test agents without publishing:
Restart CLI
Custom agents are loaded on startup: # Exit current session /exit # Restart codebuff
Invoke your agent
Use the @ syntax: @my-agent Review the authentication code for security issues
Iterate on the agent
Edit the agent file: # Open in your editor code .agents/my-agent.ts
Make changes, then restart the CLI to reload.
Check logs
If something goes wrong: tail -f ~/.config/codebuff/cli.log
Debugging Agent Issues Common issues and solutions:
Symptoms: Your agent doesn’t show up when typing @Checklist:
Is the file in .agents/ directory?
Does it export default or named export agent?
Is the id field unique?
Did you restart the CLI after creating it?
Check logs: codebuff --clear-logs # Then check ~/.config/codebuff/cli.log
Agent errors during execution
Symptoms: Agent starts but fails with errorsCommon causes:
Invalid tool calls in the agent definition
Incorrect instructions format
Missing required fields
Debug:
Check the error message in the chat
Review agent definition against the TypeScript types
Simplify the agent to isolate the issue
Agent behavior not as expected
Symptoms: Agent runs but doesn’t do what you wantSolutions:
Make instructions more specific and detailed
Add examples of desired behavior
Use <think> blocks to see agent reasoning
Adjust the system prompt
Try a different model (switch to MAX mode)
Publishing Agents to the Store Share your agents with the community:
Prepare your agent
Ensure your agent has: export const agent : AgentDefinition = { id: 'my-agent' , displayName: 'My Agent' , description: 'Clear description of what it does' , publisher: 'your-username' , version: '1.0.0' , instructions: `Detailed instructions...` , // ... other fields }
Don’t include sensitive information like API keys or internal URLs in published agents.
Test thoroughly
Test your agent with various inputs: @my-agent Test case 1 @my-agent Test case 2 @my-agent Edge case
Publish
Use the publish command: Or publish multiple agents:
Verify publication
Check the success message: Your agent is now available in the public agent store.
Update as needed
To publish updates:
Increment the version field
Make your changes
Run /publish again
Publisher Setup Before you can publish, you need a publisher account:
Visit https://codebuff.com/publishers
Create a new publisher profile
Copy your publisher ID
Add it to your agent’s publisher field
export const agent : AgentDefinition = { publisher: 'your-publisher-id' , // ... rest of agent }
Best Practices Communication
Be Specific Provide clear, specific instructions: Good: Add input validation to the login form. Email should match RFC 5322, password should be at least 8 characters with one number and one special character. Display inline error messages below each field.
Less effective: Add validation to the login form
Provide Context Help the agent understand your project:
Fill out knowledge.md with project details
Mention relevant files or modules
Describe architectural constraints
Share coding conventions
Iterate Incrementally Break large tasks into steps:
“First, create the database schema”
“Now add the API endpoints”
“Add input validation”
“Add error handling”
“Finally, add tests”
Organization
Use Agent Modes Strategically Choose the right mode for the task:
FREE: Quick questions, simple edits, documentationDEFAULT: Most coding tasks, bug fixes, featuresMAX: Complex refactoring, architecture changes, thorough reviewsPLAN: Strategic planning, design decisions, breaking down large projects
Keep Conversations Focused Start a new conversation when switching contexts: This helps the agent:
Focus on the current task
Avoid confusion from unrelated history
Load relevant context more efficiently
Leverage Bash Integration Run tests and checks during development: ! npm test ! npm run lint ! git status ! npm run build
This keeps you in the flow without switching windows. Code Quality
Request Tests Always ask for tests with new functionality: Add the user registration endpoint and include unit tests
Review Before Accepting Use the review feature for important changes: /review Check this pull request for security issues and best practices
Use Knowledge Files Maintain knowledge.md with:
Architectural decisions
Coding standards
Common patterns
Things to avoid
Agents automatically read this file for context. Advanced Workflows Multi-File Refactoring For changes across many files:
Describe the scope
Refactor the codebase to use TypeScript instead of JavaScript. Start with the core modules in /src/core, then move to /src/api. Add proper type definitions for all functions.
Review incrementally
As files are changed, review in batches before continuing.
Test at each stage
! npm run typecheck ! npm test
Working with Images For UI implementation:
Describe requirements
Implement this design using React and Tailwind CSS. Make it responsive with mobile breakpoints at 768px. Use the color palette from our design system.
Iterate on details
Adjust the spacing to match the design more closely
Make the hover states more subtle
Automating Repetitive Tasks Create agents for common tasks:
// .agents/pr-reviewer.ts export const agent : AgentDefinition = { id: 'pr-reviewer' , displayName: 'PR Reviewer' , description: 'Reviews pull requests for common issues' , publisher: 'myteam' , instructions: ` You are a code reviewer. Check for: - Security vulnerabilities - Missing error handling - Hardcoded values that should be config - Missing tests - Console.log statements - Incorrect TypeScript types Provide actionable feedback with specific line references. ` , }
Use it consistently:
@pr-reviewer Review these changes before I open the PR
Continuous Learning Build a knowledge base:
# knowledge.md ## Past Issues - 2024-01: Database connection pool exhaustion - always set maxConnections - 2024-02: CORS issues with auth - remember to set credentials: true ## Performance Notes - The image processing endpoint is slow - consider background jobs - Database queries in loops - always batch with Promise.all ## Code Style - Prefer async/await over .then() - Use Zod for runtime validation - Error messages should be user-facing
Update this file as you learn, and agents will benefit from the accumulated knowledge.
Common Pitfalls Don’t commit .env files - Always add to .gitignore
Don’t blindly accept all changes - Review code before committing, especially for security-sensitive areas
Don’t use MAX mode for simple tasks - It’s slower and uses more credits
Don’t skip testing - Always run tests after agent makes changes
Don’t publish agents with secrets - Remove API keys, internal URLs, and sensitive data
Next Steps
Agent Development Deep dive into creating custom agents
SDK Guide Integrate Codebuff into your applications
Commands Reference Complete list of all CLI commands
Examples See real-world usage examples
