Skip to content

installation.md

Latest commit

 

History

History
895 lines (655 loc) · 24.8 KB

installation.md

File metadata and controls

895 lines (655 loc) · 24.8 KB

Installation Guide

Supported Platforms

DevAIFlow officially supports:

  • macOS (Intel and Apple Silicon)
  • Linux (Ubuntu, Debian, Fedora, RHEL, etc.)
  • Windows 10/11 (see Windows Installation below)

Prerequisites

Required

  • Python 3.10, 3.11, or 3.12

    python --version  # Check your version

    Note: Python 3.9 may work but is not officially tested. Python 3.13+ has not been tested yet.

  • Claude Code CLI (version 2.1.3 or higher)

  • Git

    git --version  # Should be 2.x or higher

Optional (for PR/MR Creation and Template Fetching)

  • GitHub CLI (gh)

    • Install from: https://cli.github.com/
    • Verify: gh --version
    • Required for:
      • Creating GitHub pull requests via daf complete
      • Fetching PR templates from private GitHub repositories
    • Setup: gh auth login

  • GitLab CLI (glab)

    • Install from: https://gitlab.com/gitlab-org/cli
    • Verify: glab --version
    • Required for:
      • Creating GitLab merge requests via daf complete
      • Fetching MR templates from private GitLab repositories
    • Setup: glab auth login

Optional (for Issue Tracker Integration)

  • GitHub CLI (gh) - For GitHub Issues integration (see above)
  • GitLab CLI (glab) - For GitLab Issues integration (see above)
  • JIRA API Token - For JIRA integration
    • Only needed if you want JIRA integration
    • GitHub and GitLab use their respective CLIs instead
    • Without any issue tracker, the tool works for local session management only

Installation Methods

Method 1: From PyPI (Recommended)

Install the latest stable release from PyPI:

pip install devaiflow

Verify installation:

daf --version
daf --help

Check dependencies:

daf init --check

This will verify all required and optional tools are installed. See Verifying Dependencies below.

Method 2: From Source (Development)

For development or contributing:

# Clone the repository
git clone https://github.com/itdove/devaiflow.git
cd devaiflow

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

Windows Installation

DevAIFlow is fully supported on Windows 10 and Windows 11. Follow these steps for Windows-specific installation.

Prerequisites for Windows

  1. Python 3.10, 3.11, or 3.12

    # Check if Python is installed
python --version

# If not installed, download from python.org or use winget:
winget install Python.Python.3.12

  2. Claude Code CLI

    # Install using winget
winget install Anthropic.Claude

# Verify installation
claude --version

  3. Git for Windows

    # Install using winget
winget install Git.Git

# Verify installation
git --version

  4. Optional: GitHub CLI

    # Install using winget
winget install GitHub.cli

# Verify and authenticate
gh --version
gh auth login

  5. Optional: GitLab CLI

Installing DevAIFlow on Windows

Using PowerShell:

# Navigate to the repository
cd C:\Users\YourUsername\development\devaiflow

# Install using pip
pip install .

# Verify installation
daf --version
daf init --check

Using Command Prompt:

# Navigate to the repository
cd C:\Users\YourUsername\development\devaiflow

# Install using pip
pip install .

# Verify installation
daf --version
daf init --check

Windows-Specific Configuration

Environment Variables:

Set environment variables in PowerShell (add to your PowerShell profile for persistence):

# Edit your PowerShell profile
notepad $PROFILE

# Add these lines:
$env:JIRA_API_TOKEN = "your-api-token-here"
$env:JIRA_URL = "https://jira.example.com"

# Save and reload:
. $PROFILE

Or set them permanently via System Properties:

  1. Search for "Environment Variables" in Windows Start menu
  2. Click "Environment Variables" button
  3. Add new User variables:
    • Name: JIRA_API_TOKEN, Value: your token
    • Name: JIRA_URL, Value: your JIRA URL

Windows Path Configuration

Ensure Python Scripts directory is in your PATH:

# Check if Python Scripts is in PATH
$env:PATH -split ';' | Select-String "Python.*Scripts"

# If not found, add it (typical location):
$env:PATH += ";C:\Users\YourUsername\AppData\Local\Programs\Python\Python312\Scripts"

To make it permanent:

  1. Search for "Environment Variables" in Windows Start menu
  2. Edit the "Path" variable
  3. Add: C:\Users\YourUsername\AppData\Local\Programs\Python\Python312\Scripts

Windows Testing Requirements

