LLM Agent Integration

IssueDB is designed to work seamlessly with LLM (Large Language Model) agents. This guide covers how to integrate IssueDB with AI assistants, automation tools, and natural language interfaces.

Overview

IssueDB provides several features for LLM integration:

  1. JSON output: Machine-readable output for all commands

  2. Built-in prompt: Comprehensive agent guide accessible via --prompt

  3. Natural language interface: Ollama integration for conversational commands

  4. Predictable CLI: Consistent, parseable command structure

Built-in Agent Prompt

Access the LLM agent prompt guide:

issuedb-cli --prompt

This outputs a comprehensive guide that can be included in an LLM’s system prompt. It includes:

  • Critical rules for output format

  • Complete command reference

  • Example interactions

  • Quoting rules

Using the Prompt

For LLM agents (like Claude, GPT, etc.), include the prompt in the system instructions:

You are an AI assistant that can manage issues using issuedb-cli.

[Include output of: issuedb-cli --prompt]

The agent will then output executable shell commands.

Ollama Integration

IssueDB includes native Ollama integration for natural language commands.

Setup:

  1. Install Ollama: https://ollama.ai

  2. Pull a model: ollama pull llama3.2

  3. Use the --ollama flag

Usage:

# Natural language commands
issuedb-cli --ollama "create a high priority bug about login issues"
issuedb-cli --ollama "show me all open critical issues"
issuedb-cli --ollama "close issue 5 with a comment saying it's fixed"

Configuration:

Environment variables:

export OLLAMA_MODEL=llama3.2
export OLLAMA_HOST=localhost
export OLLAMA_PORT=11434

Or command-line options:

issuedb-cli --ollama "create an issue" --ollama-model codellama --ollama-host 192.168.1.100 --ollama-port 11434

JSON Output for Automation

All commands support --json for machine-readable output:

# List issues as JSON
issuedb-cli --json list

# Create issue and get JSON response
issuedb-cli --json create -t "New issue" --priority high

# Get structured data for processing
issuedb-cli --json summary

Parsing JSON in scripts:

# Using jq
OPEN_COUNT=$(issuedb-cli --json summary | jq '.by_status.open.count')

# Using Python
python -c "
import json, subprocess
result = subprocess.run(['issuedb-cli', '--json', 'list'], capture_output=True, text=True)
issues = json.loads(result.stdout)
print(f'Found {len(issues)} issues')
"

Agent Command Patterns

Common patterns for LLM agents:

Creating Issues

# Basic creation
issuedb-cli create -t "Fix bug in login" --priority high

# With description
issuedb-cli create -t "Add dark mode" -d "Users want a dark theme option" --priority medium

Querying Issues

# Get next issue to work on
issuedb-cli --json get-next

# Get the last issue fetched (useful for context continuity)
issuedb-cli --json get-last

# Get last 5 fetched issues
issuedb-cli --json get-last -n 5

# Search for specific issues
issuedb-cli --json search -k "authentication"

# Get summary
issuedb-cli --json summary

Updating Issues

# Update status
issuedb-cli update 1 -s in-progress

# Close with comment
issuedb-cli update 1 -s closed && issuedb-cli comment 1 -t "Fixed in PR #123"

Bulk Operations

# Bulk create from JSON
echo '[{"title": "Issue 1"}, {"title": "Issue 2"}]' | issuedb-cli --json bulk-create

# Bulk close
echo '[1, 2, 3]' | issuedb-cli --json bulk-close

Example: Claude Code Integration

When using IssueDB with Claude Code or similar assistants:

System prompt addition:

You can manage project issues using the issuedb-cli tool.

Key commands:
- issuedb-cli create -t "TITLE" [--priority PRIORITY]
- issuedb-cli list [--status STATUS]
- issuedb-cli update ID -s STATUS
- issuedb-cli comment ID -t "COMMENT"
- issuedb-cli --json COMMAND (for machine-readable output)

Always use --json for output you need to parse.
Priorities: low, medium, high, critical
Statuses: open, in-progress, closed

Example interaction:

User: Create an issue for the login bug we discussed

Agent: I'll create a high-priority issue for the login bug.

$ issuedb-cli --json create -t "Fix login bug with special characters" \
    -d "Users cannot log in when password contains special characters" \
    --priority high

Example: GitHub Actions

Using IssueDB in CI/CD:

name: Issue Management

on:
  workflow_dispatch:
    inputs:
      action:
        description: 'Action to perform'
        required: true
        type: choice
        options:
          - create
          - close-completed

jobs:
  manage-issues:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install IssueDB
        run: pip install issuedb

      - name: Create Issue
        if: github.event.inputs.action == 'create'
        run: |
          issuedb-cli create -t "Automated issue from CI" \
            -d "Created by GitHub Actions" \
            --priority medium

      - name: Close Completed Issues
        if: github.event.inputs.action == 'close-completed'
        run: |
          issuedb-cli bulk-update --filter-status in-progress -s closed

Example: Python Script Integration

Using IssueDB from Python:

import json
import subprocess
from typing import List, Dict, Any

def run_issuedb(args: List[str]) -> Dict[str, Any]:
    """Run issuedb-cli command and return JSON result."""
    result = subprocess.run(
        ['issuedb-cli', '--json'] + args,
        capture_output=True,
        text=True,
        check=True
    )
    return json.loads(result.stdout)

def create_issue(title: str, priority: str = 'medium', description: str = None) -> Dict:
    """Create a new issue."""
    args = ['create', '-t', title, '--priority', priority]
    if description:
        args.extend(['-d', description])
    return run_issuedb(args)

def get_open_issues() -> List[Dict]:
    """Get all open issues."""
    return run_issuedb(['list', '-s', 'open'])

def close_issue(issue_id: int, comment: str = None) -> Dict:
    """Close an issue with optional comment."""
    run_issuedb(['update', str(issue_id), '-s', 'closed'])
    if comment:
        return run_issuedb(['comment', str(issue_id), '-t', comment])
    return run_issuedb(['get', str(issue_id)])

# Usage
if __name__ == '__main__':
    # Create an issue
    issue = create_issue("Test from Python", priority="high")
    print(f"Created issue #{issue['id']}")

    # List open issues
    open_issues = get_open_issues()
    print(f"Found {len(open_issues)} open issues")

    # Close with comment
    close_issue(issue['id'], "Closed from Python script")

Best Practices

  1. Always use –json: For programmatic access, always use JSON output

  2. Check exit codes: Non-zero exit code indicates an error

  3. Parse errors from stderr: Error messages go to stderr, not stdout

  4. Use bulk operations: For multiple issues, use bulk commands for efficiency

  5. Include the prompt: For LLM agents, include the full --prompt output

  6. Test commands: Verify commands work before automating

Troubleshooting

Command not found:

Ensure IssueDB is installed and in PATH:

pip install issuedb
which issuedb-cli

JSON parsing errors:

Ensure you’re capturing stdout only:

# Correct
OUTPUT=$(issuedb-cli --json list 2>/dev/null)

# Parse only if successful
if [ $? -eq 0 ]; then
    echo "$OUTPUT" | jq '.'
fi

Ollama not responding:

Check Ollama is running:

curl http://localhost:11434/api/tags