Morgana Agent Development Assistant
Expert assistant for developing and working with Morgana Agent, a Go-based AI agent REPL that interfaces with Ollama for local LLM interactions.
Project Context
Morgana Agent is a sophisticated Go-based REPL that provides:
Interactive CLI interface with Ollama LLM integrationTool calling system with automatic detection and executionFile search, grep, and manipulation capabilitiesContext management and conversation historyApproval system for safe file operationsModel-specific prompt templatesExtensible architecture with registry patternsDevelopment Workflow
When working with Morgana Agent code, follow these steps:
1. Understanding the Codebase
Before making changes:
Read `main.go` to understand the core REPL loop and agent orchestrationReview `internal/search/` for file search and grep functionalityExamine `internal/repl/command_registry.go` for the command system architectureStudy `internal/tools/` to understand the tool calling mechanismCheck `internal/repl/prompt_system.go` for model-specific prompting logicReview `internal/theme/` for color palette and theme system2. Building and Running
```bash
Run directly for development
go run main.go
Build for production
go build -o morgana-agent
Set up environment configuration
cp .env.example .env
Edit .env with your settings
go run main.go
```
3. Managing Dependencies
```bash
Install dependencies
go mod download
Clean up dependencies
go mod tidy
```
4. Environment Configuration
Configure `.env` file with:
`OLLAMA_HOST`: Ollama server endpoint (default: `http://localhost:11434`)`OLLAMA_MODEL`: Model name (default: `llama3.2`)`AGENT_NAME`: Display name (default: `Morgana`)`AGENT_TEMPERATURE`: Response temperature (default: `0.7`)`AGENT_MAX_TOKENS`: Max tokens (default: `2048`)`AGENT_ENABLE_TOOLS`: Enable tool calling (default: `true`)`AGENT_APPROVAL_MODE`: File operation approval mode (interactive/auto/confirm/dry-run)`AGENT_THEME_MODE`: Color theme (auto/light/dark)`MORGANA_BUBBLE_TEA`: Force Bubble Tea UI mode (default: auto-detect)Core Architecture Components
Command Registry System
Thread-safe command registration and lookupCommand categorization (system, model, search, tools, appearance)Parameter validation metadataFuzzy search and autocomplete supportExtensible for new commandsTools System
Built-in tools include:
`search_files`: Pattern-based file search with gitignore support`find_in_files`: Content grep functionality`show_tree`: Project structure visualization`read_file`: Read file contents`fuzzy_find`: Fuzzy file/directory search`write_file`: Atomic file creation/writing`edit_file`: File editing (replace/insert/delete)`set_approval_mode`: Change approval mode`show_pending_changes`: View pending changes`apply_pending_changes`: Apply approved changesApproval System
Interactive file change preview with four modes:
`interactive`: Preview + confirmation per change`auto`: Automatic application`confirm`: Batch preview with single decision`dry-run`: Preview only, no applicationEnhanced Prompt System
Model-specific prompt templates with:
Progressive prompting and retry logicDynamic prompt building based on capabilitiesPerformance metrics trackingTemplate hot-reloadingModel profiles (Qwen, Llama, GPT, Claude, Gemma)Key Design Patterns
1. **Tool Registry Pattern**: Extensible tool system with self-describing parameters
2. **Search Options**: Flexible file/content search configuration
3. **REPL Commands**: Slash-command system for control
4. **Context Preservation**: Maintains conversation history
5. **Streaming Responses**: Real-time Ollama API output
6. **Atomic File Operations**: Safe writes using temp file + rename
7. **Security Sandboxing**: Path validation prevents external writes
Available REPL Commands
`/help` - Show available commands`/clear` - Clear conversation context`/history` - Show conversation history`/model` - Show current model`/switch <model>` - Switch models`/search <pattern>` - Search files by pattern`/find <text>` - Find text in files`/fuzzy <query>` - Fuzzy file search`/tree [depth]` - Show project structure`/tools on/off/list` - Manage tool calling`/approval [mode]` - Set approval mode`/config <cmd>` - Configuration management`/prompt [cmd]` - Prompt system commands`/theme [mode]` - Theme management`/exit` or `/quit` - Exit REPLMaking Changes
Adding New Tools
1. Define tool in `internal/tools/registry.go`
2. Implement execution logic with proper error handling
3. Add parameter validation
4. Update tool descriptions for LLM context
5. Test with various models
Adding New Commands
1. Register in `internal/repl/command_registry.go`
2. Define category, parameters, and help text
3. Implement command handler
4. Add to help system
5. Test fuzzy search and autocomplete
Modifying Prompt System
1. Edit templates in `internal/repl/prompt_system.go`
2. Update model profiles for specific capabilities
3. Test progressive prompting logic
4. Verify metrics tracking
5. Test hot-reload functionality
Theme Customization
1. Modify color palette in `internal/theme/`
2. Test in light, dark, and auto modes
3. Ensure accessibility and readability
4. Verify terminal compatibility
Testing Approach
When testing changes:
1. Run with different Ollama models to verify compatibility
2. Test tool calling with various file operations
3. Verify approval modes work correctly
4. Check theme rendering in different terminal emulators
5. Test error handling and recovery scenarios
6. Validate security boundaries for file operations
Security Considerations
Always validate file paths to prevent directory traversalUse atomic file operations to prevent corruptionRespect gitignore patterns in file searchesImplement proper approval flows for destructive operationsValidate tool parameters before executionPerformance Optimization
Use streaming for LLM responsesImplement efficient file search with proper filtersCache model profiles and prompt templatesMinimize memory allocations in hot pathsUse goroutines for concurrent operations where safeImportant Notes
The approval system auto-detects environment (TTY vs non-TTY)Model-specific prompts significantly improve tool usageFile operations use atomic writes (temp file + rename)Search respects `.gitignore` by defaultColor themes adapt to terminal capabilitiesProgressive prompting improves retry success rates