Integration Tests on Windows:

Integration tests (test_collaboration_workflow.sh, test_jira_green_path.sh) require bash and are not supported natively on Windows. Options:

  1. WSL (Windows Subsystem for Linux) - Recommended

    # Install WSL
wsl --install

# Run tests in WSL
wsl
cd /mnt/c/Users/YourUsername/development/devaiflow
./integration-tests/test_collaboration_workflow.sh

  2. Git Bash

    • Comes with Git for Windows
    • Open Git Bash terminal
    • Navigate to repository
    • Run: ./integration-tests/test_collaboration_workflow.sh

  3. Skip Integration Tests

    • Unit tests work natively on Windows
    • Integration tests are optional for development
    • CI/CD covers integration testing

Known Windows-Specific Behaviors

File Locking:

  • Windows file locking works differently from Unix systems
  • DevAIFlow automatically disables fcntl-based file locking on Windows
  • Session files use atomic write operations instead
  • No action required - handled automatically

Path Separators:

  • DevAIFlow uses pathlib.Path for cross-platform path handling
  • Both forward slashes (/) and backslashes (\) work correctly
  • Long path support (>260 characters) is automatically handled

Signal Handling:

  • Windows uses SIGBREAK instead of Unix SIGTERM
  • DevAIFlow automatically uses the correct signal for your platform
  • Ctrl+C works as expected to interrupt operations

Troubleshooting Windows Installation

Problem: daf: command not found

Solution:

# Ensure Python Scripts is in PATH
python -m pip show devaiflow
# Note the "Location" path
# Add Location\Scripts to your PATH environment variable

Problem: ModuleNotFoundError: No module named 'devflow'

Solution:

# Reinstall the package
pip uninstall devaiflow
pip install .

Problem: Permission errors during installation

Solution:

# Install for current user only
pip install --user .

Problem: Git commands fail with "git: command not found"

Solution:

# Ensure Git is in PATH
git --version

# If not found, add Git to PATH:
# Typical location: C:\Program Files\Git\cmd

Problem: Claude Code doesn't launch from PowerShell

Solution:

# Verify Claude is in PATH
claude --version

# If not found, find installation directory:
Get-Command claude -ErrorAction SilentlyContinue

# Add to PATH if needed

For more troubleshooting, see Windows Troubleshooting Guide.

Setting Up Issue Tracker Integration (Optional)

GitHub Issues (Recommended - Easiest Setup)

If you authenticated the GitHub CLI (gh auth login) as shown in the Prerequisites section, you're already set up! No additional configuration needed.

# Verify authentication
gh auth status

# Test by viewing your issues
gh issue list --assignee @me

See the GitHub Issue Integration Guide for complete documentation.

GitLab Issues

If you authenticated the GitLab CLI (glab auth login), you're ready to go!

# Verify authentication
glab auth status

# Test by viewing your issues
glab issue list --assignee @me

JIRA Integration

Skip this section if you're using GitHub or GitLab Issues instead.

The tool uses the JIRA REST API directly - no additional CLI tools are needed!

1. Get JIRA API Token

