Complete guide to using the /issue command for GitHub issue management in Claude Code.
The /issue command provides comprehensive GitHub issue management directly from Claude Code. It integrates with the GitHub CLI (gh) to allow you to create, manage, and track issues without leaving your development environment.
- GitHub CLI (
gh) installed and authenticated - Active GitHub repository
- Internet connection
List all open issues in the current repository.
Usage:
/issue list
Output: Displays a table with:
- Issue number
- Title
- Labels
- Assignees
- Created date
- State (open/closed)
Example:
/issue list
Create a new GitHub issue with intelligent analysis and duplicate detection.
Usage:
/issue new [issue description]
Features:
- Automatic title generation following best practices
- Smart label inference based on content
- Duplicate detection and consolidation
- Structured issue body with proper sections
Title Best Practices:
- Starts with a verb (Add, Fix, Update, Remove, Improve)
- Concise but descriptive (50-72 characters ideal)
- Uses title case or sentence case consistently
- Avoids generic titles like "Bug" or "Feature"
Label Inference:
The command automatically infers appropriate labels:
| Keywords | Inferred Label |
|---|---|
| fix, bug, error, crash, broken | bug |
| add, new, feature, implement | enhancement |
| docs, readme, documentation | documentation |
| slow, performance, optimize | performance |
| refactor, restructure, clean up | refactor |
| UI, UX, design, layout | ui/ux |
| update dependency, upgrade, package | dependencies |
Workflow:
- Command analyzes your description
- Generates a well-formatted title and body
- Infers appropriate labels
- Searches for similar existing issues
- If duplicates found, offers to:
- Update existing issue with new information
- Create new issue anyway
- Cancel operation
- Creates issue with proper formatting
Examples:
/issue new Fix image upload failing for PNG files over 5MB
# Creates issue with:
# Title: "Fix image upload failing for PNG files over 5MB"
# Labels: bug, priority: high
# Body: Structured with description, steps to reproduce, etc.
/issue new Add dark mode toggle to settings panel
# Creates issue with:
# Title: "Add dark mode toggle to settings panel"
# Labels: enhancement, ui/ux
# Body: Structured with description and acceptance criteria
Start working on an issue by creating a dedicated branch.
Usage:
/issue work [issue number or description]
Intelligent Behavior:
When you provide a description instead of a number, the command:
- Searches for existing issues matching the description
- If a matching issue is found, uses that issue
- If no match is found, creates a new issue first
- Then proceeds to create the branch
Workflow:
- If number provided: Validates issue exists
- If description provided: Searches for matching issue or creates new one
- Checks current git status
- Creates a new branch:
issue-[number]-[short-description] - Checks out the new branch
- Optionally adds a comment to the issue
Examples:
# Work on existing issue by number
/issue work 5
# Creates and checks out: issue-5-add-dark-mode
# Work on issue by description (searches first, creates if needed)
/issue work Add authentication system
# Searches for existing "authentication" issues
# If found: uses existing issue
# If not found: creates new issue, then creates branch
# Another example with description
/issue work Fix login timeout bug
# Intelligently searches for related issues
# Creates issue if needed, then creates branch
Check recent commits and close completed issues.
Usage:
/issue check
Workflow:
- Analyzes recent git commits (last 20)
- Looks for issue references:
fixes #N,closes #N,resolves #N - Lists open issues
- Compares commits with open issues
- Asks for confirmation before closing issues
- Closes issues with reference to completing commit
Example:
If you committed with message "fixes #5: Implemented dark mode toggle", running /issue check will detect this and offer to close issue #5.
Analyze and consolidate duplicate or related issues.
Usage:
/issue consolidate
Workflow:
- Fetches all open issues with full details
- Analyzes for consolidation opportunities:
- Duplicates (nearly identical titles/descriptions)
- Related functionality (same feature area)
- Dependencies (issues that overlap)
- Incremental improvements (multiple small issues)
- Common labels and subject matter
- Presents findings with groups of related issues
- Explains WHY they should be combined
- Shows proposed consolidated title and body
- Asks for confirmation
- If approved:
- Updates parent issue with comprehensive description
- Adds references to consolidated issues
- Closes child issues with consolidation comment
- Preserves all important information
Consolidation Criteria:
High Priority:
- Exact or near-duplicate titles
- Same feature request phrased differently
- Bug reports with identical root cause
- Sequential improvements to the same component
Consider Consolidating:
- 3+ issues with same primary label addressing related functionality
- Issues that reference each other in comments
- Issues requiring changes to same files/components
Do NOT Consolidate:
- Issues in different areas of codebase (unless clearly related)
- Different bug reports (might have different causes)
- Issues at different priority levels (unless true duplicates)
- Issues that can be worked on independently
Example:
/issue consolidate
# Might find:
# Group 1 (Duplicates):
# #3: "Add dark mode"
# #7: "Implement dark theme toggle"
# #12: "Dark mode feature request"
#
# Recommendation: Consolidate into #3 (oldest, most detailed)
Get AI-powered recommendations for which issues to work on next.
Usage:
/issue recommend
Analysis Factors:
- Priority labels
- Issue age
- Dependencies and blockers
- Project impact
- Current context
Output:
Top 3 issues with 1-2 sentence explanations for each recommendation.
Example Output:
Top 3 recommended issues:
1. #5: Fix authentication timeout (bug, priority: high)
High priority bug affecting user experience, should be addressed first.
2. #3: Add dark mode toggle (enhancement, ui/ux)
Popular feature request with clear scope, good next step after bug fixes.
3. #12: Optimize database queries (performance)
Improves overall application performance, moderate complexity.
Display detailed information about a specific issue.
Usage:
/issue show [number]
Output:
- Issue title
- Issue number and URL
- Status (open/closed)
- Labels
- Assignees
- Description
- Comments
- Timeline
Example:
/issue show 5
Close an issue with an optional comment.
Usage:
/issue close [number] [optional: reason]
Workflow:
- Asks for confirmation
- Optionally prompts for closing comment
- Closes the issue
Example:
/issue close 5
# Prompts for confirmation and optional comment
/issue close 5 Implemented in commit abc123
# Closes with comment
Add a comment to an issue.
Usage:
/issue comment [number] [comment text]
Example:
/issue comment 5 Working on this, should be done by end of week
Assign an issue to yourself or someone else.
Usage:
/issue assign [number] [optional: username]
Examples:
/issue assign 5
# Assigns to yourself
/issue assign 5 johndoe
# Assigns to GitHub user 'johndoe'
Update issue labels or status.
Usage:
/issue status [number]
Workflow:
- Shows current labels
- Asks what labels to add/remove
- Updates the issue
Example:
/issue status 5
# Shows current labels, prompts for changes
# You might say: "Add priority: high and remove good first issue"
Search for issues by keyword or filter.
Usage:
/issue search [query]
Examples:
/issue search authentication
# Finds all issues mentioning "authentication"
/issue search label:bug
# Finds all issues with bug label
Analyze your codebase to identify bugs, potential issues, and coding practice improvements.
Usage:
/issue find-bugs
What it does:
This command performs a comprehensive code analysis to discover:
- Critical bugs: Security vulnerabilities, data loss risks, crash scenarios
- High priority bugs: Broken functionality, major errors, unhandled exceptions
- Medium priority bugs: Edge cases not handled, minor errors
- Code quality issues: Best practice violations, optimization opportunities
Analysis includes:
- Unhandled errors or exceptions
- Null/undefined reference possibilities
- Race conditions or async/await issues
- Security vulnerabilities (SQL injection, XSS, etc.)
- Logic errors or missing edge case handling
- Code duplication (DRY violations)
- Poor error handling patterns
- Missing input validation
- Performance anti-patterns
- Inconsistent naming or code style
Workflow:
- Claude analyzes your codebase files
- Identifies potential bugs and issues
- Categorizes findings by severity and impact
- Checks existing issues to avoid duplicates
- Presents findings organized by priority
- Asks which findings should become issues
- Creates GitHub issues for selected findings
Output Format:
Code Analysis Results
====================
CRITICAL ISSUES (0 found)
HIGH PRIORITY (2 found)
1. src/auth.js:45 - Unhandled promise rejection in login
Impact: Could cause silent failures during authentication
Priority: High
2. src/api.js:123 - SQL injection vulnerability in search
Impact: Security risk - database could be compromised
Priority: Critical
MEDIUM PRIORITY (3 found)
[Additional findings...]
RECOMMENDATIONS (5 found)
[Code quality improvements...]
Example:
/issue find-bugs
# Analyzes the codebase
# Finds 2 critical issues, 3 high priority issues
# Shows findings with file/line references
# Asks: "Would you like me to create issues for these findings?"
# Creates issues for selected items with proper labels and descriptions
Best Practices:
- Run regularly during development
- Address critical and high priority findings first
- Use findings to improve code quality over time
- Create issues for items you plan to fix later
Note: This command analyzes code and creates issues - it does NOT implement fixes automatically.
Analyze your application to suggest valuable enhancements and new features that would improve the product.
Usage:
/issue find-features
What it does:
This command performs an intelligent analysis to suggest:
- High impact enhancements: Improvements to core functionality that benefit many users
- Medium impact enhancements: Nice-to-have features that complement existing functionality
- New feature ideas: Complementary features that expand capabilities
Analysis includes:
- Current features and functionality gaps
- Incomplete features (TODOs, FIXMEs in code)
- User experience improvements
- Accessibility enhancements
- Performance optimization opportunities
- Integration possibilities with popular tools
- Documentation gaps
- Developer experience improvements
Workflow:
- Claude analyzes your application structure and code
- Reviews existing issues for patterns
- Identifies enhancement opportunities
- Categorizes by impact and value
- Presents top suggestions with explanations
- Asks which suggestions to create as issues
- Creates GitHub issues for selected features
Output Format:
Feature Analysis Results
========================
HIGH IMPACT ENHANCEMENTS (3 found)
1. Add OAuth authentication (Google, GitHub)
Benefit: Reduces signup friction, improves security
Impact: Affects all users, highly requested feature
2. Implement dark mode theme
Benefit: Better UX in low-light environments
Impact: Accessibility improvement, frequently requested
3. Add data export functionality (JSON, CSV)
Benefit: User data ownership and portability
Impact: Critical feature for user trust
MEDIUM IMPACT ENHANCEMENTS (4 found)
[Additional suggestions...]
NEW FEATURE IDEAS (3 found)
[Innovative additions...]
Example:
/issue find-features
# Analyzes your application
# Identifies 3 high-impact, 4 medium-impact enhancements
# Presents findings with user benefit explanations
# Asks: "Which suggestions would you like me to create as issues?"
# Creates issues for selected items with acceptance criteria
Best Practices:
- Run when planning new development cycles
- Focus on user value over technical complexity
- Consider both quick wins and strategic additions
- Balance feature additions with maintenance work
- Use findings to inform product roadmap
Note: This command suggests and creates issues for features - it does NOT implement them automatically.
Display all available /issue subcommands.
Usage:
/issue help
# 1. Create issue
/issue new Add user profile page with avatar upload
# 2. Review and prioritize
/issue list
/issue recommend
# 3. Start working
/issue work 8
# 4. Make commits
git commit -m "feat: implement user profile page - fixes #8"
# 5. Check and close
/issue check# Find duplicate issues
/issue consolidate
# Review what needs attention
/issue list
# Get recommendations
/issue recommend
# Tackle high-priority items
/issue work [number]# Search for related issues
/issue search performance
# Update labels
/issue status 5
# Add: performance, priority: high
# Assign to team members
/issue assign 5 developer-name- Be Specific: Provide clear, detailed descriptions
- Use Good Titles: Start with a verb, be descriptive
- Check for Duplicates: Always search before creating
- Add Context: Include relevant information, screenshots, or examples
When using /issue work [number], branches follow the pattern:
issue-[number]-[kebab-case-description]
Example: issue-5-add-dark-mode-toggle
Reference issues in commits for automatic tracking:
# These keywords close issues automatically:
git commit -m "fixes #5: Complete dark mode implementation"
git commit -m "closes #12: Optimize database queries"
git commit -m "resolves #3: Add authentication system"Use consistent labels across your project:
- Type:
bug,enhancement,documentation - Priority:
priority: high,priority: medium,priority: low - Status:
in-progress,blocked,needs-review - Area:
ui/ux,backend,frontend,api
- Regularly run
/issue consolidateto keep issues organized - Use
/issue checkafter completing work - Update issue statuses to reflect current state
- Close stale or completed issues promptly
For more information, see: