Skip to content

README.md

Latest commit

 

History

History
660 lines (506 loc) · 18 KB

README.md

File metadata and controls

660 lines (506 loc) · 18 KB

entrust

Automate your development workflow from task tracker to pull request using Claude Code

entrust is a Swift CLI tool that automates the entire development workflow: fetch tasks from JIRA or Linear, implement them using Claude Code AI, run tests with automatic retry, and create pull requests - all with a single command. It also handles PR feedback iteration by continuing Claude Code sessions automatically.

Swift 6.0+ Platform License

✨ Features

  • 🎫 Task Tracker Integration: Fetch tasks from JIRA or Linear with full context
  • 🤖 Claude Code Automation: AI implements features with real-time streaming output
  • 💬 PR Feedback Loop: Address reviewer feedback by continuing Claude sessions
  • 🔄 Automatic Test Retry: Runs tests and asks Claude to fix failures (configurable retries)
  • 🌿 Git Worktrees: Isolated execution environments prevent conflicts
  • ⚡ Parallel Processing: Process multiple tickets concurrently
  • 📝 Smart PR Summaries: Auto-generates structured PR descriptions with context
  • 🔧 Session Management: View and continue previous Claude Code sessions
  • 🔐 Project-Level Config: Each project has its own configuration and credentials
  • 🔍 Auto-Detection: Automatically detects GitHub org/repo from git remote

🚀 Installation

Prerequisites

  • macOS 15.0+ or Linux (Ubuntu 20.04+, other distributions)
    • macOS: Uses Keychain for secure credential storage (project-specific)
    • Linux: Uses file-based storage in .entrust/credentials/ with secure permissions (project-specific)
  • Swift 6.0+
  • Claude Code installed (claude --version)
  • Git configured
  • JIRA or Linear account
  • GitHub account with gh CLI (optional, can use API tokens)

Via Mint (Recommended for macOS)

Mint is a package manager for Swift command-line tools.

# Install Mint if you haven't already
brew install mint

# Install entrust
mint install mfxstudios/entrust

Build from Source (macOS & Linux)

On macOS:

git clone https://github.com/mfxstudios/entrust.git
cd entrust
swift build -c release
cp .build/release/entrust /usr/local/bin/

On Linux:

# Install Swift 6.0+ if not already installed
# See: https://swift.org/download/

git clone https://github.com/mfxstudios/entrust.git
cd entrust
swift build -c release
sudo cp .build/release/entrust /usr/local/bin/

Verify Installation

entrust --version
entrust --help

🎯 Quick Start

1. Initial Setup

Navigate to your project directory and configure your task tracker and GitHub credentials:

cd /path/to/your/project
entrust setup

Important: Configuration is project-specific. Run entrust setup in each project directory where you want to use entrust.

You'll be prompted for:

  • Task tracker type (jira/linear)
  • JIRA URL and email (if using JIRA)
  • GitHub repository (auto-detected from git remote, or enter manually)
  • Base branch (default: main)
  • API tokens (stored securely - Keychain on macOS, .entrust/credentials/ on Linux)

This creates:

  • .env - Project configuration file
  • .entrust/credentials/ (Linux only) - Encrypted credential storage

Add to .gitignore:

.env
.entrust/

2. Process a Single Task

# Fetch ticket IOS-1234, implement it with Claude, create PR
entrust run IOS-1234

# With options
entrust run IOS-1234 --draft --skip-tests

# Run in a new terminal window (keeps your current terminal free)
entrust run IOS-1234 --new-terminal

3. Process Multiple Tasks in Parallel

# Process 3 tickets concurrently
entrust parallel IOS-1234 IOS-1235 IOS-1236

# From a file with custom concurrency
entrust parallel --file tickets.txt --max-concurrent 5

4. Address PR Feedback

When reviewers leave feedback on your PR:

# Address feedback on PR #456
entrust feedback 456

# Or using full URL
entrust feedback https://github.com/myorg/myrepo/pull/456

📚 Commands

setup

Configure task tracker and GitHub credentials.

entrust setup          # Interactive configuration
entrust setup --show   # Display current settings (tokens hidden)
entrust setup --clear  # Clear all configuration and credentials

Project-Level Configuration:

  • Configuration is stored per-project in .env file in the current directory
  • Credentials are stored project-specifically (macOS Keychain uses project path hash, Linux uses .entrust/credentials/)
  • Each project can have different JIRA instances, GitHub repos, and settings
  • Run entrust setup in each project directory where you want to use entrust

Auto-detection:

  • When run from a git repository, setup automatically detects the GitHub org/repo from the origin remote
  • Supports both SSH (git@github.com:org/repo.git) and HTTPS (https://github.com/org/repo.git) formats
  • Simply press Enter to accept the detected value, or type a different org/repo to override

run

Process a single task using an isolated git worktree.

entrust run <task-id> [options]

Options:
  --draft                 Create PR as draft
  --skip-tests            Skip running tests
  --new-terminal          Run Claude Code in a new terminal window
  --repo-root <path>      Repository root directory

Workflow:

  1. Creates isolated worktree in /tmp/entrust-<ticket>-<uuid>
  2. Fetches task from JIRA/Linear
  3. Updates ticket status to "In Progress"
  4. Runs Claude Code with streaming output
  5. Runs tests with automatic retry on failure (up to 3 attempts)
  6. Commits and pushes changes
  7. Creates pull request with structured description
  8. Updates ticket status to "In Review"
  9. Cleans up worktree

Interactive Mode (--interactive)

NEW! Guide Claude through implementation interactively with real-time chat, then auto-complete with tests & PR.

entrust run <task-id> --interactive [options]

Workflow:

  1. Fetches task from JIRA/Linear
  2. Updates ticket status to "In Progress"
  3. Starts interactive chat session - you guide Claude conversationally
  4. Type done or finish when ready to proceed
  5. Automated completion: runs tests, commits, pushes, creates PR
  6. Updates ticket status to "In Review"

Example session:

$ entrust run IOS-1234 --interactive

🎯 Interactive Mode - IOS-1234
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 Task: Add dark mode support
💬 Starting Interactive Session

Commands:
  • Type your messages to guide Claude
  • Type 'done' or 'finish' to end and proceed to automation
  • Type 'cancel' to exit without automation

🤖 Claude:
I'll help you add dark mode support. Let me start by...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
You: Let's use a theme manager pattern instead

🤖 Claude:
Good idea! I'll refactor to use a ThemeManager...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
You: done

✅ Interactive session complete!

🤖 Starting Automation Flow
🧪 Running tests...
✅ Tests passed
🌿 Creating branch: feature/IOS-1234
📬 Creating pull request...
✅ Complete!

Use cases:

  • Complex features that need iterative refinement
  • Learning how Claude approaches problems
  • Situations requiring human judgment during implementation
  • Debugging tricky issues step-by-step

parallel

Process multiple tasks concurrently using isolated worktrees.

entrust parallel <task-id> [<task-id> ...] [options]

Options:
  --file <path>           Read ticket IDs from file (one per line)
  --max-concurrent <n>    Maximum concurrent tasks (default: 3)
  --draft                 Create PRs as drafts
  --skip-tests            Skip running tests
  --new-terminal          Run each ticket in a separate terminal window
  --interactive           Interactive mode (auto-enables --new-terminal)

Examples:

# Process specific tickets
entrust parallel IOS-1234 IOS-1235 IOS-1236

# Process from file with higher concurrency
entrust parallel --file sprint-tickets.txt --max-concurrent 5

# Create draft PRs for review
entrust parallel IOS-1234 IOS-1235 --draft

# Launch each ticket in its own terminal window (best for monitoring)
entrust parallel IOS-1234 IOS-1235 IOS-1236 --new-terminal

# Interactive mode for multiple tickets - guide Claude in each terminal
entrust parallel IOS-1234 IOS-1235 --interactive

Notes:

  • When using --new-terminal, each ticket runs in a dedicated terminal window instead of using worktree-based parallelization. This provides better visibility but doesn't enforce the --max-concurrent limit.
  • --interactive automatically enables --new-terminal and launches each ticket with interactive mode, allowing you to guide Claude separately in each terminal window.

feedback

Address PR feedback by continuing the Claude Code session.

entrust feedback <pr-number or url> [options]

Options:
  --repo-root <path>      Repository root directory
  --all                   Process all comments (including previously processed)

How it works:

  • Fetches PR comments from GitHub API
  • Filters actionable comments:
    • All comments from "Request Changes" reviews
    • Any comment containing **entrust** or entrust: trigger
  • Continues the original Claude Code session with feedback
  • Runs tests with automatic retry
  • Commits and pushes fixes
  • Tracks processed comments to avoid duplicates

Reviewer triggers:

<!-- In a PR review -->
**entrust** please add error handling here

<!-- Or with prefix -->
entrust: refactor this to use async/await

<!-- Or just mark review as "Request Changes" -->
This needs better validation

continue

Continue a previous Claude Code session with additional instructions.

entrust continue <session-id or "latest"> <prompt>

Options:
  --working-directory <path>   Working directory for the session

Examples:

# Continue latest session
entrust continue latest "Add documentation to the new functions"

# Continue specific session
entrust continue abc123def "Fix the failing test"

sessions

View Claude Code session history.

entrust sessions [options]

Options:
  --project <path>        Filter sessions by project path
  --verbose               Show detailed session information
  --limit <n>             Limit number of sessions to show

status

Change ticket status manually.

entrust status <ticket-id> <status>

Example:
  entrust status IOS-1234 "In Review"

⚙️ Configuration

Configuration File

Settings are stored in .env files. Priority order:

  1. .env in current directory (project-specific)
  2. ~/.entrust/.env (global configuration)

Example .env for JIRA:

# Task Tracker Settings
TRACKER_TYPE=jira
JIRA_URL=https://your-company.atlassian.net
JIRA_EMAIL=you@company.com

# GitHub Settings
GITHUB_REPO=your-org/your-repo
BASE_BRANCH=main
USE_GH_CLI=true
AUTO_CREATE_DRAFT=false

# AI Agent Settings
AI_AGENT_TYPE=claude-code

# Execution Settings
RUN_TESTS_BY_DEFAULT=true
MAX_RETRY_ATTEMPTS=3
USE_NEW_TERMINAL=false

Example .env for Linear:

# Task Tracker Settings
TRACKER_TYPE=linear

# GitHub Settings
GITHUB_REPO=your-org/your-repo
BASE_BRANCH=main
USE_GH_CLI=true
AUTO_CREATE_DRAFT=false

# AI Agent Settings
AI_AGENT_TYPE=claude-code

# Execution Settings
RUN_TESTS_BY_DEFAULT=true
MAX_RETRY_ATTEMPTS=3
USE_NEW_TERMINAL=false

Credentials (Keychain)

API tokens are never stored in .env files. They're stored securely in macOS Keychain:

  • JIRA API token: Required when TRACKER_TYPE=jira
  • Linear API token: Required when TRACKER_TYPE=linear
  • GitHub token: Required when USE_GH_CLI=false

Run entrust setup to configure credentials securely.

Test Retry Configuration

Control automatic test retry behavior:

# In .env file
MAX_RETRY_ATTEMPTS=3  # Default: 3, Range: 0-10

# 0 = No retry (fail immediately)
# 1 = Retry once
# 3 = Retry up to 3 times (recommended)

New Terminal Mode

Run Claude Code in a separate terminal window to keep your current terminal free:

# In .env file
USE_NEW_TERMINAL=true  # Default: false

# Or use the command-line flag (single ticket)
entrust run IOS-1234 --new-terminal

# For parallel processing (each ticket in its own window)
entrust parallel IOS-1234 IOS-1235 IOS-1236 --new-terminal

How it works:

  • macOS: Automatically detects and uses Terminal.app or iTerm2
  • Linux: Supports gnome-terminal, konsole, xfce4-terminal, and xterm
  • The original terminal returns immediately while Claude Code runs in the new window
  • The new window stays open after completion so you can review the output
  • With parallel --new-terminal, each ticket gets its own dedicated window

Use cases:

  • Working on multiple tickets simultaneously (each in its own window)
  • Keeping your main terminal free for other commands
  • Better visibility of Claude Code's streaming output
  • Easier to monitor long-running tasks
  • Visual separation when processing multiple tickets

🔄 Workflows

Single Task Workflow

entrust run IOS-1234
    ↓
[Create worktree] → /tmp/entrust-IOS-1234-abc123
    ↓
[Fetch task] → "Add user authentication"
    ↓
[Update status] → "In Progress"
    ↓
[Run Claude Code] → Streaming implementation
    ↓
[Run tests] → PASSED ✓
    ↓
[Commit & push] → feature/IOS-1234
    ↓
[Create PR] → github.com/org/repo/pull/456
    ↓
[Update status] → "In Review"
    ↓
[Cleanup worktree]

Test Retry Workflow

[Run tests]
    ↓
FAILED ✗ → "Expected 200, got 404"
    ↓
[Attempt 1/3] → Continue Claude session with error
    ↓
Claude analyzes error and fixes code
    ↓
[Run tests again]
    ↓
FAILED ✗ → "Timeout on line 45"
    ↓
[Attempt 2/3] → Continue with new error
    ↓
Claude fixes timeout issue
    ↓
[Run tests again]
    ↓
PASSED ✓ → Tests succeed!

PR Feedback Workflow

[PR #456 created]
    ↓
Reviewer adds feedback:
  - "Request Changes" review with 3 comments
  - General comment: "**entrust** add error handling"
    ↓
entrust feedback 456
    ↓
[Fetch PR comments] → 4 actionable comments
    ↓
[Load session] → abc123def (from PR metadata)
    ↓
[Recreate worktree] → feature/IOS-1234
    ↓
[Continue Claude session] → "Address the following feedback: ..."
    ↓
[Run tests] → PASSED ✓
    ↓
[Commit & push] → "[IOS-1234] Address PR feedback"
    ↓
[Mark comments processed] → Track IDs to avoid duplicates

Parallel Workflow

entrust parallel IOS-1234 IOS-1235 IOS-1236 --max-concurrent 3
    ↓
[Create 3 worktrees in parallel]
  ├─ /tmp/entrust-IOS-1234-abc
  ├─ /tmp/entrust-IOS-1235-def
  └─ /tmp/entrust-IOS-1236-ghi
    ↓
[Process concurrently]
  ├─ [IOS-1234] Fetching... Running Claude... Testing... ✓
  ├─ [IOS-1235] Fetching... Running Claude... Testing... ✓
  └─ [IOS-1236] Fetching... Running Claude... Testing... ✓
    ↓
[Summary Report]
  ✓ 3 succeeded
  ✗ 0 failed
  → 3 PRs created

🏗️ Architecture

Project Structure

Sources/entrust/
├── AIAgent/              # Claude Code SDK integration
│   └── AIAgent.swift     # Streaming execution with AsyncSequence
├── TaskTracker/          # Task management
│   ├── JIRA/            # JIRA API integration
│   └── Linear/          # Linear API integration
├── Managers/            # Core services
│   ├── GitHubService.swift       # PR creation, comments, worktrees
│   ├── ConfigurationManager.swift # .env file management
│   └── KeychainManager.swift     # Secure credential storage
├── Storage/             # Session persistence
│   └── PRSessionStorage.swift    # PR/session mapping
├── Subcommands/         # CLI commands
│   ├── Run.swift
│   ├── Parallel.swift
│   ├── Feedback.swift   # NEW: PR feedback handling
│   ├── Continue.swift
│   ├── Sessions.swift
│   ├── Setup.swift
│   └── Status.swift
└── TicketAutomation.swift        # Main workflow orchestration

Key Components

Claude Code Integration:

  • Uses claude-code-sdk-swift
  • Real-time streaming output with AsyncSequence
  • Automatic backend detection (Agent SDK or Headless)
  • Session management for conversation continuation

Git Worktrees:

  • Isolated execution in /tmp/entrust-<ticket>-<uuid>
  • No conflicts between parallel tasks
  • Clean state for each task
  • Easy debugging with --keep-worktree

Test Retry System:

  • Configurable retry attempts (0-10)
  • Multi-turn conversation with Claude
  • Provides error context on each retry
  • Automatic cleanup on success

PR Feedback System:

  • Session ID stored in PR description (HTML comment)
  • Local session database (~/.entrust/pr-sessions.json)
  • Comment filtering with triggers
  • Tracks processed comments to avoid duplicates

🧪 Development

Running Tests

swift test                    # Run all tests
swift test --parallel         # Run tests in parallel

Test Coverage:

  • 142 tests across 66 test suites
  • Unit tests for all core functionality
  • BDD-style tests with Given/When/Then naming
  • Tests for PR feedback filtering, session storage, and streaming

Building

swift build                   # Debug build
swift build -c release        # Release build

Testing Locally

# Build and run
swift build
.build/debug/entrust --help

# Test with a real ticket
.build/debug/entrust run TEST-123 --skip-tests

# Install locally with Mint (for testing installation)
mint install . --force

📄 License

MIT License