tyraj-misiu

🚀 Standalone CLI tool for automation: Task Management (Trello/Jira) → Claude Agent → GitHub Pull Request

🔄 NEW: Multi-Provider Support - Works with both Trello and Jira!

🌳 Worktree Mode - Run 3-5 agents in parallel with full isolation!

📦 How to Use

Provider Support

This tool supports both Trello and Jira. You can:

• Use one provider (auto-detected from .env)
• Use both providers (interactive selection at startup)
• Specify provider via --provider=trello or --provider=jira flag

Method 1: Interactive Mode (Recommended) - Trello

# In your project directory:
cd my-project
git init
git remote add origin https://github.com/username/my-project.git

# Create .env with your API keys
cat > .env << EOF
TRELLO_KEY=your_key
TRELLO_TOKEN=your_token
TRELLO_TODO_STATUS=To Do
TRELLO_TESTING_STATUS=DEV TESTING
GITHUB_TOKEN=your_github_token
GITHUB_REPO_OWNER=username
GITHUB_REPO_NAME=my-project
EOF

# Run the tool (no card ID needed!):
npx tyraj-misiu

# The tool will:
# 1. Fetch all cards from "To Do" lists
# 2. Show you an interactive list
# 3. Use arrow keys to select a card
# 4. Press Enter to start implementation

Method 1b: Interactive Mode - Jira

# In your project directory:
cd my-project
git init
git remote add origin https://github.com/username/my-project.git

# Create .env with Jira credentials
cat > .env << EOF
JIRA_HOST=https://yourcompany.atlassian.net
[email protected]
JIRA_API_TOKEN=your_jira_token
JIRA_TODO_STATUS=To Do
JIRA_TESTING_STATUS=In Testing
GITHUB_TOKEN=your_github_token
GITHUB_REPO_OWNER=username
GITHUB_REPO_NAME=my-project
EOF

# Run the tool:
npx tyraj-misiu

# Or specify Jira explicitly:
npx tyraj-misiu --provider=jira

# The tool will:
# 1. Fetch all issues with "To Do" status
# 2. Show you an interactive list
# 3. Use arrow keys to select an issue
# 4. Press Enter to start implementation

Method 2: Direct ID (Skip Interactive Selection)

# If you already know the card/issue ID:
npx tyraj-misiu --cardId=ABC123  # Trello card
npx tyraj-misiu --cardId=PROJ-123 --provider=jira  # Jira issue

Method 3: Worktree Mode (Parallel Processing)

# Run multiple agents in parallel - each in a separate terminal:

# Terminal 1:
npx tyraj-misiu --worktree
# Select provider → Select task A, agent works in ~/.trello-agents/agent-XXX/

# Terminal 2:
npx tyraj-misiu --worktree --provider=jira
# Works with Jira issue B in ~/.trello-agents/agent-YYY/

# Terminal 3:
npx tyraj-misiu --worktree
# Select task C, agent works in ~/.trello-agents/agent-ZZZ/

# Each agent creates isolated worktree and works independently!

Method 4: Global Installation

npm install -g tyraj-misiu

# Interactive mode:
cd ~/my-project
tyraj-misiu

# With provider selection:
tyraj-misiu --provider=jira

# Or with task ID:
tyraj-misiu --cardId=PROJ-123 --provider=jira

# Or parallel mode:
tyraj-misiu --worktree

🎯 Workflow

Interactive Mode (New!)

1. Create cards in your Trello "To Do" list
2. Run: tyraj-misiu (no arguments)
3. Choose to view cards from all boards or a specific board
4. Select a card from the list using arrow keys
5. Press Enter
6. Agent implements changes and creates PR
7. Card is automatically moved to "DEV TESTING" column

Direct Mode

1. Create a Trello card with task description
2. Copy the card ID from URL (e.g., ABC123XY)
3. Run: tyraj-misiu --cardId=ABC123XY
4. Agent fetches card, implements changes, creates PR
5. Card is automatically moved to "DEV TESTING" column

Worktree Mode (Parallel Processing) 🆕

