Jira Extension for Pi

Manage Red Hat Jira issues (issues.redhat.com) directly from pi with read operations and approval-gated write operations.

Features

Read Operations (No Approval Required)

me - Get current Jira user
list - List issues with filters (assignee, status, type, priority, epic)
view - View detailed issue information
search - Advanced JQL-based search
epic-view - View epic with all child issues
list-attachments - List attachments on an issue

Write Operations (Require User Approval)

create - Create new issues (Bug, Task, Story, Epic, Feature)
update - Update issue fields (assignee, priority, labels, etc.)
comment - Add comments to issues
transition - Change issue workflow state
link-to-epic - Link issue to epic
link - Link two issues (blocks, relates to, etc.)
unlink - Remove issue link
attach - Attach file to issue

All write operations show a confirmation dialog before executing, preventing accidental changes.

Prerequisites

1. Jira CLI

Install the jira CLI tool:

go install github.com/ankitpokhrel/jira-cli/cmd/jira@latest

Verify installation:

jira version

2. Jira Configuration

Configure at ~/.config/.jira/.config.yml:

server: https://issues.redhat.com
login: your-email@redhat.com
project:
  key: SRVKP  # Your default project
installation: local
auth_type: bearer

3. API Token

Set up via passage (or environment variable):

# Via passage (recommended)
passage show redhat/issues/atlassian/token

# OR via environment variable
export JIRA_API_TOKEN="your-token-here"

4. VPN Connection

Red Hat Jira requires VPN connection. Make sure you’re connected before using the extension.

5. Test Authentication

jira me

Installation

The extension is already in your pi extensions:

dots/pi/agent/extensions/jira/
├── index.ts         # Main extension
├── actions.ts       # Action handlers
├── types.ts         # Type definitions
├── utils.ts         # Utilities
├── README.md        # This file
└── DESIGN-NOTES.md  # Design discussion

Since it’s in the dots/ directory, it will be symlinked to ~/.pi/agent/extensions/jira/ when you deploy your dots.

Slash Commands

The extension provides several slash commands for instant results (no LLM involved - works like /todos):

Command	Description
`/jira`	Show my open issues (instant)
`/jira-mine`	Show all issues assigned to me (grouped by status)
`/jira-view <key>`	View specific issue (e.g., `/jira-view SRVKP-1234`)
`/jira-search <jql>`	Search with JQL (e.g., `/jira-search status=Blocked`)
`/jira-blocked`	Show blocked issues (instant)
`/jira-recent`	Show recently viewed issues from this session

All commands execute directly - they call the jira CLI and display results immediately without going through the LLM!

Auto-completion support:

/jira-view - Press Tab to see recent issues from your session
/jira-search - Press Tab to see common JQL patterns

Examples

# Quick view of your issues (instant!)
/jira
→ Shows formatted list immediately

# View specific issue (instant!)
/jira-view SRVKP-1234
→ Shows issue details immediately

# Search for blockers (instant!)
/jira-search priority=Blocker
→ Shows search results immediately

# See blocked issues (instant!)
/jira-blocked
→ Shows all blocked/waiting issues

# See what you've been working on
/jira-recent
→ Shows list from session cache

Auto-Detection of Issue Keys

The extension automatically detects Jira issue keys (e.g., SRVKP-1234, KONFLUX-456) in your input and transforms them into view requests.

Examples

# Just type the issue key
SRVKP-1234
→ Automatically transformed to: "View Jira issue SRVKP-1234"

# Multiple keys
SRVKP-1234 SRVKP-5678
→ Automatically transformed to: "View Jira issues: SRVKP-1234, SRVKP-5678"

# Keys in context (no transformation)
"I'm working on SRVKP-1234 which relates to KONFLUX-456"
→ Passed through to LLM with context

This makes it super quick to view issues - just paste the issue key!

Usage Examples

Quick Commands

# Slash command - show my issues
/jira
→ Lists all your open issues

# Auto-detection - just paste issue key
SRVKP-1234
→ Automatically views the issue

# Quick search
/jira-search assignee=currentUser() AND status=Blocked
→ Shows your blocked issues

