{"id":43108780,"url":"https://github.com/itdove/devaiflow","last_synced_at":"2026-01-31T18:16:47.693Z","repository":{"id":334094643,"uuid":"1135057754","full_name":"itdove/devaiflow","owner":"itdove","description":"DevAIFlow - Manage AI coding assistant sessions with optional issue tracker integration","archived":false,"fork":false,"pushed_at":"2026-01-30T23:43:58.000Z","size":3653,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-31T07:43:34.088Z","etag":null,"topics":["claude-code","cli","developer-tools","jira","python"],"latest_commit_sha":null,"homepage":"https://github.com/itdove/devaiflow","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/itdove.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-15T15:25:17.000Z","updated_at":"2026-01-30T23:44:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/itdove/devaiflow","commit_stats":null,"previous_names":["itdove/devaiflow"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/itdove/devaiflow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itdove%2Fdevaiflow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itdove%2Fdevaiflow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itdove%2Fdevaiflow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itdove%2Fdevaiflow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/itdove","download_url":"https://codeload.github.com/itdove/devaiflow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itdove%2Fdevaiflow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28949280,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-31T14:26:55.697Z","status":"ssl_error","status_checked_at":"2026-01-31T14:26:52.545Z","response_time":128,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","cli","developer-tools","jira","python"],"created_at":"2026-01-31T18:16:47.036Z","updated_at":"2026-01-31T18:16:47.677Z","avatar_url":"https://github.com/itdove.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DevAIFlow (`daf`)\n\n[![PyPI version](https://badge.fury.io/py/devaiflow.svg)](https://badge.fury.io/py/devaiflow)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![GitHub Issues](https://img.shields.io/github/issues/itdove/devaiflow.svg)](https://github.com/itdove/devaiflow/issues)\n[![Build Status](https://github.com/itdove/devaiflow/actions/workflows/test.yml/badge.svg)](https://github.com/itdove/devaiflow/actions)\n\nA CLI tool to manage AI coding assistant sessions with optional issue tracker integration.\n\n![Alt DevAIFlow](https://raw.githubusercontent.com/itdove/devaiflow/main/images/daf-logo-160x160.png)\n\n**AI Assistants:** Claude Code (fully tested) | GitHub Copilot, Cursor, Windsurf (experimental)\n**Issue Trackers:** JIRA (currently supported) | Others (planned)\n\n\u003e **Note on Support Status:**\n\u003e - **Claude Code**: Fully tested and production-ready ✅\n\u003e - **Other AI Assistants**: Experimental - basic functionality works, full testing in progress ⚠️\n\u003e - **JIRA**: Currently the only supported issue tracker ✅\n\u003e - **Other Issue Trackers**: Planned for future releases 🔮\n\n## Overview\n\nDevAIFlow helps you organize your AI assistant development work into focused sessions. Each session can optionally link to an issue tracker ticket (JIRA currently supported), track time automatically, and maintain context across work sessions. Perfect for managing multiple features, bugs, or experiments without losing context.\n\nThe tool integrates seamlessly with GitHub and GitLab to automate PR/MR creation with AI-powered template filling, automatically linking pull requests to JIRA tickets and reducing manual overhead.\n\n### The Problem\n\nWhen working with AI coding assistants on multiple tasks, you quickly encounter these challenges:\n\n- **Context Pollution** - Mixing conversations from different tickets makes each session less focused and effective\n- **Lost History** - Hard to remember what was discussed for each specific task\n- **Manual Ticket Updates** - Constantly switching between terminal and browser to update tickets\n- **Time Tracking Gaps** - No automatic record of time spent per task\n- **Branch Management** - Manually creating and switching branches for each piece of work\n\n### The Solution\n\nDevAIFlow creates a **one-to-one mapping** between your work and AI assistant sessions:\n\n```\nIssue Tracker → Session → Conversations → AI Assistant\n(PROJ-12345)  (backup)  (#1 backend,   (isolated\n                         #2 frontend)    .jsonl files)\n```\n\nEach session is an **isolated workspace** with its own:\n- AI assistant conversation history\n- Git branch\n- Time tracking\n- Progress notes\n- Optional JIRA link\n\n**Named workspaces** enable concurrent multi-branch development - work on the same project in different workspaces (e.g., main branch + experimental feature) without conflicts.\n\n### Why Use This Tool?\n\n**🎯 Stay Focused**\n- One session per task means your AI assistant has full context for that specific work\n- No more \"Which ticket was that for?\" confusion\n- Resume exactly where you left off with complete conversation history\n\n**⏱️ Save Time**\n- Auto-creates git branches from JIRA keys\n- Auto-transitions issue tracker tickets (JIRA) (New → In Progress → Done)\n- Tracks time automatically when you open/close sessions\n- Auto-creates PRs/MRs with AI-filled templates and JIRA linking\n- No more manual ticket updates\n\n**📤 Enable Collaboration**\n- Export sessions with full conversation history for team handoffs\n- Import teammate's sessions to see exactly what they discussed\n- Share session templates for common workflows\n\n**🔧 Works Your Way**\n- JIRA integration is completely optional\n- Use for personal experiments without any ticket\n- Gradually adopt features as needed\n\n**Key Features:**\n- 🤖 **Multi-AI Support** - Works with Claude Code, GitHub Copilot, Cursor, Windsurf\n- 📂 **Multi-Repository Workflows** - Work on one ticket across multiple repositories with unified time tracking (one session, multiple conversations)\n- 🏢 **Named Workspaces** - Multiple workspaces for concurrent multi-branch development\n- 🎫 **Optional Issue Tracker** - Link issue tracker tickets (JIRA supported), or never (your choice)\n- ⏱️ **Time Tracking** - Automatic tracking with pause/resume\n- 🔄 **Context Loading** - Automatically reads AGENTS.md, CLAUDE.md, and issue tracker tickets\n- 🌿 **Git Integration** - Auto-create branches and manage git workflow\n- 🔗 **GitHub/GitLab Integration** - Automated PR/MR creation with AI-filled templates\n- 📝 **Progress Notes** - Track progress with local-first notes\n- 📤 **Export/Import** - Share sessions or backup your work\n- ⚙️ **Interactive Configuration** - Full-featured TUI for easy configuration management\n\n## Quick Start\n\n```bash\n# Install\npip install .\n\n# Export environment variables for issue tracker (JIRA example)\nexport JIRA_URL=\"https://jira.example.com\"  # Currently supports JIRA only\nexport JIRA_API_TOKEN=\u003cYOUR_JIRA_PAT\u003e\n\n# Initialize configuration (interactive wizard)\ndaf init  # Configures JIRA URL, comment visibility, workspace path, etc.\n\n# Install Claude Code commands and skills\ndaf upgrade  # Installs /daf-* slash commands into Claude Code\n\n# Sync JIRA tickets\ndaf sync\n\n# Open a session for your ticket\ndaf open PROJ-12345\n\n# Work in your AI assistant...\n# Add progress notes\ndaf note PROJ-12345 \"Completed API implementation\"\n\n# Complete the session\ndaf complete PROJ-12345\n```\n\n**Alternative:** Create sessions without JIRA:\n```bash\ndaf new --name \"fix-login-bug\" --goal \"Fix login timeout issue\"\ndaf open fix-login-bug\ndaf complete fix-login-bug\n```\n\n**Workspaces:** Organize projects by product or work on same project with different branches:\n```bash\n# Configure workspaces - organize by product\ndaf workspace add ~/development/product-a          # Auto-derives name: product-a\ndaf workspace add ~/development/product-b          # Auto-derives name: product-b\ndaf workspace add primary ~/development --default\n\n# Or organize for concurrent multi-branch work\ndaf workspace add experiments ~/experiments\n\n# Work on different products\ndaf new --name PROJ-123 -w product-a --path ~/development/product-a/backend\n\n# Work on experimental branch (no conflict with main workspace!)\ndaf new --name PROJ-456 -w experiments --path ~/experiments/myproject\n\n# Sessions remember their workspace\ndaf open PROJ-123  # Prompts to select which workspace if ambiguous\n```\n\n**Configuration:** Use the interactive TUI for easy configuration:\n```bash\n# Launch the interactive configuration editor\ndaf config edit\n\n# Or use the alias\ndaf config tui\n```\n\nThe TUI provides:\n- 📑 Tabbed interface for all configuration sections\n- ✅ Input validation for URLs, paths, and required fields\n- 💾 Automatic backup creation before saving\n- 👀 Preview mode to review changes before saving\n- ⌨️ Full keyboard navigation (Tab, Arrow keys, Ctrl+S to save)\n- ❓ Built-in help screen (press `?`)\n\n**Next Steps:** See the [Quick Start Guide](docs/03-quick-start.md) for a complete walkthrough.\n\n## Documentation\n\n**New to DevAIFlow?** Choose your path:\n\n- **Quick Decision** (2 min): Read [What is DevAIFlow?](docs/01-overview.md) to see if this tool is right for you\n- **Quick Start** (5 min): [Installation](docs/02-installation.md) → [Quick Start](docs/03-quick-start.md) → Create your first session\n- **Complete Guide**: Read the documentation sections below in order\n\n---\n\n📚 **[Complete Documentation](docs/)** - Full guides, references, and troubleshooting\n\n\n### Quick Links\n\n**Core Documentation:**\n- **[Installation Guide](docs/02-installation.md)** - Setup instructions and requirements\n- **[Session Management](docs/04-session-management.md)** - Understanding sessions and lifecycle\n- **[JIRA Integration](docs/05-jira-integration.md)** - Issue tracker integration (JIRA)\n- **[Command Reference](docs/07-commands.md)** - Complete CLI command documentation\n- **[Configuration](docs/06-configuration.md)** - Customizing the tool for your workflow (includes JSON Schema validation)\n- **[Troubleshooting](docs/11-troubleshooting.md)** - Common issues and solutions\n- **[Uninstall Guide](docs/uninstall.md)** - Complete uninstallation instructions\n- **[AI Agent Support](docs/ai-agent-support-matrix.md)** - Compatibility matrix for different AI assistants\n\n\n**Additional Resources:**\n- **[Uninstall Guide](docs/uninstall.md)** - Complete uninstallation instructions\n- **[AI Agent Support](docs/ai-agent-support-matrix.md)** - Compatibility matrix for different AI assistants\n\n**Validation:**\n- **[config.schema.json](config.schema.json)** - JSON Schema for validating config.json (use `daf config validate`)\n\n## Supported Platforms\n\nDevAIFlow officially supports:\n- **macOS** (Intel and Apple Silicon)\n- **Linux** (Ubuntu, Debian, Fedora, RHEL, etc.)\n- **Windows 10/11** (see [Windows Installation](docs/02-installation.md#windows-installation))\n\nAll core features work across platforms with automatic platform-specific handling for:\n- Signal handling (SIGTERM on Unix, SIGBREAK on Windows)\n- File locking (fcntl on Unix, atomic writes on Windows)\n- Path separators (automatically handled via pathlib)\n- Line endings (CRLF on Windows, LF on Unix)\n\n## Requirements\n\n- **Python 3.10, 3.11, or 3.12** - For the `daf` tool (older versions like 3.9 may work but are not officially tested)\n- **AI Assistant CLI** - At least one supported AI assistant (Claude Code, GitHub Copilot, Cursor, or Windsurf) must be installed\n- **Git** - For branch management features\n- **GitHub CLI (`gh`)** (optional) - Required for creating GitHub PRs and fetching PR templates from private repos\n- **GitLab CLI (`glab`)** (optional) - Required for creating GitLab MRs and fetching MR templates from private repos\n- **Issue Tracker API Token** (optional) - Only required if using issue tracker integration (JIRA currently supported)\n\nSee the [Installation Guide](docs/02-installation.md) for detailed setup instructions including issue tracker configuration.\n\n## For Other Organizations\n\n**DevAIFlow is fully generic and works with any JIRA instance.** Configuration is file-based and can be customized for your organization.\n\n1. **Quick Setup**: Use configuration templates to get started\n   ```bash\n   # Copy templates to your workspace\n   cp -r /path/to/devaiflow/docs/config-templates/* ~/workspace/myproject/\n\n   # Customize for your team\n   vim ~/workspace/myproject/backends/jira.json      # Set JIRA URL, transitions\n   vim ~/workspace/myproject/organization.json       # Set project key\n   vim ~/workspace/myproject/team.json              # Set team workstream\n\n   # Commit to git for team sharing\n   git add *.json backends/\n   git commit -m \"Add DevAIFlow workspace configuration\"\n   ```\n\n2. **Interactive Config**: Use the TUI for easy configuration management\n   ```bash\n   daf config tui  # Launch interactive configuration editor\n   ```\n\n3. **Workspace Configuration** (Recommended for teams):\n   - Place config files in workspace root for team sharing\n   - Automatic discovery when running `daf` from any subdirectory\n   - Version control your team's JIRA settings in git\n   - See `docs/config-templates/README.md` for detailed guide\n\n4. **User Configuration** (For personal use):\n   - Run `daf init` to configure your JIRA instance\n   - Settings stored in `$DEVAIFLOW_HOME/` directory\n   - Personal preferences only, no team sharing\n\n5. **Copy DAF_AGENTS.md**: Copy the `DAF_AGENTS.md` file to your project roots for automatic daf tool guidance in AI assistant sessions\n   - This file is automatically loaded when opening sessions\n   - Provides complete command reference and best practices\n   - Customize JIRA templates to match your organization's standards\n\n**Configuration Files:**\n- `backends/jira.json` - JIRA backend settings (URL, field mappings, transitions)\n- `organization.json` - Organization-wide settings (project, field aliases)\n- `team.json` - Team-specific settings (workstream, comment visibility)\n- `config.json` - User personal preferences\n\nSee `docs/config-templates/` for complete templates with detailed comments and examples.\n\n## Development\n\nFor developers working on the DevAIFlow codebase:\n\n```bash\n# Setup\npip install -e \".[dev]\"\n\n# Run unit tests\npytest\n\n# Run with coverage\npytest --cov=devflow --cov-report=html\n\n# Run integration tests (shell-based end-to-end tests)\ncd integration-tests\n./test_jira_green_path.sh\n\n# Run with mock services (isolated from production)\nDAF_MOCK_MODE=1 pytest\nDAF_MOCK_MODE=1 daf list\n```\n\n### Testing\n\nThe project includes two types of tests:\n\n**Unit Tests** (`tests/`):\n- Python-based tests using pytest\n- Test individual functions and classes\n- Fast execution with mocks and fixtures\n- Run with `pytest`\n\n**Integration Tests** (`integration-tests/`):\n- Shell-based end-to-end workflow tests\n- Test complete CLI command workflows\n- Run in mock mode for isolation\n- See `integration-tests/README.md` for details\n\n### Mock Services for Testing\n\nThe tool includes a comprehensive mock services infrastructure for integration testing without affecting production data:\n\n```bash\n# Enable mock mode\nexport DAF_MOCK_MODE=1\n\n# All commands now use mock services with isolated data\ndaf list              # Shows mock sessions only\ndaf new my-test       # Creates mock session\ndaf purge-mock-data   # Clear all mock data\n\n# Mock data is stored separately in $DEVAIFLOW_HOME/mocks/\n```\n\nMock services include:\n- **JIRA**: Tickets, comments, transitions, attachments\n- **GitHub**: Pull requests\n- **GitLab**: Merge requests\n- **Sessions**: Completely isolated session index\n- **Claude Code**: Skipped (not launched in mock mode)\n\n#### Testing With and Without Mock Mode\n\n**With Mock Mode** (`DAF_MOCK_MODE=1`):\n- ✅ Fast and isolated testing\n- ✅ No real JIRA tickets created\n- ✅ Claude Code launch is skipped (faster)\n- ✅ Perfect for CI/CD pipelines\n- ❌ Doesn't test real Claude Code integration\n\n**Without Mock Mode** (no `DAF_MOCK_MODE`):\n- ✅ Tests real Claude Code integration\n- ✅ Tests real JIRA API operations\n- ✅ Validates conversation export/import\n- ✅ More realistic end-to-end testing\n- ⚠️ Creates real JIRA tickets (requires cleanup)\n- ⚠️ Requires JIRA credentials and display environment\n\n**For collaboration testing**, both approaches work:\n- Use `DEVAIFLOW_HOME` to simulate multiple developers on one laptop\n- See `integration-tests/TEST_COLLABORATION_SCENARIO.md` for detailed step-by-step guides\n- Automated test available: `test_collaboration_workflow.sh` (with mock mode)\n- Manual testing guide available for no-mock testing (see TEST_COLLABORATION_SCENARIO.md)\n\nSee [AGENTS.md](AGENTS.md) for complete development guidelines, architecture, and coding standards.\n\n## Reporting Issues\n\nFound a bug or have a feature request? Please report it on GitHub:\n\n**[Report an Issue](https://github.com/itdove/devaiflow/issues)**\n\nWhen reporting bugs, please include:\n- Steps to reproduce\n- Expected vs actual behavior\n- Your environment (OS, Python version, daf version)\n- Relevant error messages or logs\n\nFor security vulnerabilities, please see [SECURITY.md](SECURITY.md) for responsible disclosure guidelines.\n\n## Contributing\n\nWe welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on:\n- Development setup\n- Running tests\n- Submitting pull requests\n- Code style guidelines\n\n## License\n\nApache License 2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitdove%2Fdevaiflow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fitdove%2Fdevaiflow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitdove%2Fdevaiflow/lists"}