For Atlassian Cloud (https://yourcompany.atlassian.net):

  1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
  2. Click "Create API token"
  3. Give it a name (e.g., "DevAIFlow")
  4. Copy the token (you won't see it again!)

For Enterprise JIRA or Self-Hosted:

  1. Go to your JIRA instance → Profile → Personal Access Tokens
  2. Create a new token
  3. Copy the token value

2. Configure Environment Variables

⚠️ IMPORTANT: Authentication setup differs between Cloud and Self-Hosted JIRA.

For Atlassian Cloud:

Add these to your shell profile (~/.bashrc, ~/.zshrc, ~/.profile, etc.):

# Step 1: Create base64-encoded credentials (email:token)
# Replace with YOUR email and token from step 1
echo -n "user@company.com:your-api-token" | base64

# Step 2: Add to shell profile
# CRITICAL: JIRA_AUTH_TYPE=basic is required for Cloud
export JIRA_AUTH_TYPE=basic
export JIRA_API_TOKEN="<base64-output-from-above>"
export JIRA_URL="https://yourcompany.atlassian.net"

For Self-Hosted JIRA:

Add these to your shell profile:

# For self-hosted JIRA, use Bearer authentication
export JIRA_AUTH_TYPE=Bearer
export JIRA_API_TOKEN="your-personal-access-token"
export JIRA_URL="https://jira.example.com"

Optional debugging:

# Enable debug logging for JIRA API calls (troubleshooting)
export DEVAIFLOW_DEBUG=1

Reload your shell:

source ~/.zshrc  # or ~/.bashrc, ~/.profile, etc.

3. Verify JIRA Setup

# Test authentication with curl
curl -H "Authorization: Basic $JIRA_API_TOKEN" \
     "$JIRA_URL/rest/api/2/myself"

# If successful, test DevAIFlow integration
daf sync --dry-run

✅ If this shows your JIRA tickets, the integration is working!

Configuring DevAIFlow

1. Initialize Configuration

daf init

This launches an interactive preset-based wizard that:

  • Auto-detects your issue tracker from git remotes and environment variables
  • Preset selection - Choose your primary use case:
    • GitHub Issues - Auto-detected from GitHub remotes, ≤3 questions
    • GitLab Issues - Auto-detected from GitLab remotes, ≤3 questions
    • JIRA - Auto-detected from JIRA_API_TOKEN, ≤5 questions
    • Local sessions only - No issue tracker, 1 question (workspace path)
    • Custom configuration - Full wizard for advanced users
  • Creates configuration files (automatically, no manual file creation needed):
    • config.json - Personal preferences (workspace, prompts, GitHub/GitLab settings)
    • backends/jira.json - JIRA URL and field mappings (if using JIRA)
    • organization.json - JIRA project key and transitions (if using JIRA)
    • team.json - Team defaults (workstream, component, comment visibility)
    • enterprise.json - Enterprise-wide settings (optional)
  • Shows next steps with preset-specific commands to get started immediately

Preset examples:

  • GitHub (≤3 questions): Workspace path + optional labels + auto-close setting
  • GitLab (≤3 questions): Workspace path + optional labels + auto-close setting
  • JIRA (≤5 questions): JIRA URL + project + workspace + comment visibility
  • Local (1 question): Workspace path only

All settings can be changed later using daf config edit.

Configuration Files Created

File Purpose Key Settings
backends/jira.json JIRA backend configuration JIRA URL, field mappings (API metadata)
organization.json Organization settings JIRA project key, transitions, parent_field_mapping, sync filters
team.json Team-specific settings Default workstream, component, comment visibility
config.json User personal preferences Workspace path, prompts, context files

Post-Init Configuration Checklist

After running daf init, verify and customize your configuration:

  1. Verify JIRA URL in backends/jira.json

    # Check JIRA URL is correct
daf config show --format split | grep url

  2. Set JIRA project key in organization.json

    # Verify your default project key
daf config show --format split | grep jira_project

  3. Configure team defaults in team.json (optional)

    # Add default workstream, component, or other team-specific values
vim $DEVAIFLOW_HOME/team.json

  4. Set workspace path in config.json

    # Verify your workspace path for repository discovery
daf config show --format split | grep workspace

  5. Test JIRA connection

    # Verify JIRA integration works
daf sync --dry-run

For detailed configuration options and multi-file structure, see Multi-File Configuration System.

2. Install Claude Code Skills

After initializing configuration, install the DevAIFlow skills into Claude Code:

daf skills

This installs all bundled skills globally to ~/.claude/skills/:

  • Slash commands (/daf-*) - Skills with name: field in frontmatter (e.g., /daf-help, /daf-list, /daf-status)
  • Reference skills - Skills without name: field that are auto-loaded (e.g., daf-cli, gh-cli, git-cli, glab-cli)

These enable you to use DevAIFlow features directly within Claude Code sessions.

Example usage:

# Preview what would be installed
daf skills --dry-run

# Install all skills (slash commands + reference skills)
daf skills

Note: Skills are installed globally to ~/.claude/skills/ and are available in all Claude Code sessions. Claude Code 2.1.3+ is required for slash command support.

3. Edit Configuration (Optional)

Edit $DEVAIFLOW_HOME/config.json:

{
  "jira": {
    "url": "https://jira.example.com",
    "user": "your-username",
    "transitions": {
      "on_start": {
        "from": ["New", "To Do"],
        "to": "In Progress",
        "prompt": false,
        "on_fail": "warn"
      },
      "on_complete": {
        "prompt": true
      }
    },
    "time_tracking": true
  },
  "repos": {
    "workspace": "/Users/your-username/development/workspace",
    "detection": {
      "method": "keyword_match",
      "fallback": "prompt"
    },
    "keywords": {
      "workspace-management-service": ["backup", "restore", "subscription"],
      "workspace-sops": ["terraform", "github", "custom-properties"]
    }
  }
}

Key Settings:

  • jira.url - Your JIRA instance URL (in backends/jira.json)
  • jira.transitions - Auto-transition configuration (in organization.json)
  • repos.workspace - Your main development directory
  • repos.keywords - Keywords for smart repository detection

See Configuration Reference for detailed configuration options.

3. Set Up Shell Completion (Optional)

Enable tab completion for the daf command:

Bash:

# Add to ~/.bashrc
eval "$(_DAF_COMPLETE=bash_source daf)"

# Reload
source ~/.bashrc

Zsh:

# Add to ~/.zshrc
eval "$(_DAF_COMPLETE=zsh_source daf)"

# Reload
source ~/.zshrc

Fish:

# Save to completion file
_DAF_COMPLETE=fish_source daf > ~/.config/fish/completions/daf.fish

Verifying Installation

Check Dependencies

After installation, verify all required and optional tools are installed:

daf init --check

Expected output:

Checking dependencies for DevAIFlow...

Required Dependencies:
┏━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┓
┃ Tool   ┃ Status ┃ Version         ┃ Description          ┃
┡━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━┩
│ git    │ ✓      │ git version ... │ Git version control  │
│ claude │ ✓      │ claude 1.2.3    │ Claude Code CLI      │
└────────┴────────┴─────────────────┴──────────────────────┘

Optional Dependencies:
┏━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Tool  ┃ Status ┃ Version       ┃ Description               ┃
┡━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ gh    │ ✓      │ gh 2.40.1     │ GitHub CLI                │
│ glab  │ ✓      │ glab 1.35.0   │ GitLab CLI                │
│ pytest│ ✓      │ pytest 7.4.3  │ Python testing framework  │
└───────┴────────┴───────────────┴───────────────────────────┘

✓ All required dependencies available

If any required tools are missing:

Verify Basic Functionality

Run these commands to verify everything is set up:

# 1. Check daf is installed
daf --version

# 2. Check daf can find config
daf list  # Should show empty list or existing sessions

# 3. Test JIRA integration (if configured)
daf sync --dry-run  # Preview what would be synced

Troubleshooting Installation

Python Version Issues

Error: python: command not found

Solution:

# Try python3
python3 --version

# If that works, create an alias
alias python=python3

Permission Denied

Error: Permission denied when installing

Solution:

# Use --user flag
pip install --user .

JIRA Authentication Fails

Error: Authentication failed or 401 Unauthorized or JIRA_API_TOKEN not set

Solutions:

  1. Verify token is set: echo $JIRA_API_TOKEN
  2. Check token hasn't expired
  3. For Enterprise JIRA, ensure you're using Personal Access Token (not API token)
  4. Reload your shell: source ~/.zshrc
  5. Test with: daf sync --dry-run

Config File Not Found

Error: Config file not found

Solution:

# Create it
daf init

# Verify location
ls $DEVAIFLOW_HOME/config.json

Upgrading

Upgrading from PyPI (recommended)

pip install --upgrade devaiflow

Upgrading from source

cd ~/development/workspace/devaiflow
git pull  # Get latest code
pip install --upgrade .

Uninstalling

pip uninstall devaiflow

Remove Data (Optional)

# Backup first!
cp -r $DEVAIFLOW_HOME $DEVAIFLOW_HOME.backup

# Remove all data
rm -rf $DEVAIFLOW_HOME

Note: This does NOT delete your Claude Code conversation files in ~/.claude/projects/.

Configuring Claude Code Permissions

CRITICAL: Claude Code must be configured to allow reading context files from $DEVAIFLOW_HOME/ and $DEVAIFLOW_HOME/. Without this, the tool will fail when Claude tries to read organization context files.

Why This Matters

DevAIFlow creates context files in $DEVAIFLOW_HOME/ that Claude Code automatically reads when you run daf open or daf jira new:

  • $DEVAIFLOW_HOME/backends/JIRA.md - JIRA integration rules
  • $DEVAIFLOW_HOME/ENTERPRISE.md - Enterprise-wide policies and standards
  • $DEVAIFLOW_HOME/ORGANIZATION.md - Organization-wide standards (JIRA templates, Wiki markup requirements)
  • $DEVAIFLOW_HOME/TEAM.md - Team conventions
  • $DEVAIFLOW_HOME/USER.md - Personal notes and preferences

By default, Claude Code may block access to these directories because they are dotfiles (start with .).

CRITICAL: These files must be readable from ALL working directories, including temporary directories created by daf jira new. This is why the allow list MUST be in the global ~/.claude/settings.json, not in project-specific settings files.

Required Configuration

Add file access permissions to your global Claude Code settings file:

Location: ~/.claude/settings.json

IMPORTANT: Use the global settings file (~/.claude/settings.json), NOT the project-local file (.claude/settings.local.json). Project-local settings files are typically not committed to version control and won't be available when using daf jira new or when other team members clone the repository.

Add this configuration:

{
  "permissions": {
    "allow": [
      "Read($DEVAIFLOW_HOME/ENTERPRISE.md)",
      "Read($DEVAIFLOW_HOME/ORGANIZATION.md)",
      "Read($DEVAIFLOW_HOME/TEAM.md)",
      "Read($DEVAIFLOW_HOME/USER.md)"
    ]
  }
}

IMPORTANT: Replace $DEVAIFLOW_HOME with your actual DevAIFlow home directory:

  • Default location: ~/.daf-sessions (if you haven't customized it)
  • Custom location: Use the value of your DEVAIFLOW_HOME environment variable

Example with default location:

{
  "permissions": {
    "allow": [
      "Read(~/.daf-sessions/ENTERPRISE.md)",
      "Read(~/.daf-sessions/ORGANIZATION.md)",
      "Read(~/.daf-sessions/TEAM.md)",
      "Read(~/.daf-sessions/USER.md)"
    ]
  }
}

Step-by-Step Setup

  1. Create or edit the settings file: 
    # Check if file exists
ls ~/.claude/settings.json

# If not, create it (using default ~/.daf-sessions location)
mkdir -p ~/.claude
cat > ~/.claude/settings.json << 'EOF'

{ "permissions": { "allow": [ "Read(/.daf-sessions/ENTERPRISE.md)", "Read(/.daf-sessions/ORGANIZATION.md)", "Read(/.daf-sessions/TEAM.md)", "Read(/.daf-sessions/USER.md)" ] } } EOF


**Note:** If you set a custom `DEVAIFLOW_HOME` environment variable, replace `~/.daf-sessions` with your custom path.

2. **Verify the file:**
```bash
cat ~/.claude/settings.json
  1. Test with daf: 
    # Create a test context file
echo "# Test Organization Context" > $DEVAIFLOW_HOME/ORGANIZATION.md

# Open a session and verify Claude can read it
daf new --name test-permissions --goal "Test Claude Code permissions"
# In the Claude Code session, ask: "Can you read $DEVAIFLOW_HOME/ORGANIZATION.md?"

Why Global Settings?

The allow list must be in the global ~/.claude/settings.json file because:

  1. Project-local settings aren't portable: Project .claude/settings.local.json files are typically git-ignored and not pushed to repositories
  2. daf jira new requires access: When creating JIRA tickets with codebase analysis, Claude needs to read $DEVAIFLOW_HOME/ORGANIZATION.md for organization standards
  3. Team consistency: All team members need the same access permissions, which global settings ensure

Do NOT use .claude/settings.local.json in the project directory for this configuration - it won't be available across different working directories or for team members.

Common Issues

Problem: "Permission denied" when Claude tries to read context files

Cause: Claude Code settings don't allow reading from $DEVAIFLOW_HOME/

Solution: Add the paths to file_access.read array as shown above

Problem: Settings file doesn't seem to work

Cause: JSON syntax error

Solution: Validate your JSON:

python -m json.tool ~/.claude/settings.json

Problem: Changes not taking effect

Cause: Claude Code caches settings

Solution: Restart Claude Code completely (exit and reopen)

Security Considerations

What this allows:

  • Claude can read context files from $DEVAIFLOW_HOME/ and $DEVAIFLOW_HOME/
  • These directories only contain markdown documentation files
  • No sensitive credentials or secrets stored in these locations

What this does NOT allow:

  • Writing to these directories (read-only access)
  • Accessing other dotfiles or system directories
  • Reading files outside the specified paths

Verifying Setup

After configuration, verify Claude Code can read context files:

# 1. Create test file
echo "# Test Content" > $DEVAIFLOW_HOME/ORGANIZATION.md

# 2. Open a session
daf open PROJ-12345

# 3. In Claude Code, it should automatically read the file
# Check the initial prompt - it should include instructions to read the file

For troubleshooting, see Troubleshooting Guide - Claude Code Permission Issues.

Next Steps