# Recent issues
/jira-recent
→ Shows issues you've viewed in this session

Get Current User

User: "What is my Jira username?"
Agent: <calls jira tool with action=me>
→ Returns: "Current user: vdemeest"

List Your Open Issues

User: "Show me my open Jira issues"
Agent: <calls jira tool with action=list, assignee=me, status=~Done>
→ Returns list of issues not in Done status

View Issue Details

User: "Show me details for SRVKP-1234"
Agent: <calls jira tool with action=view, key=SRVKP-1234>
→ Returns full issue details

Filter by Type and Priority

User: "Show high priority bugs"
Agent: <calls jira tool with action=list, type=Bug, priority=High,Critical>
→ Returns filtered list

Create Issue (With Approval)

User: "Create a bug for the failing CI tests"
Agent: <calls jira tool with action=create, issueType=Bug, summary=...>
→ Shows approval dialog:
  ┌─────────────────────────────┐
  │ Create Jira Issue?          │
  │                             │
  │ Type: Bug                   │
  │ Summary: "CI tests failing" │
  │ Priority: Major             │
  │                             │
  │ This will create a new      │
  │ issue in Jira.              │
  │                             │
  │ [Yes] [No]                  │
  └─────────────────────────────┘
→ After confirmation: Creates issue and returns key

Update Issue (With Approval)

User: "Assign SRVKP-1234 to me"
Agent: <calls jira tool with action=update, key=SRVKP-1234, field=assignee, value=me>
→ Shows approval dialog
→ After confirmation: Updates issue

Add Comment (With Approval)

User: "Add a comment to SRVKP-1234 saying I'm working on it"
Agent: <calls jira tool with action=comment, key=SRVKP-1234, comment=...>
→ Shows approval dialog with comment preview
→ After confirmation: Adds comment

Transition Issue (With Approval)

User: "Move SRVKP-1234 to In Progress"
Agent: <calls jira tool with action=transition, key=SRVKP-1234, state="In Progress">
→ Shows approval dialog
→ After confirmation: Transitions issue

Advanced Search

User: "Find all blocker issues in SRVKP project"
Agent: <calls jira tool with action=search, jql="project = SRVKP AND priority = Blocker">
→ Returns matching issues

Tool Parameters

Common Parameters

assignee - Username or “me” for current user
status - Status name (use “~Done” for “not Done”)
type - Bug, Task, Story, Epic, Feature (comma-separated)
priority - Blocker, Critical, Major, Minor, Trivial
limit - Max results (default 20 for list, 50 for search)
epic - Filter by epic key
key - Issue key (e.g., SRVKP-1234)

Create Parameters

issueType - Bug, Task, Story, Epic, Feature, Sub-task
summary - Issue title (required)
description - Issue description
priority - Priority level
assignee - Assignee (or “me”)
labels - Array of labels
parent - Parent issue key (for sub-tasks)

Update Parameters

field - Field to update: assignee, priority, labels, summary, description
value - New value

Other Parameters

comment - Comment text
state - New workflow state
jql - JQL query string

Common Issue Types

Bug - Software defects
Task - General work items
Story - User stories/features
Epic - Large features or initiatives
Feature - New features
Sub-task - Child issues

Common Workflow States

To Do - Not started
In Progress - Currently being worked on
Code Review - Awaiting code review
QE Review - In QA testing
Done - Completed
Blocked - Blocked by dependencies

Tips and Tricks

1. Use “me” for Current User

action: list, assignee: "me"
action: create, assignee: "me"

2. Filter by Multiple Values

type: "Bug,Task"
priority: "Critical,Blocker"
status: "To Do,In Progress"

3. Exclude Done Issues

status: "~Done"

4. Search by Epic

action: list, epic: "SRVKP-1234"

5. Use JQL for Complex Queries

action: search, jql: "project = SRVKP AND status != Done AND assignee = currentUser()"

State Management

The extension caches the current user in session state:

First call to me action fetches username from Jira
Username is stored in tool result details
Subsequent operations use cached username
State is reconstructed from session on load
State survives session branching/forking

