# Gira - Git-based Issue Tracking and Project Management
[](https://pypi.org/project/gira/)
[](https://www.python.org/downloads/)
[](https://pypi.org/project/gira/)
[]()
[](https://github.com/goatbytes/gira/actions/workflows/deploy-docs.yml)
[](https://github.com/goatbytes/gira/actions/workflows/mcp-tests.yml)
[](https://styles.goatbytes.io/lang/python)
**Gira** is a lightweight, Git-friendly project management tool designed for developers and AI agents. It stores all project data in plain JSON files within your repository, making it perfect for version control and collaboration.
## ✨ Features
- **Git-Native**: All data stored as JSON files in `.gira/` directory
- **Offline-First**: Works completely offline, no external dependencies
- **AI-Friendly**: MCP server for AI agents (Claude, Gemini) with 30+ tools
- **Kanban Board**: Visual project management with customizable swimlanes
- **Rich CLI**: Beautiful terminal UI with colors and tables
- **Advanced Search**: Powerful query language with filters and full-text search
- **Shell Completion**: Tab completion for all commands and dynamic ID completion
- **Fast**: Lightweight and responsive, perfect for large projects
- **Extensible**: Hook system, webhooks, and custom fields support
- **Import/Export**: JSON, CSV, and Markdown format support
## 🚀 Quick Start
```bash
# Install Gira
pip install gira # Available on PyPI
# Or install from source
pip install -e .
# Install with optional features
pip install "gira[s3]" # For AWS S3, Cloudflare R2, Backblaze B2
pip install "gira[gcs]" # For Google Cloud Storage
pip install "gira[azure]" # For Azure Blob Storage
pip install "gira[docs]" # For documentation tools
# Initialize a new project
gira init "My Project"
# Create your first ticket
gira ticket create "Set up project structure"
# View the kanban board
gira board
# List all tickets
gira ticket list
```
## 📋 Core Commands
### Project Management
- `gira init <name>` - Initialize a new Gira project
- `gira --version` - Show version information
### Ticket Operations
- `gira ticket create <title>` - Create a new ticket
- `gira ticket list` - List tickets with filtering (`--search`, `--labels`, `--assignee`)
- `gira ticket show <id>` - Display ticket details
- `gira ticket update <id>` - Update ticket fields
- `gira ticket move <id> <status>` - Move ticket between statuses
### Epic Management
- `gira epic create <title>` - Create a new epic
- `gira epic list` - List all epics
- `gira epic show <id>` - Display epic details
- `gira epic update <id>` - Update epic fields (`--add-tickets`)
### Sprint Management
- `gira sprint create <name>` - Create a new sprint (`--duration`, `--end-date`)
- `gira sprint list` - List sprints (`--format json`)
- `gira sprint show <id>` - Display sprint details
- `gira sprint update <id>` - Update sprint fields
### Comments & Search
- `gira comment add <ticket-id>` - Add comment to ticket
- `gira comment list <ticket-id>` - List ticket comments
- `gira query <expression>` - Advanced search with filters
### Export & Integration
- `gira export json` - Export project data to JSON
- `gira export csv` - Export to CSV format
- `gira export md` - Export to Markdown format
- `gira webhook add <url>` - Add webhook integration
### AI Integration
- **MCP Server**: 30+ tools for AI agents (Claude Desktop, etc.)
- **Natural Language**: AI agents can manage tickets through conversation
- Install: `pip install "gira[mcp]"` and configure Claude Desktop
### Shell Completion
- `gira --install-completion` - Install tab completion (recommended)
- `gira completion install <shell>` - Legacy completion system (deprecated)
### Board Visualization
- `gira board` - Display kanban board
- `gira board --compact` - Compact board view
- `gira board --assignee <email>` - Filter by assignee
### Backlog Management
- `gira backlog` - View backlog tickets with smart filters
- `gira backlog --ready` - Show tickets ready to work on
- `gira backlog --unassigned` - Show unassigned tickets
- `gira backlog --priority high` - Filter by priority
- `gira backlog --counts` - Show summary counts
## 🏗️ Project Structure
```
.gira/
├── config.json # Project configuration
├── .state.json # Internal state (next ticket ID, etc.)
├── backlog/ # Tickets in backlog
├── board/ # Active tickets by status
│ ├── todo/
│ ├── in_progress/
│ ├── review/
│ └── done/
├── epics/ # Epic definitions and management
├── sprints/ # Sprint data and tracking
├── comments/ # Ticket comments and discussions
└── archive/ # Completed tickets
```
## 📖 Documentation
- [Installation Guide](docs/installation.md)
- [Quick Start Guide](docs/quickstart.md)
- [User Guide](docs/02-user-guide/README.md)
- [Architecture Overview](docs/00-overview/architecture.md)
- [CLI Reference](docs/05-reference/cli-reference.md)
## 🛠️ Advanced Features
### Custom Git Merge Driver
Gira includes an intelligent Git merge driver that automatically resolves conflicts in JSON files:
- **Smart Conflict Resolution**: Uses "latest-write-wins" strategy based on timestamps
- **Semantic Merging**: Understands ticket structure and merges fields intelligently
- **File Movement Handling**: Correctly handles tickets moved to different statuses
- **Audit Trail**: Adds merge notes to track automatic resolutions
To enable the merge driver:
```bash
.gira/scripts/setup-merge-driver.sh
```
See [merge driver documentation](docs/03-integrations/git-merge-driver.md) for details.
## Contributing
Contributions are welcome! Please read our [contributing guide](CONTRIBUTING.md) and submit pull requests to our repository.
## 📚 Documentation
Comprehensive documentation is available at **[goatbytes.github.io/gira](https://goatbytes.github.io/gira/)**
- **[📖 Installation](https://goatbytes.github.io/gira/installation/)** - Installation guide
- **[🚀 Quick Start](https://goatbytes.github.io/gira/quickstart/)** - Get started in minutes
- **[📋 User Guide](https://goatbytes.github.io/gira/02-user-guide/)** - Complete feature documentation
- **[🔧 CLI Reference](https://goatbytes.github.io/gira/05-reference/cli-reference/)** - All commands and options
- **[📝 Commands](https://goatbytes.github.io/gira/05-reference/commands/)** - Individual command documentation
- **[🤖 AI Agents](https://goatbytes.github.io/gira/10-ai-agents/)** - AI integration documentation
- **[🔗 MCP Server](https://goatbytes.github.io/gira/09-mcp/)** - Model Context Protocol integration
> 📡 Documentation is automatically updated on every release using our automated generation system.
### Development Setup
```bash
# Clone the repository
git clone https://github.com/goatbytes/gira.git
cd gira
# Install in development mode
pip install -e ".[dev]"
# Run tests
pytest
# Run linter
ruff check src/
```
## 📊 Testing
Gira maintains high test coverage (88%+) with comprehensive unit and integration tests:
```bash
# Run all tests
pytest
# Run with coverage
pytest --cov=gira --cov-report=html
# Run specific test file
pytest tests/integration/test_cli_ticket.py
```
## 🔧 Requirements
- Python 3.8 or higher
- Git (for version control integration)
- Terminal with Unicode support (for rich output)
## 🎯 Design Philosophy
Gira follows these core principles:
1. **Simplicity**: Plain JSON files, no database required
2. **Transparency**: All data is human-readable and Git-friendly
3. **Flexibility**: Extensible design for custom workflows
4. **Performance**: Fast operations even with thousands of tickets
5. **AI-First**: Structured data optimized for AI agent interaction
## 🔧 Troubleshooting
### Unicode Display Issues
If you see garbled characters (like `â`) instead of box-drawing characters in the board view:
```bash
# Set environment variable to force ASCII-only output
export GIRA_ASCII_ONLY=1
gira board
# Or force Unicode if your terminal supports it
export GIRA_FORCE_UNICODE=1
gira board
```
For container environments, Gira automatically detects and adjusts output. If auto-detection fails, use the environment variables above.
---
## 📄 License
Gira is released under the MIT License. See [LICENSE](LICENSE) file for details.
---
## About GoatBytes.IO
At **[GoatBytes.IO](https://goatbytes.io)**, our mission is to develop secure software solutions that empower businesses to
transform the world. With a focus on innovation and excellence, we strive to deliver cutting-edge
products that meet the evolving needs of businesses across various industries.
[](https://github.com/goatbytes)
[](https://twitter.com/goatbytes)
[](https://www.linkedin.com/company/goatbytes)
[](https://www.instagram.com/goatbytes.io/)
Raw data
{
"_id": null,
"home_page": null,
"name": "gira",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Jared Rummler <jared@goatbytes.dev>",
"keywords": "project-management, git, cli, agile, tickets, ai-agents",
"author": null,
"author_email": "GoatBytes <contact@goatbytes.dev>",
"download_url": "https://files.pythonhosted.org/packages/bc/f5/02f9bf907d5df5d6e7a111826d0f1e7a2412c7a0d0dbce6f56ad73867d93/gira-0.2.2.tar.gz",
"platform": null,
"description": "# Gira - Git-based Issue Tracking and Project Management\n\n[](https://pypi.org/project/gira/)\n[](https://www.python.org/downloads/)\n[](https://pypi.org/project/gira/)\n[]()\n[](https://github.com/goatbytes/gira/actions/workflows/deploy-docs.yml)\n[](https://github.com/goatbytes/gira/actions/workflows/mcp-tests.yml)\n[](https://styles.goatbytes.io/lang/python)\n\n\n**Gira** is a lightweight, Git-friendly project management tool designed for developers and AI agents. It stores all project data in plain JSON files within your repository, making it perfect for version control and collaboration.\n\n## \u2728 Features\n\n- **Git-Native**: All data stored as JSON files in `.gira/` directory\n- **Offline-First**: Works completely offline, no external dependencies\n- **AI-Friendly**: MCP server for AI agents (Claude, Gemini) with 30+ tools\n- **Kanban Board**: Visual project management with customizable swimlanes\n- **Rich CLI**: Beautiful terminal UI with colors and tables\n- **Advanced Search**: Powerful query language with filters and full-text search\n- **Shell Completion**: Tab completion for all commands and dynamic ID completion\n- **Fast**: Lightweight and responsive, perfect for large projects\n- **Extensible**: Hook system, webhooks, and custom fields support\n- **Import/Export**: JSON, CSV, and Markdown format support\n\n## \ud83d\ude80 Quick Start\n\n```bash\n# Install Gira\npip install gira # Available on PyPI\n\n# Or install from source\npip install -e .\n\n# Install with optional features\npip install \"gira[s3]\" # For AWS S3, Cloudflare R2, Backblaze B2\npip install \"gira[gcs]\" # For Google Cloud Storage\npip install \"gira[azure]\" # For Azure Blob Storage\npip install \"gira[docs]\" # For documentation tools\n\n# Initialize a new project\ngira init \"My Project\"\n\n# Create your first ticket\ngira ticket create \"Set up project structure\"\n\n# View the kanban board\ngira board\n\n# List all tickets\ngira ticket list\n```\n\n## \ud83d\udccb Core Commands\n\n### Project Management\n- `gira init <name>` - Initialize a new Gira project\n- `gira --version` - Show version information\n\n### Ticket Operations\n- `gira ticket create <title>` - Create a new ticket\n- `gira ticket list` - List tickets with filtering (`--search`, `--labels`, `--assignee`)\n- `gira ticket show <id>` - Display ticket details \n- `gira ticket update <id>` - Update ticket fields\n- `gira ticket move <id> <status>` - Move ticket between statuses\n\n### Epic Management\n- `gira epic create <title>` - Create a new epic\n- `gira epic list` - List all epics\n- `gira epic show <id>` - Display epic details\n- `gira epic update <id>` - Update epic fields (`--add-tickets`)\n\n### Sprint Management \n- `gira sprint create <name>` - Create a new sprint (`--duration`, `--end-date`)\n- `gira sprint list` - List sprints (`--format json`)\n- `gira sprint show <id>` - Display sprint details\n- `gira sprint update <id>` - Update sprint fields\n\n### Comments & Search\n- `gira comment add <ticket-id>` - Add comment to ticket\n- `gira comment list <ticket-id>` - List ticket comments\n- `gira query <expression>` - Advanced search with filters\n\n### Export & Integration\n- `gira export json` - Export project data to JSON\n- `gira export csv` - Export to CSV format \n- `gira export md` - Export to Markdown format\n- `gira webhook add <url>` - Add webhook integration\n\n### AI Integration\n- **MCP Server**: 30+ tools for AI agents (Claude Desktop, etc.)\n- **Natural Language**: AI agents can manage tickets through conversation\n- Install: `pip install \"gira[mcp]\"` and configure Claude Desktop\n\n### Shell Completion\n- `gira --install-completion` - Install tab completion (recommended)\n- `gira completion install <shell>` - Legacy completion system (deprecated)\n\n### Board Visualization\n- `gira board` - Display kanban board\n- `gira board --compact` - Compact board view\n- `gira board --assignee <email>` - Filter by assignee\n\n### Backlog Management\n- `gira backlog` - View backlog tickets with smart filters\n- `gira backlog --ready` - Show tickets ready to work on\n- `gira backlog --unassigned` - Show unassigned tickets\n- `gira backlog --priority high` - Filter by priority\n- `gira backlog --counts` - Show summary counts\n\n## \ud83c\udfd7\ufe0f Project Structure\n\n```\n.gira/\n\u251c\u2500\u2500 config.json # Project configuration\n\u251c\u2500\u2500 .state.json # Internal state (next ticket ID, etc.)\n\u251c\u2500\u2500 backlog/ # Tickets in backlog\n\u251c\u2500\u2500 board/ # Active tickets by status\n\u2502 \u251c\u2500\u2500 todo/\n\u2502 \u251c\u2500\u2500 in_progress/\n\u2502 \u251c\u2500\u2500 review/\n\u2502 \u2514\u2500\u2500 done/\n\u251c\u2500\u2500 epics/ # Epic definitions and management\n\u251c\u2500\u2500 sprints/ # Sprint data and tracking\n\u251c\u2500\u2500 comments/ # Ticket comments and discussions\n\u2514\u2500\u2500 archive/ # Completed tickets\n```\n\n## \ud83d\udcd6 Documentation\n\n- [Installation Guide](docs/installation.md)\n- [Quick Start Guide](docs/quickstart.md)\n- [User Guide](docs/02-user-guide/README.md)\n- [Architecture Overview](docs/00-overview/architecture.md)\n- [CLI Reference](docs/05-reference/cli-reference.md)\n\n## \ud83d\udee0\ufe0f Advanced Features\n\n### Custom Git Merge Driver\n\nGira includes an intelligent Git merge driver that automatically resolves conflicts in JSON files:\n\n- **Smart Conflict Resolution**: Uses \"latest-write-wins\" strategy based on timestamps\n- **Semantic Merging**: Understands ticket structure and merges fields intelligently\n- **File Movement Handling**: Correctly handles tickets moved to different statuses\n- **Audit Trail**: Adds merge notes to track automatic resolutions\n\nTo enable the merge driver:\n```bash\n.gira/scripts/setup-merge-driver.sh\n```\n\nSee [merge driver documentation](docs/03-integrations/git-merge-driver.md) for details.\n\n\n## Contributing\n\nContributions are welcome! Please read our [contributing guide](CONTRIBUTING.md) and submit pull requests to our repository.\n\n## \ud83d\udcda Documentation\n\nComprehensive documentation is available at **[goatbytes.github.io/gira](https://goatbytes.github.io/gira/)**\n\n- **[\ud83d\udcd6 Installation](https://goatbytes.github.io/gira/installation/)** - Installation guide\n- **[\ud83d\ude80 Quick Start](https://goatbytes.github.io/gira/quickstart/)** - Get started in minutes\n- **[\ud83d\udccb User Guide](https://goatbytes.github.io/gira/02-user-guide/)** - Complete feature documentation \n- **[\ud83d\udd27 CLI Reference](https://goatbytes.github.io/gira/05-reference/cli-reference/)** - All commands and options\n- **[\ud83d\udcdd Commands](https://goatbytes.github.io/gira/05-reference/commands/)** - Individual command documentation\n- **[\ud83e\udd16 AI Agents](https://goatbytes.github.io/gira/10-ai-agents/)** - AI integration documentation\n- **[\ud83d\udd17 MCP Server](https://goatbytes.github.io/gira/09-mcp/)** - Model Context Protocol integration\n\n> \ud83d\udce1 Documentation is automatically updated on every release using our automated generation system.\n\n### Development Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/goatbytes/gira.git\ncd gira\n\n# Install in development mode\npip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Run linter\nruff check src/\n```\n\n## \ud83d\udcca Testing\n\nGira maintains high test coverage (88%+) with comprehensive unit and integration tests:\n\n```bash\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=gira --cov-report=html\n\n# Run specific test file\npytest tests/integration/test_cli_ticket.py\n```\n\n## \ud83d\udd27 Requirements\n\n- Python 3.8 or higher\n- Git (for version control integration)\n- Terminal with Unicode support (for rich output)\n\n## \ud83c\udfaf Design Philosophy\n\nGira follows these core principles:\n\n1. **Simplicity**: Plain JSON files, no database required\n2. **Transparency**: All data is human-readable and Git-friendly\n3. **Flexibility**: Extensible design for custom workflows\n4. **Performance**: Fast operations even with thousands of tickets\n5. **AI-First**: Structured data optimized for AI agent interaction\n\n\n## \ud83d\udd27 Troubleshooting\n\n### Unicode Display Issues\n\nIf you see garbled characters (like `\u00e2`) instead of box-drawing characters in the board view:\n\n```bash\n# Set environment variable to force ASCII-only output\nexport GIRA_ASCII_ONLY=1\ngira board\n\n# Or force Unicode if your terminal supports it\nexport GIRA_FORCE_UNICODE=1\ngira board\n```\n\nFor container environments, Gira automatically detects and adjusts output. If auto-detection fails, use the environment variables above.\n\n---\n\n## \ud83d\udcc4 License\n\nGira is released under the MIT License. See [LICENSE](LICENSE) file for details.\n\n---\n\n## About GoatBytes.IO\n\n\n\nAt **[GoatBytes.IO](https://goatbytes.io)**, our mission is to develop secure software solutions that empower businesses to\ntransform the world. With a focus on innovation and excellence, we strive to deliver cutting-edge\nproducts that meet the evolving needs of businesses across various industries.\n\n[](https://github.com/goatbytes)\n[](https://twitter.com/goatbytes)\n[](https://www.linkedin.com/company/goatbytes)\n[](https://www.instagram.com/goatbytes.io/)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Git-based project management for developers and AI agents",
"version": "0.2.2",
"project_urls": {
"Documentation": "https://github.com/goatbytes/gira/tree/main/docs",
"Homepage": "https://github.com/goatbytes/gira",
"Issues": "https://github.com/goatbytes/gira/issues",
"Repository": "https://github.com/goatbytes/gira.git"
},
"split_keywords": [
"project-management",
" git",
" cli",
" agile",
" tickets",
" ai-agents"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9da9efadbb055052a5f59ee8bee7923926dbcc0ad78eb3792d0f13623a29bca3",
"md5": "95ed74746de4fcc093a31c9ec4537698",
"sha256": "3d57a31febf8d44c5fa110a5fc25f4ca12acfc34ae4122512711de8f85398649"
},
"downloads": -1,
"filename": "gira-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "95ed74746de4fcc093a31c9ec4537698",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 745714,
"upload_time": "2025-08-12T20:12:30",
"upload_time_iso_8601": "2025-08-12T20:12:30.203417Z",
"url": "https://files.pythonhosted.org/packages/9d/a9/efadbb055052a5f59ee8bee7923926dbcc0ad78eb3792d0f13623a29bca3/gira-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "bcf502f9bf907d5df5d6e7a111826d0f1e7a2412c7a0d0dbce6f56ad73867d93",
"md5": "0c42c6c03f9c5a358de77bd94948bd62",
"sha256": "060fc8280760645311ffe4795025a81a6c6f0b79638e6402067a085f4ae9281c"
},
"downloads": -1,
"filename": "gira-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "0c42c6c03f9c5a358de77bd94948bd62",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 598945,
"upload_time": "2025-08-12T20:12:31",
"upload_time_iso_8601": "2025-08-12T20:12:31.879719Z",
"url": "https://files.pythonhosted.org/packages/bc/f5/02f9bf907d5df5d6e7a111826d0f1e7a2412c7a0d0dbce6f56ad73867d93/gira-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-12 20:12:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "goatbytes",
"github_project": "gira",
"github_not_found": true,
"lcname": "gira"
}
JSON
