MAIASS - Modular AI-Augmented Semantic Scribe - Intelligent Git workflow automation
npm install maiass

---
MAIASS is an intelligent Git workflow automation tool that streamlines version management, changelog generation, and deployment processes with AI-powered commit message suggestions. This Node.js implementation provides cross-platform compatibility and self-contained binary distribution.
Cross-Platform Binaries (Recommended):
``bash`Download and install for your platform
curl -L https://github.com/vsmash/maiass/releases/latest/download/maiass-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m) -o maiass
chmod +x maiass
./maiass --version
From Source:
`bash`
git clone https://github.com/vsmash/nodemaiass.git
cd nodemaiass && npm install && npm link
`bashComplete workflow with patch version bump
maiass
$3
`bash
Enable AI features
maiass config set maiass_token "your_api_key"
maiass config set ai_mode "ask" (or "always" or "off")MAIASS will now suggest intelligent commit messages
maiass
`✨ Key Features- 🤖 AI-Powered Commit Messages: AI integration for intelligent commit suggestions- 📋 Dual Changelog System: User-facing and developer-facing changelogs- 🔄 Complete Git Workflow: Branch validation, commits, merges, and versioning- 🏷️ Smart Version Management: Multiple version file support with semantic versioning- 🌍 Cross-Platform: Self-contained binaries for macOS, Linux, and Windows- ⚙️ Zero Configuration: Works out of the box with sensible defaults- 🎯 JIRA Integration: Automatic ticket detection from branch names
� Documentation
| Topic | Description |
|-------|-------------|
| Installation Guide | Detailed installation instructions and binaries |
| Configuration | Environment variables and project setup |
| Workflow Guide | Complete workflow documentation |
| Commands Reference | All available commands and options |
| Cross-Platform Guide | Platform-specific notes and compatibility |
| Development | Contributing and development setup |
🔧 Supported Technologies
$3
$3
$3
🌍 Platform Support
| Platform | Binary Available | Self-Contained |
|----------|------------------|----------------|
| macOS Intel | ✅
maiass-macos-intel | ✅ Node.js included |
| macOS Apple Silicon | ✅ maiass-macos-arm64 | ✅ Node.js included |
| Linux x64 | ✅ maiass-linux-x64 | ✅ Node.js included |
| Linux ARM64 | ✅ maiass-linux-arm64 | ✅ Node.js included |
| Windows x64 | ✅ maiass-windows-x64.exe | ✅ Node.js included |
| Windows ARM64 | ✅ maiass-windows-arm64.exe | ✅ Node.js included |🔄 Workflow Overview
MAIASS orchestrates a 4-phase intelligent workflow:
1. Branch Detection & Validation - Validates current branch and workflow requirements
2. Commit Workflow - AI-powered commit messages with JIRA integration
3. Merge Management - Handles branch merging and conflict resolution
4. Version & Changelog - Semantic versioning with dual changelog generation
⚙️ Quick Configuration
`bash
Enable AI features (global)
maiass config set --global maiass_token "your_api_key"
maiass config set --global ai_mode "ask"Project-specific branch override
maiass config set mainbranch "main"View current configuration
maiass config list
`🎯 What Makes This Special?
$3
$3
$3
🔗 Related Projects- MAIASS (Bash) - Original bash implementation- Homebrew Formula - Homebrew installation
🤝 Contributing
We welcome contributions! Whether it's:- 🐛 Bug reports and feature requests- 📖 Documentation improvements- 🔧 Code contributions and enhancements- 💡 Ideas for new features
See our Development Guide to get started.
📄 License
MAIASS is released under the GNU General Public License v3.0. Free and open source software.
🔗 Links- GitHub Repository- Issue Tracker- Releases- Original MAIASS---
Ready to streamline your Git workflow? Download MAIASS today and experience intelligent version management with AI-powered automation.
`bash
Get the latest release
curl -L https://github.com/vsmash/maiass/releases/latest/download/maiass-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m) -o maiass && chmod +x maiass
`---Made with ❤️ for developers who want better Git workflows
maiass version [major|minor|patch|version]
Configuration
maiass config list
maiass config get
maiass config set Environment info
maiass envGit information
maiass git-info
maiass git # Show git status and branch infoEnvironment variables
maiass env # Show current environment
maiass env --json # Show environment as JSON
`⚙️ Configuration
$3
1. Enable AI features (optional):
`bash
# Set Maiass API key globally
maiass config --global maiass_token=your_api_key_here
`2. Project-specific settings (if needed):
`bash
# Override branch names for projects using 'main'
maiass config --project mainbranch=main
`$3
MAIASS uses
.env.maiass files for configuration:- Global: ~/.env.maiass (user-wide settings)- Project: ./.env.maiass (project-specific overrides)$3
`bash
AI Integration
MAIASS_AI_TOKEN=your_api_key_here
MAIASS_AI_MODE=ask # ask, autosuggest, off
MAIASS_AI_MODEL=gpt-4 # AI model to useBranch Configuration (only set if different from defaults)
MAIASS_MAINBRANCH=main # Default: main
MAIASS_DEVELOPBRANCH=develop # Default: develop
MAIASS_STAGINGBRANCH=staging # Default: stagingWorkflow Settings
MAIASS_DEBUG=true # Enable debug output
MAIASS_VERBOSITY=normal # brief, normal, verbose
MAIASS_AUTO_TAG_RELEASES=true # Automatically tag releases (required for changelog)Changelog Configuration
MAIASS_CHANGELOG_PATH=CHANGELOG.md # Main changelog file path
MAIASS_CHANGELOG_NAME=CHANGELOG.md # Main changelog file name
MAIASS_CHANGELOG_INTERNAL_NAME.CHANGELOG_internal.md # Internal changelog file name
`🔄 Workflow Phases
MAIASS orchestrates a 4-phase workflow:
$3
$3
$3
$3
- CHANGELOG.md: Clean, user-facing format with JIRA tickets stripped
- .CHANGELOG_internal.md: Developer format with commit hashes, authors, and JIRA tickets- Smart commit range detection: Only includes commits since the last release tag- Version replacement logic: Replaces same-day patch versions instead of duplicating entries📝 Changelog System
MAIASS automatically generates two types of changelogs during version management:
$3
User-facing format with clean, readable entries:
`markdown
0.5.6
24 July 2025- Update Maiass Pipeline functionality
- feat: imported path package in maiass-pipeline
- docs: added comment about commit message formatting- Updated commit message filtering for maiass-pipeline
- feat: added code to clean up commit messages
- fix: removed empty lines and trailing newlines from each commit
`$3
Developer-facing format with commit hashes, authors, and JIRA tickets:
`markdown
0.5.6
Thursday, 24 July 2025- d7ddba9 VEL-405 Update Maiass Pipeline functionality (Developer Name)- 5ea6d03 VEL-405 Updated commit message filtering for maiass-pipeline (Developer Name)
`$3
🎨 Examples
$3
`bash
On feature branch: feature/USER-123-new-login
1. Complete workflow with minor version bump
maiass minor --tagThis will:
- Detect you're on a feature branch
- Run commit workflow with AI suggestions
- Merge to develop branch
- Bump minor version (1.0.0 → 1.1.0)
- Create git tag v1.1.0
`$3
`bash
Just commit changes without version bumping
maiass --commits-only --auto-stageWith AI commit message
maiass commit
`$3
`bash
Preview what would happen without making changes
maiass --dry-run patchCheck current version status
maiass version --current
`🔧 Advanced Usage
$3
`bash
Configure custom version file
maiass config --project version_primary_file=VERSION.txt
maiass config --project version_primary_type=text
`$3
`bash
Update multiple files with same version
maiass config --project version_secondary_files="src/version.js,docs/VERSION"
`$3
`bash
Different AI modes
maiass config --global ai_mode=autosuggest # Auto-suggest without asking
maiass config --global ai_mode=off # Disable AICustom commit message style
maiass config --global ai_commit_message_style=conventional
`🐛 Troubleshooting
$3
"Not in a git repository"
`bash
Ensure you're in a git repository
git status
`"No version files detected"
`bash
Check for supported version files
ls package.json composer.json VERSIONOr configure custom version file
maiass config --project version_primary_file=your-version-file
`"Failed to switch to develop branch"
`bash
Create develop branch if it doesn't exist
git checkout -b develop
`$3
`bash
Enable verbose debugging
export MAIASS_DEBUG=true
maiass --dry-run
``Contributions are welcome! Please read our Contributing Guide for details.
MIT License - see LICENSE file for details.
Made with ❤️ by the MAIASS team