This reduces API calls and improves performance.

Error Handling

The extension provides helpful error messages:

Authentication Error

Authentication failed. Check API token:
passage show redhat/issues/atlassian/token

Network Error

Network error. Are you on VPN?

Not Found

Issue SRVKP-1234 not found

Approval Pattern

All write operations follow this pattern:

LLM calls jira tool with write action
Extension shows confirmation dialog
User reviews and confirms/cancels
If confirmed: operation executes
If cancelled: returns with cancelled: true

The LLM sees the cancellation and can explain or suggest alternatives.

Integration Patterns

With Org-Mode TODOs

After viewing an issue:

User: "Create a TODO for SRVKP-1234"
Agent: Uses org_todo tool to create corresponding TODO

With Git Commits

User: "Generate commit message for SRVKP-1234"
Agent: Views issue and generates:
  fix(tekton): resolve affinity assistant pod creation
  
  Fixes issue where affinity assistant pod was not
  being created with default serviceAccount.
  
  Refs: SRVKP-1234

With Notes

User: "Create a note documenting SRVKP-1234"
Agent: Views issue and creates denote note with issue details

Future Enhancements

Planned Features

Epic Management
- View epic details with child issues
- Create epics
- Link issues to epics
Feature Support
- Full support for Feature issue type
- Feature-specific fields
Attachments
- Attach files to issues
- Download attachments
- View attachment list
Links
- Link related issues (blocks, relates to, duplicates)
- View issue links
- Create issue links
Offline Support
- Queue write operations when offline
- Sync when connection restored
- Cache issue data in session
Batch Operations
- Update multiple issues at once
- Bulk transition
- Bulk comment/label

Offline Support Strategy

For future offline support, the plan is:

Queue Operations - Store write operations in session when offline
Detect Connectivity - Check VPN/network status
Sync on Connect - Execute queued operations when online
Conflict Resolution - Handle conflicts if issue changed
Cache Issue Data - Store issue details in session for offline viewing

This would work similar to git commits - you can make local changes and push when connected.

Batch Operations Strategy

Batch operations would be useful for:

Sprint Planning - Move multiple issues to sprint
Status Updates - Transition multiple issues at once
Bulk Labeling - Add labels to multiple issues
Team Assignment - Assign multiple issues

However, this can wait until there’s a real need. Start with single operations.

Troubleshooting

Extension Not Loading

Check for errors:

pi  # Look for error messages in TUI

Tool Not Being Called

Be explicit:

User: "Use the jira tool to list my issues"

Approval Dialog Not Showing

Check you’re not in print mode (pi -p)
Verify it’s a write operation (create/update/comment/transition)

Authentication Fails

# Check config
cat ~/.config/.jira/.config.yml

# Test jira CLI
jira me

# Check token
passage show redhat/issues/atlassian/token

Network Errors

Verify VPN connection
Test with: jira me
Check network connectivity

Architecture

jira/
├── index.ts       # Main extension entry point
│                  # - Tool registration
│                  # - State management
│                  # - Custom rendering
│
├── actions.ts     # Action handlers
│                  # - handleMe, handleList, handleView
│                  # - handleCreate, handleUpdate, handleComment
│                  # - handleTransition, handleSearch
│
├── types.ts       # TypeScript type definitions
│                  # - JiraDetails, JiraIssue
│                  # - Parameter types for each action
│
└── utils.ts       # Utility functions
                   # - Parsing (parseIssueList)
                   # - Formatting (getStatusColor, truncate)
                   # - Error handling (getErrorMessage)
                   # - Confirmation messages

Development

Adding New Actions

Add action to StringEnum in index.ts
Add parameter types to types.ts
Add handler function to actions.ts
Add routing in execute() in index.ts
Add custom rendering in renderResult() in index.ts
Update this README

Testing

Test each action manually:

# Start pi
pi

# Test read operations
"What's my Jira username?"
"Show my open issues"
"View SRVKP-1234"
"Search for blocker issues"

