1  # Multi-Agent System - Usage Guide
  2  
  3  ## 🎉 Multi-Agent System is Now Live!
  4  
  5  Kamaji now supports specialized AI agents for different tasks. The system automatically routes your requests to the best agent, or you can explicitly select one.
  6  
  7  ---
  8  
  9  ## Quick Start
 10  
 11  ### In Chat Mode
 12  
 13  ```bash
 14  kamaji chat
 15  ```
 16  
 17  You'll see:
 18  ```
 19  🔥 Multi-Agent Mode: ENABLED
 20  
 21  🔥 Available Specialized Agents:
 22  
 23    @review
 24      Code review specialist - analyzes code quality, security, and best practices
 25  
 26    @docs
 27      Documentation specialist - writes READMEs, docstrings, and technical docs
 28  
 29    general
 30      General-purpose agent - handles filesystem, shell, and general tasks
 31  ```
 32  
 33  ### In TUI Mode
 34  
 35  ```bash
 36  kamaji tui
 37  ```
 38  
 39  Same multi-agent capabilities with a beautiful interface!
 40  
 41  ---
 42  
 43  ## How to Use
 44  
 45  ### Method 1: Explicit Agent Selection
 46  
 47  Use `@agent_name` prefix:
 48  
 49  ```
 50  You: @review Check kamaji/tools.py for security issues
 51  
 52  [Using @review agent]
 53  
 54  Kamaji: 🔍 Analyzing kamaji/tools.py...
 55  
 56  📊 Code Review Results:
 57  ✅ Syntax: No errors found
 58  ✅ Security: execute_shell_command has timeout (good!)
 59  ⚠️  Code Quality: Consider adding input validation
 60  💡 Suggestion: Add type hints to function signatures
 61  
 62  Overall Rating: 8/10
 63  ```
 64  
 65  ```
 66  You: @docs Write a README for the agents module
 67  
 68  [Using @docs agent]
 69  
 70  Kamaji: 📝 Creating documentation...
 71  
 72  ✅ Created README.md with:
 73  - Overview of multi-agent system
 74  - Available agents and their capabilities
 75  - Usage examples
 76  - Integration guide
 77  ```
 78  
 79  ### Method 2: Auto-Routing (Keywords)
 80  
 81  Just ask naturally - the system detects keywords:
 82  
 83  ```
 84  You: Review the authentication code
 85  
 86  [Using @review agent]
 87  → Auto-detected "review" keyword
 88  ```
 89  
 90  ```
 91  You: Document this module
 92  
 93  [Using @docs agent]
 94  → Auto-detected "document" keyword
 95  ```
 96  
 97  ```
 98  You: What files are in this directory?
 99  
100  [Using general agent]
101  → Default for general queries
102  ```
103  
104  ### Method 3: Get Help
105  
106  ```
107  You: @help
108  
109  🔥 Available Specialized Agents:
110  
111    @review
112      Code review specialist
113      Keywords: review, check code, analyze code, code quality, security
114  
115    @docs
116      Documentation specialist
117      Keywords: document, documentation, readme, docstring, write docs
118  
119    general
120      General-purpose agent
121      Handles: filesystem, shell, git, all other tasks
122  ```
123  
124  ---
125  
126  ## Available Agents
127  
128  ### @review - Code Review Specialist
129  
130  **Optimized for**: Analyzing code quality, finding bugs, security issues
131  
132  **Tools**:
133  - `read_file` - Read source code
134  - `check_syntax` - Validate Python syntax
135  - `count_lines` - Analyze code statistics
136  - `run_tests` - Execute linters and tests
137  - `list_directory` - Find files to review
138  
139  **Example Tasks**:
140  ```
141  @review Check auth.py for security vulnerabilities
142  @review Analyze the entire project for code quality
143  @review Find potential bugs in user_manager.py
144  Review the API endpoint implementations
145  ```
146  
147  ### @docs - Documentation Specialist
148  
149  **Optimized for**: Writing documentation, READMEs, docstrings
150  
151  **Tools**:
152  - `read_file` - Read source code
153  - `write_file` - Create documentation files
154  - `extract_docstrings` - Analyze existing docs
155  - `check_missing_docs` - Find undocumented code
156  - `run_command` - Run doc generators (sphinx, mkdocs)
157  
158  **Example Tasks**:
159  ```
160  @docs Write a comprehensive README for this project
161  @docs Add docstrings to all functions in utils.py
162  @docs Create API documentation
163  Document the authentication flow
164  ```
165  
166  ### general - General-Purpose Agent
167  
168  **Optimized for**: Filesystem operations, shell commands, git, general tasks
169  
170  **Tools**:
171  - `shell` - Execute shell commands
172  - `read_file` - Read any file
173  - `write_file` - Write/modify files
174  - `list_directory` - List files
175  - `append_to_file` - Append to files
176  - `resolve_git_conflicts` - Auto-resolve merge conflicts
177  
178  **Example Tasks**:
179  ```
180  What files are in this directory?
181  Create a new Python file called test.py
182  Run the tests
183  Commit the changes
184  Fix the merge conflict
185  ```
186  
187  ---
188  
189  ## Keyword Auto-Routing
190  
191  The system automatically detects these keywords and routes appropriately:
192  
193  **Routes to @review**:
194  - "review"
195  - "check code"
196  - "analyze code"
197  - "code quality"
198  - "security"
199  
200  **Routes to @docs**:
201  - "document"
202  - "documentation"
203  - "readme"
204  - "docstring"
205  - "write docs"
206  
207  **Everything else**: Routes to general agent
208  
209  ---
210  
211  ## Advanced Usage
212  
213  ### Chaining Tasks
214  
215  You can have different agents work on the same codebase:
216  
217  ```
218  You: @review Check utils.py
219  
220  [Agent analyzes and finds issues]
221  
222  You: Fix the issues you found
223  
224  [General agent fixes the code]
225  
226  You: @docs Add docstrings to the updated file
227  
228  [Docs agent adds documentation]
229  ```
230  
231  ### Work Mode (Self-Improvement)
232  
233  ```bash
234  kamaji work
235  ```
236  
237  In work mode, Kamaji can modify its own code using all agents:
238  
239  ```
240  You: @review Review your own TUI code
241  You: Fix the issues you found
242  You: @docs Document the changes
243  ```
244  
245  ### RAG with Agents
246  
247  Load documents and all agents can query them:
248  
249  ```bash
250  kamaji chat -f design_doc.md architecture.md
251  ```
252  
253  ```
254  You: @review Check if the code matches the design doc
255  You: @docs Write a README based on the architecture doc
256  ```
257  
258  ---
259  
260  ## Current Limitations
261  
262  ### React Format Issue
263  
264  The underlying LLM may struggle with the React agent format, showing:
265  ```
266  ❌ Invalid Format: Missing 'Action:' after 'Thought:'
267  ```
268  
269  **Solutions**:
270  1. **Use a larger model**: `ollama pull llama2:13b`
271  2. **Configure Kamaji**: `kamaji config set model llama2:13b`
272  3. **Try different models**: mistral, mixtral, or GPT-4
273  
274  Larger models (13B+ parameters) follow agent patterns much better.
275  
276  ### Memory Across Agents
277  
278  Each agent has independent memory. If you switch agents, context isn't automatically shared.
279  
280  **Workaround**: Include relevant context in your prompt:
281  ```
282  You: @review Found 3 security issues in auth.py
283  You: Fix the 3 security issues from the review above
284  ```
285  
286  ---
287  
288  ## Adding Your Own Agents
289  
290  See `ARCHITECTURE.md` and `AGENTS_GUIDE.md` for detailed guides on creating custom agents.
291  
292  Quick example:
293  
294  ```python
295  # kamaji/agents/refactoring.py
296  
297  def create_refactoring_agent(llm):
298      tools = [...]  # Define specialized tools
299      prompt = ...   # Create focused prompt
300      return AgentExecutor(...)
301  
302  # Add to router in kamaji/agents/router.py
303  ```
304  
305  ---
306  
307  ## Examples
308  
309  ### Example 1: Complete Code Review
310  
311  ```
312  You: @review Analyze the entire kamaji codebase for issues
313  
314  Kamaji: 🔍 Comprehensive Code Review
315  
316  Analyzing project structure...
317  ✅ Found 18 Python files
318  📊 Total lines: 3,247
319  
320  Issues Found:
321  1. kamaji/tools.py:45 - Missing error handling
322  2. kamaji/agent.py:120 - Type hints missing
323  3. kamaji/commands/chat.py:89 - Unused import
324  
325  Security:
326  ✅ No major security issues
327  ⚠️  execute_shell_command could use input sanitization
328  
329  Recommendations:
330  1. Add comprehensive error handling
331  2. Implement type hints across codebase
332  3. Add unit tests for critical paths
333  
334  Overall Rating: 7.5/10
335  ```
336  
337  ### Example 2: Generate Documentation
338  
339  ```
340  You: @docs Write a comprehensive README for the entire project
341  
342  Kamaji: 📝 Creating README.md...
343  
344  Reading project structure...
345  Analyzing features...
346  Writing documentation...
347  
348  ✅ Created README.md with:
349  
350  # Kamaji - AI CLI Assistant
351  
352  ## Features
353  - Multi-agent system with specialized agents
354  - Code review automation
355  - Documentation generation
356  [... full README content ...]
357  
358  ✅ Successfully wrote 456 lines to README.md
359  ```
360  
361  ### Example 3: Multi-Agent Workflow
362  
363  ```
364  You: @review Check auth.py
365  
366  Kamaji: Found 2 issues:
367  1. Missing input validation on line 34
368  2. Hardcoded secret on line 67
369  
370  You: Fix those 2 issues
371  
372  Kamaji: ✅ Fixed both issues:
373  - Added input validation with regex check
374  - Moved secret to environment variable
375  
376  You: @docs Add docstrings to the updated auth.py
377  
378  Kamaji: ✅ Added comprehensive docstrings:
379  - Module docstring explaining auth system
380  - Function docstrings for all 7 functions
381  - Parameter and return type documentation
382  ```
383  
384  ---
385  
386  ## Summary
387  
388  **To use specialized agents**:
389  - `@review` for code analysis
390  - `@docs` for documentation
391  - `@help` to see all agents
392  - Or just ask naturally!
393  
394  **Auto-routing works great** - the system is smart enough to route most requests correctly based on keywords.
395  
396  **All previous functionality preserved** - general agent handles everything that doesn't match specialized agents.
397  
398  Enjoy your new multi-agent system! 🎉