1. Create multiple cards in your Trello "To Do" list
2. Open 3-5 terminals
3. In each terminal: tyraj-misiu --worktree
4. Each agent:
   - Choose to filter by board (optional)
   - Shows interactive card list
   - Select different card in each terminal
   - Creates isolated git worktree in ~/.trello-agents/
   - Works independently without conflicts
   - Creates separate Pull Request
   - Moves card to "DEV TESTING" column
5. All agents can run simultaneously!

Benefits of Worktree Mode:

• ✅ Process multiple cards in parallel (3-5 agents)
• ✅ Full isolation - no file conflicts
• ✅ Each agent has own working directory
• ✅ Independent git branches
• ✅ Separate Pull Requests for each card
• ✅ Copy of .env for each agent

⚙️ Configuration

The tool looks for a .env file in the directory where you run the command (not in the tool directory).

Example .env:

# === Trello Configuration ===
TRELLO_KEY=xxxxx
TRELLO_TOKEN=xxxxx
# Customizable status names (optional)
TRELLO_TODO_STATUS=To Do
TRELLO_TESTING_STATUS=DEV TESTING

# === Jira Configuration ===
JIRA_HOST=https://yourcompany.atlassian.net
[email protected]
JIRA_API_TOKEN=xxxxx
# Customizable status names (optional)
JIRA_TODO_STATUS=To Do
JIRA_TESTING_STATUS=In Testing

# === Claude Configuration ===
# Subscription mode: Uses local Claude Code authentication (no API key needed)
# API mode: Requires API key below
# Get your API key at: https://console.anthropic.com/settings/keys
ANTHROPIC_API_KEY=sk-ant-xxxxx

# === GitHub Configuration ===
GITHUB_TOKEN=ghp_xxxxx
GITHUB_REPO_OWNER=yourname
GITHUB_REPO_NAME=yourrepo

How to get API keys:

• Trello: https://trello.com/app-key (Key + Token)
• Jira: https://id.atlassian.com/manage-profile/security/api-tokens (API Token)
• Anthropic: https://console.anthropic.com/settings/keys (optional - only for API mode)
• GitHub: https://github.com/settings/tokens (permissions: repo)

Important:

• Trello: Make sure you have a list matching TRELLO_TODO_STATUS (default: "To Do"). Cards will be moved to TRELLO_TESTING_STATUS (default: "DEV TESTING") after implementation.
• Jira: Make sure you have issues with status matching JIRA_TODO_STATUS (default: "To Do"). Issues will be moved to JIRA_TESTING_STATUS (default: "In Testing") after implementation.
• Provider Auto-Detection: The tool automatically detects which provider(s) you have configured based on .env variables.

🤖 Claude Processing Modes

The CLI supports two modes for Claude processing:

Subscription Mode (Default)

Uses your local Claude Code authentication. No API key required.

• ✅ Full file operations (Read, Write, Edit, Glob, Grep)
• ✅ Direct code implementation
• ⚠️ Limited by subscription token quota
• 💰 Included in Claude Code subscription ($20/month)

API Mode

Uses Anthropic API with pay-per-use pricing.

• ✅ No token quota limits (only rate limits)
• ✅ Pay only for what you use
• ⚠️ Limited to guidance only (no direct file operations)
• ⚠️ Requires ANTHROPIC_API_KEY in .env
• 💰 ~$0.003 - $0.015 per request (based on usage)

Token Exhaustion Handling

If your subscription tokens are exhausted during processing, you'll be prompted to switch to API mode. This allows you to complete your task without interruption.

How it works:

1. Select provider: Trello or Jira (if both configured)
2. Filter by board/project (optional - all or specific)
3. Select task (card/issue) with arrow keys
4. Choose Claude mode: Subscription or API
5. Claude processes the task
6. If subscription tokens exhausted → prompt to switch to API
7. Git operations → GitHub PR creation
8. Task automatically moved to testing status (DEV TESTING/In Testing)

📋 Requirements

• Node.js v18+ (uses ES Modules for inquirer)
• Claude Code - Installed and authenticated
• Git - Configured with GitHub access
• Task Provider - Trello (Key + Token) OR Jira (Host + Username + API Token)
• GitHub Token - Personal Access Token with repo permissions

🛠️ Installation & Setup