# Test write operations (verify approval)
"Create a test bug"  # Should show approval dialog
"Assign SRVKP-1234 to me"  # Should show approval dialog
"Add comment to SRVKP-1234"  # Should show approval dialog
"Move SRVKP-1234 to Done"  # Should show approval dialog

# Test cancellation
Create issue → Cancel in dialog → Should return cancelled

Jira CLI: https://github.com/ankitpokhrel/jira-cli
Red Hat Jira: https://issues.redhat.com
JQL Reference: https://issues.redhat.com/secure/JiraJQLHelp.jspa
Claude Skills Jira: ~/.config/claude/skills/Jira/
Org-Todo Extension: dots/pi/agent/extensions/org-todos/

License

Same as your homelab repository.

Epic Management

View Epic with Children

User: "Show me epic SRVKP-1000"
Agent: <calls jira tool with action=epic-view, key=SRVKP-1000>
→ Shows epic details plus all child issues grouped

Link Issue to Epic

User: "Link SRVKP-1234 to epic SRVKP-1000"
Agent: <calls jira tool with action=link-to-epic>
→ Shows approval dialog
→ Links issue to epic

Issue Links

Link Issues

User: "SRVKP-1234 blocks SRVKP-5678"
Agent: <calls jira tool with action=link, from=SRVKP-1234, to=SRVKP-5678, linkType="blocks">
→ Shows approval dialog
→ Creates issue link

Link types:

blocks - Source blocks target
is blocked by - Source is blocked by target
relates to - General relation
duplicates - Source duplicates target
is duplicated by - Source is duplicated by target

Unlink Issues

User: "Unlink SRVKP-1234 from SRVKP-5678"
Agent: <calls jira tool with action=unlink, from=SRVKP-1234, to=SRVKP-5678>
→ Shows approval dialog
→ Removes link

Attachments

Attach File

User: "Attach screenshot.png to SRVKP-1234"
Agent: <calls jira tool with action=attach, key=SRVKP-1234, file=screenshot.png>
→ Shows approval dialog
→ Uploads file

List Attachments

User: "What files are attached to SRVKP-1234?"
Agent: <calls jira tool with action=list-attachments, key=SRVKP-1234>
→ Shows list of attachments

Testing

The extension includes comprehensive tests for all utilities and functions.

Run tests:

cd dots/pi/agent/extensions/jira
make test

Run tests in watch mode:

make test-watch

Test coverage:

✅ Issue list parsing
✅ Issue key extraction
✅ Status color coding
✅ Priority color coding
✅ Text truncation
✅ Pattern matching (auto-detection)
✅ Detection logic
✅ Confirmation message building
✅ Error message handling

41 tests, all passing!

Jira Extension for Pi

Features

Read Operations (No Approval Required)

Write Operations (Require User Approval)

Prerequisites

1. Jira CLI

2. Jira Configuration

3. API Token

4. VPN Connection

5. Test Authentication

Installation

Slash Commands

Examples

Auto-Detection of Issue Keys

Examples

Usage Examples

Quick Commands

Get Current User

List Your Open Issues

View Issue Details

Filter by Type and Priority

Create Issue (With Approval)

Update Issue (With Approval)

Add Comment (With Approval)

Transition Issue (With Approval)

Advanced Search

Tool Parameters

Common Parameters

Create Parameters

Update Parameters

Other Parameters

Common Issue Types

Common Workflow States

Tips and Tricks

1. Use “me” for Current User

2. Filter by Multiple Values

3. Exclude Done Issues

4. Search by Epic

5. Use JQL for Complex Queries

State Management

Error Handling

Authentication Error

Network Error

Not Found

Approval Pattern

Integration Patterns

With Org-Mode TODOs

With Git Commits

With Notes

Future Enhancements

Planned Features

Offline Support Strategy

Batch Operations Strategy

Troubleshooting

Extension Not Loading

Tool Not Being Called

Approval Dialog Not Showing

Authentication Fails

Network Errors

Architecture

Development

Adding New Actions

Testing

Related

License

Epic Management

View Epic with Children

Link Issue to Epic

Issue Links

Link Issues

Unlink Issues

Attachments

Attach File

List Attachments

Testing