# AI Agent Manager v0.1.0 (Beta)
**Terminal UI for managing AI agents, resources, and MCP servers across multiple AI tools.**
## 🎯 What It Does
AI Agent Manager helps you manage AI agents (Amazon Q CLI, Claude, etc.) with a visual terminal interface:
- 📚 **Library Management**: Organize knowledge files (templates, rules, docs)
- 🤖 **Agent Configuration**: Create and edit AI agents visually
- 🔌 **MCP Server Management**: Add and configure Model Context Protocol servers
- 🎨 **Dual-Pane Editor**: Select resources and MCP servers with checkboxes
- 🔄 **Auto-Export**: Agents automatically export to Q CLI directory
## ✨ Key Features
### 🖥️ **TUI (Terminal User Interface)**
- **Dual-Pane Editor**: Resources on left, agent config on right
- **Multi-Select**: Use Space to select multiple files/servers
- **Keyboard Navigation**: Arrow keys + shortcuts (no mouse needed)
- **Live Preview**: See current agent configuration while editing
- **Auto-Export**: Changes sync to Q CLI automatically
### 📚 **Library System**
- **Base Library**: Shared templates and rules (5 default templates included)
- **Personal Library**: Your custom files
- **Clone & Edit**: Copy base files to personal for customization
- **Visual Separation**: Clear distinction between base and personal files
### 🔌 **MCP Server Management**
- **Paste Configs**: Copy JSON from internet, paste directly
- **Flexible Parsing**: Handles multiple JSON formats
- **Edit Configs**: Modify server settings in your editor
- **Registry**: Browse and add servers from MCP registry
## 📦 Installation
```bash
# Install from PyPI
pip install ai-agent-manager
# Or install from source
git clone https://github.com/jschwellach/ai-configurator.git
cd ai-configurator
pip install -e .
```
## 🚀 Quick Start
### Launch TUI
```bash
ai-agent-manager
# or shorthand:
ai-config
# Navigate with:
# 1 - Agent Management
# 2 - Library Management
# 3 - MCP Servers
# 4 - Settings
# ? - Help
# q - Quit
```
### Using CLI (For Automation)
```bash
# Create an agent
ai-config agent create my-agent --tool q-cli
# List agents
ai-config agent list
# Sync library
ai-config library sync
# Browse MCP servers
ai-config mcp browse
# Get help
ai-config --help
```
## 📚 Features
### 🏗️ **Core Features**
- **Tool-Agnostic Library**: Pure markdown knowledge that works with any AI tool
- **Role-Based Organization**: Knowledge organized around roles
- **Multi-Tool Agent Support**: Amazon Q CLI, Claude Projects, ChatGPT (planned)
- **File References**: Agents reference library files without duplication
- **MCP Integration**: Full MCP server management
- **Cross-Platform**: Windows, macOS, and Linux
### 🔄 **Library Management**
- **Synchronization**: Conflict-aware sync between base and personal libraries
- **Local Files**: Include project files using glob patterns
- **Git Integration**: Clone, sync, and collaborate via Git
- **Performance**: Intelligent caching with 3.3x speedup
### 🖥️ **User Experience**
- **TUI Mode**: Visual, menu-driven interface
- **CLI Mode**: Simplified, consistent commands
- **Interactive Wizards**: Step-by-step setup
- **Template System**: Pre-built agent templates
## 📖 Documentation
- [TUI User Guide](docs/TUI_GUIDE.md) - Complete TUI usage guide
- [Migration Guide](docs/MIGRATION_GUIDE_V4.md) - Upgrading from v3.x
- [Keyboard Shortcuts](docs/KEYBOARD_SHORTCUTS.md) - Quick reference
- [User Guide](docs/USER_GUIDE.md) - Comprehensive documentation
- [Troubleshooting](docs/TROUBLESHOOTING.md) - Common issues
## 🎮 Usage Examples
### Agent Management
```bash
# CLI
ai-config agent create my-agent
ai-config agent list
ai-config agent export my-agent
# TUI
ai-config # Navigate to Agent Management
```
### Library Management
```bash
# CLI
ai-config library status
ai-config library sync
ai-config library files "**/*.md"
# TUI
ai-config # Navigate to Library Management
```
### MCP Server Management
```bash
# CLI
ai-config mcp browse
ai-config mcp install filesystem
ai-config mcp list
# TUI
ai-config # Navigate to MCP Servers
```
## 🔑 Key Commands
| Command | Description |
|---------|-------------|
| `ai-config` | Launch TUI |
| `ai-config agent list` | List all agents |
| `ai-config agent create <name>` | Create new agent |
| `ai-config library sync` | Sync library |
| `ai-config mcp browse` | Browse MCP servers |
| `ai-config status` | Show system status |
| `ai-config --help` | Show help |
## 🎯 Quick Start
### Using TUI (Recommended for New Users)
```bash
# Launch TUI
ai-config
# Navigate with:
# 1 - Agent Management
# 2 - Library Management
# 3 - MCP Servers
# 4 - Settings
# ? - Help
# q - Quit
```
### Using CLI (For Automation)
```bash
# Create an agent
ai-config agent create my-agent --tool q-cli
# List agents
ai-config agent list
# Sync library
ai-config library sync
# Browse MCP servers
ai-config mcp browse
# Get help
ai-config --help
```
cd ai-configurator
pip install -r requirements-dev.txt
pip install -e .
```
## 🚀 Quick Start
### New User Setup
```bash
# Complete interactive setup for new users
ai-config wizard quick-start
# Or step by step:
ai-config status # Check system status
ai-config library sync # Sync knowledge library
ai-config wizard create-agent # Create your first agent
```
### Existing Users
```bash
# Check system status
ai-config status
# Sync library with conflict resolution
ai-config library sync
# Browse available MCP servers
ai-config mcp browse
# Create agent from template
ai-config wizard create-agent
```
## 📚 Command Reference
### 🚀 Production Management (Phase 3)
```bash
# Git-based library management
ai-config git clone <repo-url> # Clone remote library
ai-config git pull # Pull updates
ai-config git push # Push changes
ai-config git status # Show Git status
ai-config git sync # Sync with remote
# Enhanced synchronization
ai-config sync all # Sync all libraries
ai-config sync source remote # Sync specific source
ai-config sync status # Show sync status
# Performance and caching
ai-config cache stats # Show cache statistics
ai-config cache benchmark # Run performance test
ai-config cache preload # Preload cache
ai-config cache clear # Clear cache
# Production configuration
ai-config production show # Show config
ai-config production environments # List environments
ai-config production validate --env production
ai-config production generate --env production
# Monitoring and logging
ai-config monitoring health # System health check
ai-config monitoring logs # View logs
ai-config monitoring stats # Log statistics
ai-config monitoring setup # Setup logging
```
### 🔄 Library Management
```bash
# Library synchronization
ai-config library status # Show sync status
ai-config library sync # Sync with conflict resolution
ai-config library diff # Show differences
ai-config library update # Update from base library
# View library content
ai-config status # System overview
```
### 📁 File Management
```bash
# Discover and add local files
ai-config files scan-files <agent> --pattern "**/*.md"
ai-config files add-files <agent> --pattern "./docs/**/*.md"
ai-config files watch-files <agent> --enable
# Examples
ai-config files scan-files my-agent --pattern "**/*.py" --base-path .
ai-config files add-files dev-agent --pattern "./rules/**/*.md"
```
### 🔧 MCP Server Management
```bash
# Browse and discover servers
ai-config mcp browse # Browse available servers
ai-config mcp search git # Search for specific servers
ai-config mcp status # Show registry status
# Install and manage servers
ai-config mcp install filesystem # Install a server
ai-config mcp create-sample # Create sample registry
```
### 🧙 Interactive Wizards
```bash
# Setup wizards
ai-config wizard quick-start # Complete new user setup
ai-config wizard create-agent # Interactive agent creation
ai-config wizard setup-mcp <agent> # MCP server setup
# Agent management
ai-config create-agent # Create new agent
ai-config manage-agent <name> # Interactive management
ai-config export-agent <name> --save # Export to Q CLI
```
## 🏗️ Architecture
### Library Structure
```
~/.config/ai-configurator/
├── library/ # Base knowledge library
│ ├── roles/ # Role-specific knowledge
│ ├── domains/ # Domain expertise
│ ├── workflows/ # Process documentation
│ ├── tools/ # Tool-specific guides
│ ├── templates/ # Agent templates (NEW!)
│ └── common/ # Shared knowledge
├── personal/ # Personal customizations (NEW!)
├── agents/ # Agent configurations
├── registry/ # MCP server registry (NEW!)
└── backups/ # Automatic backups (NEW!)
```
### Agent Templates
Pre-built templates for common roles:
- **Software Engineer**: Development-focused with Git, filesystem tools
- **Software Architect**: Architecture and design patterns
- **System Administrator**: Infrastructure and operations
- **Daily Assistant**: General productivity and task management
- **Product Owner**: Product management and planning
## 🔧 Advanced Usage
### Library Synchronization
```bash
# Check for conflicts before syncing
ai-config library sync --dry-run
# Interactive conflict resolution
ai-config library sync
# Show detailed differences
ai-config library diff --file specific-file.md
```
### Local File Integration
```bash
# Add project-specific files to agents
ai-config files add-files my-agent --pattern "./docs/**/*.md"
ai-config files add-files my-agent --pattern "./rules/*.txt"
# Enable file watching for auto-updates
ai-config files watch-files my-agent --enable
# Scan for files without adding
ai-config files scan-files my-agent --pattern "**/*.py" --base-path ./src
```
### MCP Server Management
```bash
# Create sample registry for testing
ai-config mcp create-sample
# Browse servers by category
ai-config mcp browse --category development
# Search for specific functionality
ai-config mcp search database
ai-config mcp search "file system"
# Install servers for enhanced capabilities
ai-config mcp install git
ai-config mcp install filesystem
```
### Template Usage
Templates are stored in `library/templates/` and can be:
- Used during agent creation via wizards
- Customized in your personal library
- Shared through library synchronization
- Created by copying existing role files
## 🛠️ Development
### Running Tests
```bash
# Run all tests
pytest
# Run Phase 2 specific tests
pytest tests/test_phase2_*.py -v
# Run with coverage
pytest --cov=ai_configurator
```
### Project Structure
```
ai_configurator/
├── models/ # Pydantic data models
│ ├── sync_models.py # Library sync models (NEW!)
│ ├── file_models.py # File management models (NEW!)
│ ├── registry_models.py # MCP registry models (NEW!)
│ └── wizard_models.py # Wizard models (NEW!)
├── services/ # Business logic services
│ ├── sync_service.py # Library synchronization (NEW!)
│ ├── file_service.py # File management (NEW!)
│ ├── registry_service.py # MCP registry (NEW!)
│ └── wizard_service.py # Interactive wizards (NEW!)
├── cli/ # CLI command modules (NEW!)
│ ├── sync_commands.py # Library sync commands
│ ├── file_commands.py # File management commands
│ ├── registry_commands.py # MCP registry commands
│ └── wizard_commands.py # Wizard commands
└── cli_enhanced.py # Main CLI interface
```
## 🔄 Migration from Phase 1
Phase 2 maintains full backward compatibility with Phase 1 configurations. Your existing agents and MCP servers will continue to work without changes.
New features are additive and optional:
- Library sync is available but not required
- Local file integration is opt-in per agent
- MCP registry enhances but doesn't replace existing MCP management
- Wizards provide alternative setup methods alongside existing commands
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass (`pytest`)
6. Commit your changes (`git commit -m 'Add amazing feature'`)
7. Push to the branch (`git push origin feature/amazing-feature`)
8. Open a Pull Request
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🆘 Support
- **Documentation**: Check this README and inline help (`ai-config --help`)
- **Issues**: Report bugs and request features via GitHub Issues
- **Discussions**: Join community discussions for questions and ideas
## 🎉 What's New
### 🚀 **Phase 3: Production Ready** (Latest)
- Git-based library management with remote repositories
- Performance optimization with intelligent caching (3.3x speedup)
- Production configuration management with environment support
- Comprehensive logging and error handling
- Health monitoring and system diagnostics
### ✅ **Phase 2: Advanced Library Management**
- Conflict-aware library sync with interactive resolution
- Local file integration with glob patterns and file watching
- MCP server registry with discovery and installation
- Interactive wizards and pre-built templates
### 🏗️ **Phase 1: Foundation**
- Tool-agnostic knowledge library system
- Multi-tool agent support (Q CLI, Claude, ChatGPT)
- Role-based organization and MCP integration
---
**AI Configurator v4.0.0** - Production-ready tool-agnostic knowledge library manager
# Navigate with arrow keys, Enter to select, Esc to go back
```
### Create Your First Agent
1. **Launch TUI**: `ai-config`
2. **Select "Agent Management"**
3. **Press `n` to create new agent**
4. **Press `e` to edit the agent**
5. **Select resources** with Space key
6. **Select MCP servers** with Space key
7. **Press Ctrl+S to save**
8. **Agent auto-exports to Q CLI!**
## 📖 Usage Guide
### Agent Management
**Keyboard Shortcuts:**
- `n` - Create new agent
- `e` - Edit selected agent
- `m` - Rename agent
- `d` - Delete agent
- `x` - Export to Q CLI
- `r` - Refresh list
**Agent Editor:**
- `Space` - Toggle selection (checkbox)
- `Tab` - Switch between tables
- `↑/↓` - Navigate items
- `Ctrl+S` - Save changes
- `Esc` - Cancel
### Library Management
**Keyboard Shortcuts:**
- `n` - Create new file
- `e` - Edit file (personal files only)
- `c` - Clone file (base → personal)
- `r` - Refresh list
### MCP Server Management
**Keyboard Shortcuts:**
- `a` - Add new server
- `e` - Edit server config
- `d` - Delete server
- `s` - Sync registry
- `r` - Refresh list
**Supported JSON Formats:**
```json
// Format 1: mcpServers wrapper
{
"mcpServers": {
"server-name": {
"command": "npx",
"args": ["@package/server"]
}
}
}
// Format 2: Direct entry (auto-wrapped)
"server-name": {
"command": "npx",
"args": ["@package/server"]
}
```
## 🗂️ Directory Structure
```
~/.config/ai-configurator/
├── agents/ # Agent configurations
├── library/
│ ├── base/ # Shared templates
│ └── personal/ # Your custom files
├── registry/
│ └── servers/ # MCP server configs
└── logs/
└── tui.log # Application logs
~/.aws/amazonq/cli-agents/ # Q CLI agents (auto-synced)
```
## 🔧 CLI Commands
```bash
# Agent commands
ai-config agent list
ai-config agent create my-agent
ai-config agent export my-agent
# Library commands
ai-config library list
# MCP commands
ai-config mcp list
# System commands
ai-config status
```
## 🐛 Troubleshooting
### Agent not appearing in Q CLI
```bash
# Check if exported
ls ~/.aws/amazonq/cli-agents/
# Manual export
ai-config agent export my-agent
```
### Editor not opening
```bash
# Set your preferred editor
export EDITOR=vim # or kate, nano, etc.
```
## 📚 Documentation
- [TUI Guide](docs/TUI_GUIDE.md)
- [Agent Editor Guide](docs/AGENT_EDITOR_GUIDE.md)
- [Keyboard Shortcuts](docs/KEYBOARD_SHORTCUTS.md)
## 📄 License
MIT License - see [LICENSE](LICENSE) for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "ai-agent-manager",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "agents, ai, amazon-q, claude, configuration, knowledge-management, mcp, tui",
"author": "AI Configurator Team",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/0f/52/58384c1b47cf89ab7bc5cd0aa82f34cdf24e388dd8d2b94644c770aab925/ai_agent_manager-0.2.3.tar.gz",
"platform": null,
"description": "# AI Agent Manager v0.1.0 (Beta)\n\n**Terminal UI for managing AI agents, resources, and MCP servers across multiple AI tools.**\n\n## \ud83c\udfaf What It Does\n\nAI Agent Manager helps you manage AI agents (Amazon Q CLI, Claude, etc.) with a visual terminal interface:\n- \ud83d\udcda **Library Management**: Organize knowledge files (templates, rules, docs)\n- \ud83e\udd16 **Agent Configuration**: Create and edit AI agents visually\n- \ud83d\udd0c **MCP Server Management**: Add and configure Model Context Protocol servers\n- \ud83c\udfa8 **Dual-Pane Editor**: Select resources and MCP servers with checkboxes\n- \ud83d\udd04 **Auto-Export**: Agents automatically export to Q CLI directory\n\n## \u2728 Key Features\n\n### \ud83d\udda5\ufe0f **TUI (Terminal User Interface)**\n- **Dual-Pane Editor**: Resources on left, agent config on right\n- **Multi-Select**: Use Space to select multiple files/servers\n- **Keyboard Navigation**: Arrow keys + shortcuts (no mouse needed)\n- **Live Preview**: See current agent configuration while editing\n- **Auto-Export**: Changes sync to Q CLI automatically\n\n### \ud83d\udcda **Library System**\n- **Base Library**: Shared templates and rules (5 default templates included)\n- **Personal Library**: Your custom files\n- **Clone & Edit**: Copy base files to personal for customization\n- **Visual Separation**: Clear distinction between base and personal files\n\n### \ud83d\udd0c **MCP Server Management**\n- **Paste Configs**: Copy JSON from internet, paste directly\n- **Flexible Parsing**: Handles multiple JSON formats\n- **Edit Configs**: Modify server settings in your editor\n- **Registry**: Browse and add servers from MCP registry\n\n## \ud83d\udce6 Installation\n\n```bash\n# Install from PyPI\npip install ai-agent-manager\n\n# Or install from source\ngit clone https://github.com/jschwellach/ai-configurator.git\ncd ai-configurator\npip install -e .\n```\n\n## \ud83d\ude80 Quick Start\n\n### Launch TUI\n```bash\nai-agent-manager\n# or shorthand:\nai-config\n\n# Navigate with:\n# 1 - Agent Management\n# 2 - Library Management\n# 3 - MCP Servers\n# 4 - Settings\n# ? - Help\n# q - Quit\n```\n\n### Using CLI (For Automation)\n```bash\n# Create an agent\nai-config agent create my-agent --tool q-cli\n\n# List agents\nai-config agent list\n\n# Sync library\nai-config library sync\n\n# Browse MCP servers\nai-config mcp browse\n\n# Get help\nai-config --help\n```\n\n## \ud83d\udcda Features\n\n### \ud83c\udfd7\ufe0f **Core Features**\n- **Tool-Agnostic Library**: Pure markdown knowledge that works with any AI tool\n- **Role-Based Organization**: Knowledge organized around roles\n- **Multi-Tool Agent Support**: Amazon Q CLI, Claude Projects, ChatGPT (planned)\n- **File References**: Agents reference library files without duplication\n- **MCP Integration**: Full MCP server management\n- **Cross-Platform**: Windows, macOS, and Linux\n\n### \ud83d\udd04 **Library Management**\n- **Synchronization**: Conflict-aware sync between base and personal libraries\n- **Local Files**: Include project files using glob patterns\n- **Git Integration**: Clone, sync, and collaborate via Git\n- **Performance**: Intelligent caching with 3.3x speedup\n\n### \ud83d\udda5\ufe0f **User Experience**\n- **TUI Mode**: Visual, menu-driven interface\n- **CLI Mode**: Simplified, consistent commands\n- **Interactive Wizards**: Step-by-step setup\n- **Template System**: Pre-built agent templates\n\n## \ud83d\udcd6 Documentation\n\n- [TUI User Guide](docs/TUI_GUIDE.md) - Complete TUI usage guide\n- [Migration Guide](docs/MIGRATION_GUIDE_V4.md) - Upgrading from v3.x\n- [Keyboard Shortcuts](docs/KEYBOARD_SHORTCUTS.md) - Quick reference\n- [User Guide](docs/USER_GUIDE.md) - Comprehensive documentation\n- [Troubleshooting](docs/TROUBLESHOOTING.md) - Common issues\n\n## \ud83c\udfae Usage Examples\n\n### Agent Management\n```bash\n# CLI\nai-config agent create my-agent\nai-config agent list\nai-config agent export my-agent\n\n# TUI\nai-config # Navigate to Agent Management\n```\n\n### Library Management\n```bash\n# CLI\nai-config library status\nai-config library sync\nai-config library files \"**/*.md\"\n\n# TUI\nai-config # Navigate to Library Management\n```\n\n### MCP Server Management\n```bash\n# CLI\nai-config mcp browse\nai-config mcp install filesystem\nai-config mcp list\n\n# TUI\nai-config # Navigate to MCP Servers\n```\n\n## \ud83d\udd11 Key Commands\n\n| Command | Description |\n|---------|-------------|\n| `ai-config` | Launch TUI |\n| `ai-config agent list` | List all agents |\n| `ai-config agent create <name>` | Create new agent |\n| `ai-config library sync` | Sync library |\n| `ai-config mcp browse` | Browse MCP servers |\n| `ai-config status` | Show system status |\n| `ai-config --help` | Show help |\n\n## \ud83c\udfaf Quick Start\n\n### Using TUI (Recommended for New Users)\n```bash\n# Launch TUI\nai-config\n\n# Navigate with:\n# 1 - Agent Management\n# 2 - Library Management\n# 3 - MCP Servers\n# 4 - Settings\n# ? - Help\n# q - Quit\n```\n\n### Using CLI (For Automation)\n```bash\n# Create an agent\nai-config agent create my-agent --tool q-cli\n\n# List agents\nai-config agent list\n\n# Sync library\nai-config library sync\n\n# Browse MCP servers\nai-config mcp browse\n\n# Get help\nai-config --help\n```\ncd ai-configurator\npip install -r requirements-dev.txt\npip install -e .\n```\n\n## \ud83d\ude80 Quick Start\n\n### New User Setup\n```bash\n# Complete interactive setup for new users\nai-config wizard quick-start\n\n# Or step by step:\nai-config status # Check system status\nai-config library sync # Sync knowledge library\nai-config wizard create-agent # Create your first agent\n```\n\n### Existing Users\n```bash\n# Check system status\nai-config status\n\n# Sync library with conflict resolution\nai-config library sync\n\n# Browse available MCP servers\nai-config mcp browse\n\n# Create agent from template\nai-config wizard create-agent\n```\n\n## \ud83d\udcda Command Reference\n\n### \ud83d\ude80 Production Management (Phase 3)\n```bash\n# Git-based library management\nai-config git clone <repo-url> # Clone remote library\nai-config git pull # Pull updates\nai-config git push # Push changes\nai-config git status # Show Git status\nai-config git sync # Sync with remote\n\n# Enhanced synchronization\nai-config sync all # Sync all libraries\nai-config sync source remote # Sync specific source\nai-config sync status # Show sync status\n\n# Performance and caching\nai-config cache stats # Show cache statistics\nai-config cache benchmark # Run performance test\nai-config cache preload # Preload cache\nai-config cache clear # Clear cache\n\n# Production configuration\nai-config production show # Show config\nai-config production environments # List environments\nai-config production validate --env production\nai-config production generate --env production\n\n# Monitoring and logging\nai-config monitoring health # System health check\nai-config monitoring logs # View logs\nai-config monitoring stats # Log statistics\nai-config monitoring setup # Setup logging\n```\n\n### \ud83d\udd04 Library Management\n```bash\n# Library synchronization\nai-config library status # Show sync status\nai-config library sync # Sync with conflict resolution\nai-config library diff # Show differences\nai-config library update # Update from base library\n\n# View library content\nai-config status # System overview\n```\n\n### \ud83d\udcc1 File Management\n```bash\n# Discover and add local files\nai-config files scan-files <agent> --pattern \"**/*.md\"\nai-config files add-files <agent> --pattern \"./docs/**/*.md\"\nai-config files watch-files <agent> --enable\n\n# Examples\nai-config files scan-files my-agent --pattern \"**/*.py\" --base-path .\nai-config files add-files dev-agent --pattern \"./rules/**/*.md\"\n```\n\n### \ud83d\udd27 MCP Server Management\n```bash\n# Browse and discover servers\nai-config mcp browse # Browse available servers\nai-config mcp search git # Search for specific servers\nai-config mcp status # Show registry status\n\n# Install and manage servers\nai-config mcp install filesystem # Install a server\nai-config mcp create-sample # Create sample registry\n```\n\n### \ud83e\uddd9 Interactive Wizards\n```bash\n# Setup wizards\nai-config wizard quick-start # Complete new user setup\nai-config wizard create-agent # Interactive agent creation\nai-config wizard setup-mcp <agent> # MCP server setup\n\n# Agent management\nai-config create-agent # Create new agent\nai-config manage-agent <name> # Interactive management\nai-config export-agent <name> --save # Export to Q CLI\n```\n\n## \ud83c\udfd7\ufe0f Architecture\n\n### Library Structure\n```\n~/.config/ai-configurator/\n\u251c\u2500\u2500 library/ # Base knowledge library\n\u2502 \u251c\u2500\u2500 roles/ # Role-specific knowledge\n\u2502 \u251c\u2500\u2500 domains/ # Domain expertise\n\u2502 \u251c\u2500\u2500 workflows/ # Process documentation\n\u2502 \u251c\u2500\u2500 tools/ # Tool-specific guides\n\u2502 \u251c\u2500\u2500 templates/ # Agent templates (NEW!)\n\u2502 \u2514\u2500\u2500 common/ # Shared knowledge\n\u251c\u2500\u2500 personal/ # Personal customizations (NEW!)\n\u251c\u2500\u2500 agents/ # Agent configurations\n\u251c\u2500\u2500 registry/ # MCP server registry (NEW!)\n\u2514\u2500\u2500 backups/ # Automatic backups (NEW!)\n```\n\n### Agent Templates\nPre-built templates for common roles:\n- **Software Engineer**: Development-focused with Git, filesystem tools\n- **Software Architect**: Architecture and design patterns\n- **System Administrator**: Infrastructure and operations\n- **Daily Assistant**: General productivity and task management\n- **Product Owner**: Product management and planning\n\n## \ud83d\udd27 Advanced Usage\n\n### Library Synchronization\n```bash\n# Check for conflicts before syncing\nai-config library sync --dry-run\n\n# Interactive conflict resolution\nai-config library sync\n\n# Show detailed differences\nai-config library diff --file specific-file.md\n```\n\n### Local File Integration\n```bash\n# Add project-specific files to agents\nai-config files add-files my-agent --pattern \"./docs/**/*.md\"\nai-config files add-files my-agent --pattern \"./rules/*.txt\"\n\n# Enable file watching for auto-updates\nai-config files watch-files my-agent --enable\n\n# Scan for files without adding\nai-config files scan-files my-agent --pattern \"**/*.py\" --base-path ./src\n```\n\n### MCP Server Management\n```bash\n# Create sample registry for testing\nai-config mcp create-sample\n\n# Browse servers by category\nai-config mcp browse --category development\n\n# Search for specific functionality\nai-config mcp search database\nai-config mcp search \"file system\"\n\n# Install servers for enhanced capabilities\nai-config mcp install git\nai-config mcp install filesystem\n```\n\n### Template Usage\nTemplates are stored in `library/templates/` and can be:\n- Used during agent creation via wizards\n- Customized in your personal library\n- Shared through library synchronization\n- Created by copying existing role files\n\n## \ud83d\udee0\ufe0f Development\n\n### Running Tests\n```bash\n# Run all tests\npytest\n\n# Run Phase 2 specific tests\npytest tests/test_phase2_*.py -v\n\n# Run with coverage\npytest --cov=ai_configurator\n```\n\n### Project Structure\n```\nai_configurator/\n\u251c\u2500\u2500 models/ # Pydantic data models\n\u2502 \u251c\u2500\u2500 sync_models.py # Library sync models (NEW!)\n\u2502 \u251c\u2500\u2500 file_models.py # File management models (NEW!)\n\u2502 \u251c\u2500\u2500 registry_models.py # MCP registry models (NEW!)\n\u2502 \u2514\u2500\u2500 wizard_models.py # Wizard models (NEW!)\n\u251c\u2500\u2500 services/ # Business logic services\n\u2502 \u251c\u2500\u2500 sync_service.py # Library synchronization (NEW!)\n\u2502 \u251c\u2500\u2500 file_service.py # File management (NEW!)\n\u2502 \u251c\u2500\u2500 registry_service.py # MCP registry (NEW!)\n\u2502 \u2514\u2500\u2500 wizard_service.py # Interactive wizards (NEW!)\n\u251c\u2500\u2500 cli/ # CLI command modules (NEW!)\n\u2502 \u251c\u2500\u2500 sync_commands.py # Library sync commands\n\u2502 \u251c\u2500\u2500 file_commands.py # File management commands\n\u2502 \u251c\u2500\u2500 registry_commands.py # MCP registry commands\n\u2502 \u2514\u2500\u2500 wizard_commands.py # Wizard commands\n\u2514\u2500\u2500 cli_enhanced.py # Main CLI interface\n```\n\n## \ud83d\udd04 Migration from Phase 1\n\nPhase 2 maintains full backward compatibility with Phase 1 configurations. Your existing agents and MCP servers will continue to work without changes.\n\nNew features are additive and optional:\n- Library sync is available but not required\n- Local file integration is opt-in per agent\n- MCP registry enhances but doesn't replace existing MCP management\n- Wizards provide alternative setup methods alongside existing commands\n\n## \ud83e\udd1d Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Add tests for new functionality\n5. Ensure all tests pass (`pytest`)\n6. Commit your changes (`git commit -m 'Add amazing feature'`)\n7. Push to the branch (`git push origin feature/amazing-feature`)\n8. Open a Pull Request\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83c\udd98 Support\n\n- **Documentation**: Check this README and inline help (`ai-config --help`)\n- **Issues**: Report bugs and request features via GitHub Issues\n- **Discussions**: Join community discussions for questions and ideas\n\n## \ud83c\udf89 What's New\n\n### \ud83d\ude80 **Phase 3: Production Ready** (Latest)\n- Git-based library management with remote repositories\n- Performance optimization with intelligent caching (3.3x speedup)\n- Production configuration management with environment support\n- Comprehensive logging and error handling\n- Health monitoring and system diagnostics\n\n### \u2705 **Phase 2: Advanced Library Management**\n- Conflict-aware library sync with interactive resolution\n- Local file integration with glob patterns and file watching\n- MCP server registry with discovery and installation\n- Interactive wizards and pre-built templates\n\n### \ud83c\udfd7\ufe0f **Phase 1: Foundation**\n- Tool-agnostic knowledge library system\n- Multi-tool agent support (Q CLI, Claude, ChatGPT)\n- Role-based organization and MCP integration\n\n---\n\n**AI Configurator v4.0.0** - Production-ready tool-agnostic knowledge library manager\n\n\n# Navigate with arrow keys, Enter to select, Esc to go back\n```\n\n### Create Your First Agent\n\n1. **Launch TUI**: `ai-config`\n2. **Select \"Agent Management\"**\n3. **Press `n` to create new agent**\n4. **Press `e` to edit the agent**\n5. **Select resources** with Space key\n6. **Select MCP servers** with Space key \n7. **Press Ctrl+S to save**\n8. **Agent auto-exports to Q CLI!**\n\n## \ud83d\udcd6 Usage Guide\n\n### Agent Management\n\n**Keyboard Shortcuts:**\n- `n` - Create new agent\n- `e` - Edit selected agent\n- `m` - Rename agent\n- `d` - Delete agent\n- `x` - Export to Q CLI\n- `r` - Refresh list\n\n**Agent Editor:**\n- `Space` - Toggle selection (checkbox)\n- `Tab` - Switch between tables\n- `\u2191/\u2193` - Navigate items\n- `Ctrl+S` - Save changes\n- `Esc` - Cancel\n\n### Library Management\n\n**Keyboard Shortcuts:**\n- `n` - Create new file\n- `e` - Edit file (personal files only)\n- `c` - Clone file (base \u2192 personal)\n- `r` - Refresh list\n\n### MCP Server Management\n\n**Keyboard Shortcuts:**\n- `a` - Add new server\n- `e` - Edit server config\n- `d` - Delete server\n- `s` - Sync registry\n- `r` - Refresh list\n\n**Supported JSON Formats:**\n```json\n// Format 1: mcpServers wrapper\n{\n \"mcpServers\": {\n \"server-name\": {\n \"command\": \"npx\",\n \"args\": [\"@package/server\"]\n }\n }\n}\n\n// Format 2: Direct entry (auto-wrapped)\n\"server-name\": {\n \"command\": \"npx\",\n \"args\": [\"@package/server\"]\n}\n```\n\n## \ud83d\uddc2\ufe0f Directory Structure\n\n```\n~/.config/ai-configurator/\n\u251c\u2500\u2500 agents/ # Agent configurations\n\u251c\u2500\u2500 library/\n\u2502 \u251c\u2500\u2500 base/ # Shared templates\n\u2502 \u2514\u2500\u2500 personal/ # Your custom files\n\u251c\u2500\u2500 registry/\n\u2502 \u2514\u2500\u2500 servers/ # MCP server configs\n\u2514\u2500\u2500 logs/\n \u2514\u2500\u2500 tui.log # Application logs\n\n~/.aws/amazonq/cli-agents/ # Q CLI agents (auto-synced)\n```\n\n## \ud83d\udd27 CLI Commands\n\n```bash\n# Agent commands\nai-config agent list\nai-config agent create my-agent\nai-config agent export my-agent\n\n# Library commands\nai-config library list\n\n# MCP commands\nai-config mcp list\n\n# System commands\nai-config status\n```\n\n## \ud83d\udc1b Troubleshooting\n\n### Agent not appearing in Q CLI\n```bash\n# Check if exported\nls ~/.aws/amazonq/cli-agents/\n\n# Manual export\nai-config agent export my-agent\n```\n\n### Editor not opening\n```bash\n# Set your preferred editor\nexport EDITOR=vim # or kate, nano, etc.\n```\n\n## \ud83d\udcda Documentation\n\n- [TUI Guide](docs/TUI_GUIDE.md)\n- [Agent Editor Guide](docs/AGENT_EDITOR_GUIDE.md)\n- [Keyboard Shortcuts](docs/KEYBOARD_SHORTCUTS.md)\n\n## \ud83d\udcc4 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n",
"bugtrack_url": null,
"license": null,
"summary": "Terminal UI for managing AI agents, resources, and MCP servers across multiple AI tools",
"version": "0.2.3",
"project_urls": {
"Bug Tracker": "https://github.com/jschwellach/ai-configurator/issues",
"Documentation": "https://github.com/jschwellach/ai-configurator#readme",
"Homepage": "https://github.com/jschwellach/ai-configurator",
"Repository": "https://github.com/jschwellach/ai-configurator.git"
},
"split_keywords": [
"agents",
" ai",
" amazon-q",
" claude",
" configuration",
" knowledge-management",
" mcp",
" tui"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4253ed5eb020493b5228e53773ba54e2ca0e4b69362762c049487cd7ffdfb00e",
"md5": "5432b3208d50def17d4f8997c9b3c83f",
"sha256": "9f18be8a2ad7978273bfebb2969b90e09b09e0f6413c4102ac2121f65913b896"
},
"downloads": -1,
"filename": "ai_agent_manager-0.2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5432b3208d50def17d4f8997c9b3c83f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 161028,
"upload_time": "2025-10-08T06:00:19",
"upload_time_iso_8601": "2025-10-08T06:00:19.174727Z",
"url": "https://files.pythonhosted.org/packages/42/53/ed5eb020493b5228e53773ba54e2ca0e4b69362762c049487cd7ffdfb00e/ai_agent_manager-0.2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0f5258384c1b47cf89ab7bc5cd0aa82f34cdf24e388dd8d2b94644c770aab925",
"md5": "607b941e77ab8ee0944738c4cde02ab0",
"sha256": "05992a2f487a69db78e7c5d6c7aaca3cb4c73fc8441c845d98828eda3f4bb2fd"
},
"downloads": -1,
"filename": "ai_agent_manager-0.2.3.tar.gz",
"has_sig": false,
"md5_digest": "607b941e77ab8ee0944738c4cde02ab0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 115016,
"upload_time": "2025-10-08T06:00:20",
"upload_time_iso_8601": "2025-10-08T06:00:20.773720Z",
"url": "https://files.pythonhosted.org/packages/0f/52/58384c1b47cf89ab7bc5cd0aa82f34cdf24e388dd8d2b94644c770aab925/ai_agent_manager-0.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-08 06:00:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jschwellach",
"github_project": "ai-configurator",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "click",
"specs": [
[
">=",
"8.0.0"
]
]
},
{
"name": "click-default-group",
"specs": [
[
">=",
"1.2.2"
]
]
},
{
"name": "rich",
"specs": [
[
">=",
"13.0.0"
]
]
},
{
"name": "textual",
"specs": [
[
">=",
"0.40.0"
]
]
},
{
"name": "pydantic",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "pyyaml",
"specs": [
[
">=",
"6.0.0"
]
]
},
{
"name": "jsonschema",
"specs": [
[
">=",
"4.17.0"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.28.0"
]
]
},
{
"name": "packaging",
"specs": [
[
">=",
"21.0.0"
]
]
},
{
"name": "platformdirs",
"specs": [
[
">=",
"3.0.0"
]
]
},
{
"name": "watchdog",
"specs": [
[
">=",
"3.0.0"
]
]
},
{
"name": "prompt-toolkit",
"specs": [
[
">=",
"3.0.0"
]
]
},
{
"name": "gitpython",
"specs": [
[
">=",
"3.1.0"
]
]
},
{
"name": "jinja2",
"specs": [
[
">=",
"3.0.0"
]
]
}
],
"lcname": "ai-agent-manager"
}
JSON