1. Install Claude Code (if you don't have it)

# Homebrew (macOS)
brew install --cask claude-code

# Or NPM globally
npm install -g @anthropic-ai/claude-code

2. Authenticate Claude Code

claude

Log in through your browser.

3. Get Your API Keys

Trello:

• Key: https://trello.com/app-key
• Token: Click "Token" on the same page

GitHub:

• Token: https://github.com/settings/tokens
• Permissions: repo (full access)

🎨 Example Trello Card

Card Title:

Add user authentication validation

Card Description:

Create a new file src/validators/auth.js with the following functions:

1. validateEmail(email) - Check if email is valid format
2. validatePassword(password) - Minimum 8 chars, 1 uppercase, 1 number
3. validateUsername(username) - 3-20 alphanumeric characters

Export these as named exports.
Add JSDoc comments for each function.

The agent will automatically:

1. Create the file src/validators/auth.js
2. Implement all validation functions
3. Add JSDoc documentation
4. Commit changes
5. Create a Pull Request

🌳 Worktree Management

List Active Worktrees

git worktree list

View Worktree Directories

ls -la ~/.trello-agents/

Cleanup Single Worktree

# After PR is merged:
git worktree remove ~/.trello-agents/agent-XXXXX-cardYYY/

Cleanup All Worktrees

# Remove all trello-agents worktrees:
git worktree list | grep .trello-agents | awk '{print $1}' | xargs -n1 git worktree remove

Worktree Info After Completion

After each worktree agent finishes, it shows:

🌳 Worktree Information:
   Path: /Users/you/.trello-agents/agent-1703001234567-cardABC123/
   Branch: feature-name

   To cleanup worktree manually, run:
   git worktree remove /Users/you/.trello-agents/agent-1703001234567-cardABC123/

Note: Worktrees are NOT automatically deleted after completion. This allows you to inspect results before cleanup.

🐛 Troubleshooting

Error: Cannot find module 'yargs/yargs'

npm install yargs

Error: Claude Agent not authenticated

claude

Log in again.

Error: Missing Trello keys in .env

Make sure the .env file is in the directory where you run the command (not in the CLI tool directory).

Git error: fatal: not a git repository

cd your-project
git init
git remote add origin https://github.com/username/yourrepo.git

Worktree: Already running inside a worktree

If you see:

⚠️  Already running inside a worktree. Worktree mode disabled.

This means you're already in a worktree directory. Run the command from the main repository instead:

cd /path/to/main/repo
tyraj-misiu --worktree

Worktree: Disk space issues

Worktrees create full copies of your repository. To free space:

# List all worktrees
git worktree list

# Remove unused ones
git worktree remove /path/to/worktree

📁 Project Structure

trello-claude-cli/          # CLI tool (standalone)
├── src/
│   ├── index.ts            # Main entry point (TypeScript)
│   ├── scripts/
│   │   ├── trello.ts       # Trello API integration
│   │   ├── claude.ts       # Claude Agent SDK (dual mode)
│   │   ├── git.ts          # Git operations (worktree support)
│   │   ├── github.ts       # GitHub PR creation
│   │   └── worktree.ts     # Git worktree management 🆕
│   └── types/
│       ├── claude.ts       # Claude types
│       └── worktree.ts     # Worktree types 🆕
├── dist/                   # Compiled JavaScript (auto-generated)
├── tsconfig.json           # TypeScript configuration
└── package.json

my-project/                  # Your project (normal mode)
├── .env                    # Configuration (API keys)
└── (Code will be created here)

~/.trello-agents/            # Worktree storage (parallel mode) 🆕
├── agent-1703001234567-cardABC123/   # Agent 1 workspace
│   ├── .git                # Git worktree metadata
│   ├── .env                # Copy from main repo
│   └── (Project files)
├── agent-1703001234789-cardDEF456/   # Agent 2 workspace
└── agent-1703001234890-cardGHI789/   # Agent 3 workspace

🔧 How It Works

Normal Mode

1. Loads .env from the directory where you run the command
2. Selects provider (Trello or Jira)
   • Auto-detect if only one configured
   • Interactive prompt if both configured
   • Or use --provider flag
3. Fetches task via provider API
   • Interactive mode: Filter by board/project (optional) → Select from list
   • Direct mode: Uses --cardId argument
4. Select Claude mode (Subscription or API)
5. Runs Claude to implement the task
   • Subscription mode: Agent creates files directly
   • API mode: Provides implementation guidance
6. Creates branch, commit, push
7. Opens Pull Request on GitHub
8. Moves task to testing status automatically (DEV TESTING for Trello, In Testing for Jira)

Worktree Mode (--worktree)

1. Loads .env from the directory where you run the command
2. Selects provider (Trello or Jira)
3. Fetches task via provider API
   • Interactive mode: Filter by board/project (optional) → Select from list
   • Direct mode: Uses --cardId argument
4. Creates isolated git worktree in ~/.trello-agents/agent-{timestamp}-{taskId}/
5. Copies .env to worktree for full isolation
6. Select Claude mode (Subscription or API)
7. Runs Claude in worktree directory (isolated from main repo)
   • All file operations happen in worktree
   • No conflicts with other agents
8. Creates branch, commit, push from worktree
9. Opens Pull Request on GitHub
10. Moves task to testing status automatically
11. Worktree remains for inspection (manual cleanup required)

💰 Costs

| What | Who Pays | How Much | |------|----------|----------| | npm publish | You (once) | 🆓 FREE | | npx download | FREE | 🆓 FREE | | Claude Code | Each user | $20/month | | Claude API | API key owner | ~$0.003 - $0.015 per request | | Trello API | FREE | 🆓 FREE | | GitHub API | FREE | 🆓 FREE |

🔄 Working with Existing Projects

The Claude Agent automatically analyzes existing files before making changes:

• ✅ Reads existing files - Uses Read tool
• ✅ Finds files by pattern - Uses Glob tool (e.g., **/*.ts)
• ✅ Searches code - Uses Grep tool (regex search)
• ✅ Edits existing files - Uses Edit tool (precise replacements)

The agent will:

1. Analyze the project structure
2. Read relevant files
3. Make targeted changes preserving your code style
4. Never overwrite files unnecessarily

🚀 GitHub Actions (Optional)

You can also run this as a GitHub Action. See .github/workflows/trello-to-pr.yml for example configuration.

📚 Additional Resources

• Trello API Documentation
• Claude Agent SDK
• GitHub REST API

💻 Development

This project is written in TypeScript. For development:

# Clone the repository
git clone https://github.com/dwantula/trello-claude-cli.git
cd trello-claude-cli

# Install dependencies
npm install

# Build TypeScript to JavaScript
npm run build

# Run in development mode (without building)
npm run dev

# The compiled files will be in the dist/ directory

🔧 CLI Options Reference

tyraj-misiu [options]

Options:
  --version   Show version number                                      [boolean]
  --cardId    Task ID - Trello Card ID or Jira Issue Key (optional - if not
              provided, shows interactive list)                         [string]
  --provider  Task provider to use (trello or jira) - optional, will auto-detect
              or prompt if not specified              [choices: "trello", "jira"]
  --dry-run   Test mode - fetch and display task without implementing changes
                                                      [boolean] [default: false]
  --worktree  Enable worktree mode - creates isolated git worktree in
              ~/.trello-agents/                       [boolean] [default: false]
  --help      Show help                                                [boolean]

Examples

# Interactive mode (provider auto-detected or prompted)
tyraj-misiu

# Specify provider explicitly
tyraj-misiu --provider=jira
tyraj-misiu --provider=trello

# Direct task ID with provider
tyraj-misiu --cardId=PROJ-123 --provider=jira
tyraj-misiu --cardId=ABC123 --provider=trello

# Dry-run mode (test without making changes)
tyraj-misiu --dry-run
tyraj-misiu --cardId=PROJ-123 --provider=jira --dry-run

# Worktree mode for parallel processing
tyraj-misiu --worktree
tyraj-misiu --worktree --provider=jira

# Combine all options
tyraj-misiu --cardId=PROJ-123 --provider=jira --worktree --dry-run

📄 License

MIT

🤝 Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.

🔐 Security

• Never commit API keys to the repository
• Test on a separate branch/test repo first
• Review changes before merging
• Keep your .env file in .gitignore

Made with ❤️ using Claude Code