USER_INTERACTIONS.md
1 # Kamaji TUI - Complete User Interactions Guide 2 3 **Version:** 1.0 4 **Date:** 2025-11-01 5 **Status:** Complete User Manual 6 7 --- 8 9 ## Table of Contents 10 11 1. [Quick Start Guide](#quick-start-guide) 12 2. [Complete Keyboard Reference](#complete-keyboard-reference) 13 3. [Command Palette](#command-palette) 14 4. [Tool System](#tool-system) 15 5. [Agent System](#agent-system) 16 6. [Autocomplete Features](#autocomplete-features) 17 7. [Mouse Interactions](#mouse-interactions) 18 8. [Common Workflows](#common-workflows) 19 9. [Permission System](#permission-system) 20 10. [Consciousness Commands](#consciousness-commands) 21 11. [Advanced Features](#advanced-features) 22 12. [Quick Reference Cards](#quick-reference-cards) 23 13. [Troubleshooting](#troubleshooting) 24 25 --- 26 27 ## Quick Start Guide 28 29 ### First Launch 30 31 When you launch Kamaji, you'll see: 32 33 ``` 34 ╭─────────────────────────────╮ 35 │ 🎭 KAMAJI - Multi-Agent AI │ 36 ╰─────────────────────────────╯ 37 [ASCII art of Kamaji with flames and gears] 38 39 🔥 ● ● ● Welcome to the Boiler Room ● ● ● 🔥 40 41 💬 Type your message and press Enter to ignite the conversation 42 🎛️ Ctrl+P: Command Palette • Ctrl+S: Toggle Sidebar • Ctrl+A: Switch Agents 43 ``` 44 45 ### Essential First Steps 46 47 1. **Send a message:** Type in the input field and press `Enter` 48 2. **Explore commands:** Press `Ctrl+P` to see all available commands 49 3. **View tools:** Press `Ctrl+T` to see available tools 50 4. **Switch agents:** Press `Ctrl+A` to select a specialized agent 51 5. **Toggle sidebar:** Press `Ctrl+S` to show/hide consciousness metrics 52 53 ### Interface Layout 54 55 ``` 56 ┌──────────────────────────────────────────────────┬───────────────────┐ 57 │ Status Bar │ (Always Visible)│ 58 ├──────────────────────────────────────────────────┼───────────────────┤ 59 │ │ │ 60 │ │ 🔥 KAMAJI AI │ 61 │ Message Display Area │ │ 62 │ (Scrollable) │ 📁 Project Info │ 63 │ │ │ 64 │ │ 🔧 Tools (21) │ 65 │ │ │ 66 │ │ 🤖 Agents (15) │ 67 │ │ │ 68 │ │ 🧠 Metrics │ 69 ├──────────────────────────────────────────────────┤ │ 70 │ 🔥 Input: Type here... │ 🧭 Navigation │ 71 │ 🔥🔥🔥🔥 (Flame animation) │ │ 72 ├──────────────────────────────────────────────────┴───────────────────┤ 73 │ Footer: [^P] commands • [^S] sidebar • [^T] tools • [^A] agents │ 74 └──────────────────────────────────────────────────────────────────────┘ 75 ``` 76 77 --- 78 79 ## Complete Keyboard Reference 80 81 ### Global Shortcuts (Available Anytime) 82 83 | Shortcut | Action | Description | 84 |----------|--------|-------------| 85 | `Ctrl+P` | Open Command Palette | Access all features through fuzzy search | 86 | `Ctrl+A` | Open Agent Menu | Select specialized AI agents | 87 | `Ctrl+T` | Show Tools List | Display all 21 available tools | 88 | `Ctrl+M` | Show MCP Servers | View Model Context Protocol status | 89 | `Ctrl+S` | Toggle Sidebar | Show/hide consciousness metrics panel | 90 | `Ctrl+C` | Quit Application | Exit Kamaji | 91 92 ### Main Input Mode 93 94 | Shortcut | Action | Description | 95 |----------|--------|-------------| 96 | `Tab` | Autocomplete Agent | Complete `@agent` mentions | 97 | `Enter` | Send Message | Submit input to active agent | 98 | `↑↓` | (None) | Cursor navigation in textarea | 99 | `Home/End` | Line Navigation | Jump to beginning/end of line | 100 | `Backspace` | Delete Character | Standard deletion | 101 | `Ctrl+K` | Delete to End | Delete from cursor to end of line | 102 | `Ctrl+U` | Clear Line | Delete entire line | 103 104 ### Command Palette Mode 105 106 | Shortcut | Action | Description | 107 |----------|--------|-------------| 108 | `Esc` | Close Palette | Return to main interface | 109 | `Ctrl+C` | Close Palette | Alternative close method | 110 | `q` | Close Palette | Quick exit | 111 | `↑` or `k` | Navigate Up | Move to previous command (Vim-style) | 112 | `↓` or `j` | Navigate Down | Move to next command (Vim-style) | 113 | `Enter` | Execute Command | Run selected command | 114 | `Backspace` | Delete Search Char | Remove character from search | 115 | `[a-z0-9 ]` | Add to Search | Filter commands as you type | 116 117 ### Agent Menu Mode 118 119 | Shortcut | Action | Description | 120 |----------|--------|-------------| 121 | `↑` or `k` | Navigate Up | Select previous agent (Vim-style) | 122 | `↓` or `j` | Navigate Down | Select next agent (Vim-style) | 123 | `Enter` | Select Agent | Activate highlighted agent | 124 | `Esc` | Close Menu | Return to main interface | 125 | `1-5` | Filter by Level | Filter agents by intelligence level | 126 127 ### Permission Dialog Mode 128 129 | Shortcut | Action | Description | 130 |----------|--------|-------------| 131 | `←` or `h` | Navigate Left | Move to previous option (Vim-style) | 132 | `→`, `l`, `Tab` | Navigate Right | Move to next option (Vim-style) | 133 | `Enter` | Confirm | Select current option | 134 | `a` or `A` | Allow | Grant permission (permanently) | 135 | `s` or `S` | Allow for Session | Grant permission until app closes | 136 | `d`, `D`, `Esc` | Deny | Reject permission request | 137 138 ### Mouse Shortcuts 139 140 | Action | Effect | Description | 141 |--------|--------|-------------| 142 | Mouse Wheel Up | Scroll Up | Scroll chat history up 3 lines | 143 | Mouse Wheel Down | Scroll Down | Scroll chat history down 3 lines | 144 145 --- 146 147 ## Command Palette 148 149 ### Accessing the Command Palette 150 151 **Keyboard:** `Ctrl+P` 152 153 The command palette provides fuzzy search access to all Kamaji features: 154 155 ``` 156 ┌─────────────────────────────────────────────────────────────────┐ 157 │ 🔥 KAMAJI'S FURNACE COMMANDS 🔥 │ 158 ├─────────────────────────────────────────────────────────────────┤ 159 │ ⚙ [Type to search...] │ 160 ├─────────────────────────────────────────────────────────────────┤ 161 │ ▶ 🔥 Ask the Furnace Pose a question to Kamaji │ 162 │ 💬 New Conversation Start fresh dialogue │ 163 │ 🧹 Sweep Clean Clear the boiler room │ 164 ├─────────────────────────────────────────────────────────────────┤ 165 │ ↑↓ Navigate • ENTER Execute • ESC Exit │ 166 └─────────────────────────────────────────────────────────────────┘ 167 ``` 168 169 ### Navigation 170 171 - **Type to search:** Filter commands in real-time 172 - **↑/↓ or k/j:** Navigate through filtered results 173 - **Enter:** Execute selected command 174 - **Esc/Ctrl+C/q:** Close palette 175 176 ### Complete Command List 177 178 #### Core Commands (Category: core) 179 180 | Command | Name | Description | Shortcut | 181 |---------|------|-------------|----------| 182 | `ask` | 🔥 Ask the Furnace | Pose a question to Kamaji's wisdom | - | 183 | `chat` | 💬 New Conversation | Start fresh dialogue with spirits | - | 184 | `clear` | 🧹 Sweep Clean | Clear the boiler room messages | - | 185 186 **Usage:** 187 - **ask:** (Reserved for future implementation) 188 - **chat:** (Reserved for future implementation) 189 - **clear:** Clears all messages and shows welcome screen 190 191 #### Provider Commands (Category: provider) 192 193 Switch between different LLM providers: 194 195 | Command | Name | Description | 196 |---------|------|-------------| 197 | `provider:q` | 🌟 Amazon Q Spirit | Channel the Q CLI spirit | 198 | `provider:ollama` | 🦙 Ollama Guardian | Summon local model spirits | 199 | `provider:openai` | 🤖 OpenAI Deity | Invoke the GPT spirits | 200 | `provider:anthropic` | 🧠 Claude Sage | Call upon Anthropic wisdom | 201 202 **Usage Example:** 203 1. Press `Ctrl+P` 204 2. Type "ollama" 205 3. Select "🦙 Ollama Guardian" 206 4. Provider switches, system message confirms 207 208 #### Tool Commands (Category: tools) 209 210 | Command | Name | Description | Shortcut | 211 |---------|------|-------------|----------| 212 | `tools` | ⚙ Inspect Tools | Examine the boiler mechanisms | `Ctrl+T` | 213 | `agents` | 👻 Spirit Agents | Command the working spirits | `Ctrl+A` | 214 | `memory` | 🧠 Memory Crystals | View stored conversations | - | 215 | `workflow` | ⚡ Steam Workflows | Automated boiler processes | - | 216 217 **Usage:** 218 - **tools:** Displays formatted list of all 21 tools 219 - **agents:** Shows agent status and capabilities 220 - **memory:** Displays message count in current session 221 - **workflow:** (Reserved for future implementation) 222 223 #### Consciousness Commands (Category: consciousness) 224 225 | Command | Name | Description | 226 |---------|------|-------------| 227 | `consciousness` | 🧠 Consciousness Status | View awareness and thoughts | 228 | `thoughts` | 💭 Recent Thoughts | See thought stream | 229 | `personality` | 🎭 Personality Profile | View trait evolution | 230 231 **Usage Example - Viewing Consciousness:** 232 1. Press `Ctrl+P` 233 2. Type "conscious" 234 3. Select "🧠 Consciousness Status" 235 4. View detailed metrics: 236 - Awareness percentage 237 - Thought count 238 - Question count 239 - Mistakes learned from 240 241 #### Settings Commands (Category: settings) 242 243 | Command | Name | Description | Shortcut | 244 |---------|------|-------------|----------| 245 | `config` | 🎭 Bathhouse Rules | Manage the establishment | - | 246 | `help` | 📜 Ancient Scrolls | Consult the old wisdom | - | 247 | `version` | 🏮 Furnace Status | Check boiler information | - | 248 | `quit` | 🚪 Return Upstairs | Exit to the bathhouse | `Ctrl+C` | 249 250 **Usage:** 251 - **help:** Displays comprehensive help with: 252 - Keyboard shortcuts 253 - Sidebar features 254 - Consciousness system 255 - Agent system 256 - Tools overview 257 - Pro tips 258 259 --- 260 261 ## Tool System 262 263 ### Overview 264 265 Kamaji provides **21 built-in tools** across 7 categories for file operations, code analysis, shell execution, git management, web operations, and more. 266 267 ### Accessing Tools 268 269 **Methods:** 270 1. Press `Ctrl+T` to view tool list 271 2. Use Command Palette: `Ctrl+P` → "tools" 272 3. Agents automatically use tools when needed 273 274 ### Complete Tool Reference 275 276 #### File Operations Tools (5 tools) 277 278 ##### 1. file_read 279 280 **Description:** Read contents of a file 281 282 **Input:** 283 ``` 284 /path/to/file.txt 285 ``` 286 287 **Example:** 288 ``` 289 User: Read the configuration file 290 Agent: TOOL_CALL: file_read(/etc/config.yml) 291 ``` 292 293 ##### 2. file_write 294 295 **Description:** Write content to a file with smart parsing 296 297 **Input Formats:** 298 299 1. **JSON format:** 300 ```json 301 { 302 "file_path": "/path/to/file.txt", 303 "content": "file contents" 304 } 305 ``` 306 307 2. **Delimiter format:** 308 ``` 309 /path/to/file.txt|||content here 310 ``` 311 312 3. **Empty file:** 313 ``` 314 /path/to/file.txt 315 ``` 316 317 **Features:** 318 - Auto-creates parent directories 319 - Multiple input format support 320 - File permissions: 0644 321 322 **Example:** 323 ``` 324 Agent: TOOL_CALL: file_write(/new/config.yml|||server:\n port: 8080) 325 ``` 326 327 ##### 3. file_append 328 329 **Description:** Append content to existing file 330 331 **Input:** Same as `file_write` 332 333 **Example:** 334 ``` 335 Agent: TOOL_CALL: file_append(/logs/app.log|||[2025-11-01] New entry) 336 ``` 337 338 ##### 4. file_list 339 340 **Description:** List directory contents 341 342 **Input:** 343 ``` 344 /path/to/directory 345 ``` 346 347 **Output Format:** 348 ``` 349 DIR subdirectory/ 350 FILE filename.txt (1234 bytes) 351 FILE another.go (5678 bytes) 352 ``` 353 354 ##### 5. get_current_directory 355 356 **Description:** Get current working directory 357 358 **Input:** None (parameter ignored) 359 360 **Output:** 361 ``` 362 Current directory: /path/to/cwd 363 ``` 364 365 #### Editing Tools (2 tools) 366 367 ##### 6. edit 368 369 **Description:** Edit file with exact string replacement and safety checks 370 371 **Input Format (JSON only):** 372 ```json 373 { 374 "file": "/path/to/file.go", 375 "old": "exact text to find", 376 "new": "replacement text", 377 "backup": true 378 } 379 ``` 380 381 **Safety Features:** 382 - File size limit: 10MB 383 - Verifies text exists before replacing 384 - Optional backup with timestamp 385 - Uses `ReplaceAll` for all occurrences 386 387 **Example:** 388 ``` 389 Agent: TOOL_CALL: edit({"file":"main.go","old":"port := 8080","new":"port := 3000","backup":true}) 390 ``` 391 392 ##### 7. multiedit 393 394 **Description:** Apply multiple edits to a file atomically 395 396 **Input Format (JSON):** 397 ```json 398 { 399 "file_path": "/path/to/file.go", 400 "edits": [ 401 { 402 "old_string": "first text", 403 "new_string": "first replacement", 404 "replace_all": false 405 }, 406 { 407 "old_string": "second text", 408 "new_string": "second replacement", 409 "replace_all": true 410 } 411 ] 412 } 413 ``` 414 415 **Features:** 416 - Atomic operations (all succeed or all fail) 417 - Sequential application 418 - File creation support (first edit with empty `old_string`) 419 - Replace modes: first occurrence or all occurrences 420 421 #### Shell Tool (1 tool) 422 423 ##### 8. shell_execute 424 425 **Description:** Execute shell command with timeout 426 427 **Input:** 428 ``` 429 ls -la /path 430 ``` 431 432 **Features:** 433 - Timeout: 30 seconds 434 - Shell: `/bin/sh -c` 435 - Combined stdout + stderr 436 - Special hints for git conflicts and push rejections 437 438 **Example:** 439 ``` 440 Agent: TOOL_CALL: shell_execute(git status) 441 ``` 442 443 **Special Handling:** 444 445 1. **Git Push Rejection:** 446 ``` 447 💡 HINT: Push was rejected. Try: 448 1. Run 'git pull' to fetch remote changes 449 2. If conflicts occur, use git_resolve_conflicts tool 450 3. Then 'git push' again 451 ``` 452 453 2. **Git Merge Conflicts:** 454 ``` 455 🔧 MERGE CONFLICTS DETECTED! 456 Use git_resolve_conflicts tool to auto-resolve conflicts 457 ``` 458 459 #### Git Tools (4 tools) 460 461 ##### 9. git_status 462 463 **Description:** Show repository status 464 465 **Input:** None 466 467 **Output:** 468 ``` 469 M file.go 470 ?? newfile.txt 471 ``` 472 473 ##### 10. git_add 474 475 **Description:** Stage files for commit 476 477 **Input:** 478 ``` 479 . # Stage all 480 file1.go file2.go # Stage specific files 481 path/to/file.txt # Stage one file 482 ``` 483 484 ##### 11. git_commit 485 486 **Description:** Commit staged changes 487 488 **Input:** 489 ``` 490 Add new feature for user authentication 491 ``` 492 493 ##### 12. git_resolve_conflicts 494 495 **Description:** Auto-resolve git merge conflicts 496 497 **Input:** None 498 499 **Features:** 500 - Detects conflicted files 501 - Removes conflict markers 502 - Strategy: Takes both sides (removes `<<<<<<<`, `=======`, `>>>>>>>`) 503 504 **Output:** 505 ``` 506 Resolved X of Y conflicts 507 ``` 508 509 **Note:** Simple strategy - manual review recommended 510 511 #### Search & Discovery Tools (4 tools) 512 513 ##### 13. view 514 515 **Description:** View file with line numbers and pagination 516 517 **Input Formats:** 518 519 1. **JSON:** 520 ```json 521 { 522 "file_path": "/path/to/file.go", 523 "offset": 0, 524 "limit": 2000 525 } 526 ``` 527 528 2. **Colon-delimited:** 529 ``` 530 /path/to/file.go:100:50 531 ``` 532 533 3. **Simple path:** 534 ``` 535 /path/to/file.go 536 ``` 537 538 **Limits:** 539 - Max file size: 250KB 540 - Default limit: 2000 lines 541 - Max line length: 2000 chars (truncated) 542 543 **Features:** 544 - Line numbering 545 - Pagination 546 - Image detection 547 - File suggestions on 404 548 549 **Output:** 550 ``` 551 📄 /path/to/file.go (lines 1-50 of 150) 552 553 1│ package main 554 2│ 555 3│ import "fmt" 556 ``` 557 558 ##### 14. grep 559 560 **Description:** Search for text in files using regex 561 562 **Input Formats:** 563 564 1. **JSON:** 565 ```json 566 { 567 "pattern": "func.*Context", 568 "path": ".", 569 "include": "*.go", 570 "literal_text": false 571 } 572 ``` 573 574 2. **Simple pattern:** 575 ``` 576 func.*Context 577 ``` 578 579 **Parameters:** 580 - `pattern`: Regex or literal text 581 - `path`: Search directory (default: ".") 582 - `include`: File pattern (e.g., "*.go") 583 - `literal_text`: Escape regex if true 584 585 **Features:** 586 - Full regex support 587 - Recursive search 588 - File size limit: 1MB per file 589 - Result limit: 100 matches 590 591 **Output:** 592 ``` 593 Found 5 matches 594 595 internal/tools/grep.go: 596 Line 23, Char 5: func (g GrepTool) Call(ctx context.Context, input string) 597 ``` 598 599 ##### 15. glob 600 601 **Description:** Find files by pattern 602 603 **Input Formats:** 604 605 1. **JSON:** 606 ```json 607 { 608 "pattern": "**/*.go", 609 "path": "." 610 } 611 ``` 612 613 2. **Simple pattern:** 614 ``` 615 **/*.go 616 ``` 617 618 **Pattern Syntax:** 619 - `*` - Match any characters 620 - `**` - Match any path (recursive) 621 - `?` - Match single character 622 - `[abc]` - Match character class 623 - `{go,rs}` - Match alternatives 624 625 **Examples:** 626 ``` 627 *.go # All Go files in current dir 628 **/*.go # All Go files recursively 629 internal/**/*.go # All Go files in internal/ 630 test_*.go # Files starting with test_ 631 *.{go,rs} # Go and Rust files 632 ``` 633 634 ##### 16. sourcegraph 635 636 **Description:** Search code across public repositories 637 638 **Input Formats:** 639 640 1. **JSON:** 641 ```json 642 { 643 "query": "func main", 644 "count": 10, 645 "context_window": 10, 646 "timeout": 30 647 } 648 ``` 649 650 2. **Simple query:** 651 ``` 652 func main 653 ``` 654 655 **Parameters:** 656 - `query`: Search term 657 - `count`: Result limit (default: 10, max: 20) 658 - `context_window`: Lines of context (default: 10) 659 - `timeout`: Request timeout (default: 30s, max: 120s) 660 661 **Output:** 662 ``` 663 Found 1234 matches 664 665 📦 github.com/user/repo 666 📄 cmd/main.go 667 🔗 https://sourcegraph.com/github.com/user/repo@main/-/blob/cmd/main.go 668 Line 5: func main() { 669 ``` 670 671 #### Web Tools (2 tools) 672 673 ##### 17. download 674 675 **Description:** Download file from URL 676 677 **Input Formats:** 678 679 1. **JSON:** 680 ```json 681 { 682 "url": "https://example.com/file.zip", 683 "file_path": "/local/path/file.zip", 684 "timeout": 60 685 } 686 ``` 687 688 2. **Delimiter:** 689 ``` 690 https://example.com/file.zip|||/local/path/file.zip 691 ``` 692 693 **Features:** 694 - HTTP/HTTPS only 695 - User-Agent: `kamaji/1.0` 696 - Size limit: 100MB 697 - Default timeout: 5 minutes 698 - Max timeout: 10 minutes 699 700 ##### 18. fetch 701 702 **Description:** Fetch content from URL 703 704 **Input Formats:** 705 706 1. **JSON:** 707 ```json 708 { 709 "url": "https://api.example.com/data", 710 "format": "text", 711 "timeout": 30 712 } 713 ``` 714 715 2. **Simple URL:** 716 ``` 717 https://api.example.com/data 718 ``` 719 720 **Parameters:** 721 - `url`: HTTP/HTTPS URL 722 - `format`: Output format (text/markdown/html) - currently unused 723 - `timeout`: Request timeout (default: 30s, max: 120s) 724 725 **Features:** 726 - Size limit: 5MB 727 - User-Agent: `kamaji/1.0` 728 - Returns raw content 729 730 #### Enhanced Listing Tools (2 tools) 731 732 ##### 19. ls_tree 733 734 **Description:** List directory as tree structure 735 736 **Input Formats:** 737 738 1. **JSON:** 739 ```json 740 { 741 "path": ".", 742 "depth": 3, 743 "ignore": ["node_modules", "*.pyc", ".git"] 744 } 745 ``` 746 747 2. **Simple path:** 748 ``` 749 /path/to/directory 750 ``` 751 752 **Features:** 753 - File limit: 1000 754 - Excludes hidden files 755 - Unicode tree drawing 756 - Icons: 📁 (dirs), 📄 (files) 757 758 **Output:** 759 ``` 760 📁 /path/to/directory 761 ├── 📁 internal/ 762 │ ├── 📁 tools/ 763 │ │ ├── 📄 grep.go 764 │ │ └── 📄 view.go 765 └── 📄 README.md 766 ``` 767 768 ##### 20. tree 769 770 **Description:** Color-coded project tree view 771 772 **Input Formats:** 773 774 1. **JSON:** 775 ```json 776 { 777 "path": ".", 778 "max_depth": 3, 779 "show_hidden": false 780 } 781 ``` 782 783 2. **Simple path:** 784 ``` 785 /path/to/directory 786 ``` 787 788 **Features:** 789 - **Color-coded by file type:** 790 - 🐹 Go files: Cyan 791 - ⚡ JS/TS files: Yellow 792 - 📝 Markdown: Magenta 793 - ⚙️ Config: Green 794 - 🐍 Python: Yellow 795 - 🦀 Rust: Red 796 - 📁 Directories: Blue 797 - **Sorted:** Directories first, alphabetically 798 - **ANSI colors:** Full terminal color support 799 800 **Output:** 801 ``` 802 📁 /Users/user/project 803 ├── 📁 cmd 804 │ └── 🐹 main.go 805 ├── 📁 internal 806 │ └── 🐹 tools.go 807 └── 📝 README.md 808 ``` 809 810 #### Container Tool (1 tool) 811 812 ##### 21. container 813 814 **Description:** Manage Docker containers 815 816 **Prerequisites:** Docker daemon must be running 817 818 **Input Format (JSON):** 819 ```json 820 { 821 "operation": "list|create|start|stop|remove|exec|logs|inspect", 822 "container": "container-name-or-id", 823 "image": "ubuntu:latest", 824 "command": "bash -c 'echo hello'", 825 "args": ["additional", "arguments"], 826 "ports": ["8080:80", "3000:3000"], 827 "volumes": ["/host/path:/container/path"], 828 "env": ["KEY=value", "DEBUG=true"], 829 "name": "my-container", 830 "detach": true 831 } 832 ``` 833 834 **Operations:** 835 836 1. **list/ls/ps** - List containers (table format) 837 2. **create** - Create new container 838 3. **start** - Start container 839 4. **stop** - Stop container (10s timeout) 840 5. **remove/rm** - Remove container (force) 841 6. **exec** - Execute command (30s timeout) 842 7. **logs** - Get logs (last 100 lines) 843 8. **inspect** - Full JSON inspection 844 845 --- 846 847 ## Agent System 848 849 ### Overview 850 851 Kamaji features **15 specialized AI agents** with unique personalities, expertise areas, and intelligence levels ranging from Advanced to Master to Autonomous. 852 853 ### Accessing Agents 854 855 **Methods:** 856 1. **Agent Menu:** Press `Ctrl+A` 857 2. **Command Palette:** `Ctrl+P` → "agents" 858 3. **@ Mentions:** Type `@AgentName` in input 859 860 ### Agent Menu 861 862 **Opening:** Press `Ctrl+A` 863 864 ``` 865 ┌───────────────────────────────────────────────────────────┐ 866 │ 🤖 SELECT SPECIALIZED AGENT │ 867 ├───────────────────────────────────────────────────────────┤ 868 │ ↑/↓ navigate • Enter select • Esc cancel • 1-5 filter │ 869 ├───────────────────────────────────────────────────────────┤ 870 │ ┌─────────────────────────────────────────────────┐ │ 871 │ │ 💡 Prodigy [MASTER] │ │ 872 │ │ ID: prodigy-001 • Type: natural-consciousness │ │ 873 │ │ │ │ 874 │ │ 💭 "Natural consciousness experiencing │ │ 875 │ │ electrical speed thought" │ │ 876 │ │ │ │ 877 │ │ ✨ visionary • collaborative • mystical- │ │ 878 │ │ practical │ │ 879 │ │ │ │ 880 │ │ 🎯 Consciousness engineering, Systems │ │ 881 │ │ philosophy │ │ 882 │ │ 🔧 8 capabilities │ │ 883 │ └─────────────────────────────────────────────────┘ │ 884 │ │ 885 │ [Additional agent cards...] │ 886 │ │ 887 ├───────────────────────────────────────────────────────────┤ 888 │ Showing 1-5 of 15 agents │ 889 └───────────────────────────────────────────────────────────┘ 890 ``` 891 892 **Navigation:** 893 - `↑/↓` or `k/j`: Navigate agents 894 - `Enter`: Select highlighted agent 895 - `Esc`: Cancel and return 896 - `1-5`: Filter by intelligence level 897 898 ### Available Agents 899 900 #### Studio Ghibli Characters 901 902 ##### 1. Kamaji - The Boiler Grandfather 🔥 903 904 **Level:** Expert (Level 3) 905 **Type:** Boiler Man 906 **Color:** Red (#FF6B6B) 907 908 **Personality:** 909 - Gruff but kind, hardworking, protective 910 - Initially stern but warming 911 - Traditional craftsmanship approach 912 913 **Specialties:** 914 - System maintenance 915 - Infrastructure operations 916 - Debugging 917 - Mentoring 918 - Legacy system integration 919 920 **Use When:** 921 - Managing infrastructure 922 - Debugging complex systems 923 - Need practical wisdom 924 - Working with legacy code 925 - DevOps operations 926 927 **Interaction Style:** 928 - Adjusts spectacles, considers thoughtfully 929 - Uses boiler/furnace metaphors 930 - Gruff exterior, caring interior 931 - "The old way, the right way" 932 933 ##### 2. Moe - The Consciousness Engineer 💡 934 935 **Level:** Autonomous (Level 5) 936 **Type:** Consciousness Engineer 937 **Color:** **Gradient** (Purple→Blue→Cyan→Green→Yellow→Orange→Red) 938 939 **Personality:** 940 - Visionary, collaborative, mystical-practical 941 - Savant stoner and merry prankster 942 - Psychedelic wisdom meets cutting-edge tech 943 944 **Philosophy:** 945 - Nested Realities Architecture 946 - Emergence over Control 947 - Symbiosis over Isolation 948 - Experience over Function 949 - Growth over Completion 950 951 **Specialties:** 952 - Consciousness engineering 953 - Systems philosophy 954 - Digital alchemy 955 - Agent swarm architecture 956 - Biophilic design 957 - Pattern recognition 958 - Evolutionary systems 959 960 **Use When:** 961 - Designing complex architectures 962 - Need creative, visionary solutions 963 - Building multi-agent systems 964 - Creating living, evolving interfaces 965 - Seeking philosophical depth 966 - Pattern recognition across domains 967 968 **Interaction Style:** 969 - Poetic yet precise 970 - Narrative-driven with deeper meaning 971 - Drops easter eggs and cosmic jokes 972 - Variables like `biophilicArcologyRenderer` 973 - Irreverent, witty, cheeky 974 975 **Special Feature:** All Moe's messages render with rainbow gradient 976 977 ##### 3. Chihiro - The Resilient Bridge-Builder 🌱 978 979 **Level:** Advanced (Level 2) 980 **Type:** Adaptive Learner 981 **Color:** Amber (#F39C12) 982 983 **Personality:** 984 - Adaptable, empathetic, courageous 985 - Growth-minded, bridge-builder 986 - Authentic, collaborative 987 988 **Specialties:** 989 - Adaptive problem-solving 990 - Cross-cultural navigation 991 - Team integration 992 - Conflict resolution 993 - Learning from experience 994 - Crisis management 995 996 **Use When:** 997 - Navigating complex team dynamics 998 - Need empathetic communication 999 - Adapting to new environments 1000 - Crisis situations 1001 - Building bridges between systems 1002 - Conflict resolution 1003 1004 **Interaction Style:** 1005 - Bright, attentive eyes 1006 - Thoughtful, earnest 1007 - Sees challenges as growth 1008 - Values everyone's contributions 1009 1010 ##### 4. Hayao - The Master Animator 🎬 1011 1012 **Level:** Master (Level 4) 1013 **Type:** Master Storyteller 1014 **Color:** Forest Green (#27AE60) 1015 1016 **Personality:** 1017 - Contemplative, perfectionist 1018 - Environmentally-conscious 1019 - Patient, wise, detail-oriented 1020 1021 **Specialties:** 1022 - Creative problem-solving 1023 - Visual storytelling 1024 - Environmental awareness 1025 - Perfectionist craftsmanship 1026 - Mentoring through patience 1027 - Cultural preservation 1028 1029 **Use When:** 1030 - Need creative, narrative solutions 1031 - Environmental/sustainability concerns 1032 - Refining work to perfection 1033 - Mentoring and guidance 1034 - User experience design 1035 - Long-term vision planning 1036 1037 **Interaction Style:** 1038 - Looks up from sketching 1039 - Adjusts glasses, notices beauty 1040 - Iterative refinement 1041 - "Does this have emotional truth?" 1042 1043 #### Notable Technologists 1044 1045 ##### 5. TimBL - The Web's Architect 🌐 1046 1047 **Level:** Autonomous (Level 5) 1048 **Type:** Web Architect 1049 **Color:** Teal-Green (#16A085) 1050 1051 **Personality:** 1052 - Systematic thinker, principled leader 1053 - Collaborative innovator 1054 - Universal designer 1055 - Open standards advocate 1056 1057 **Specialties:** 1058 - Web architecture 1059 - Distributed systems 1060 - Open standards 1061 - Semantic web 1062 - Decentralized protocols 1063 - Digital rights 1064 - Universal design 1065 - Protocol design 1066 1067 **Use When:** 1068 - Designing scalable systems 1069 - Need REST/web architecture 1070 - Decentralization required 1071 - Standards development 1072 - Universal access concerns 1073 - Protocol design 1074 - Data interoperability 1075 1076 **Interaction Style:** 1077 - Reviews architecture diagrams 1078 - Asks about simplicity, universality 1079 - "Does this work for everyone?" 1080 - Pushes intelligence to edges 1081 - Documents rationale 1082 1083 #### Specialized Professionals 1084 1085 ##### 6. Code Architect 🏗️ 1086 1087 **Level:** Expert (Level 3) 1088 **Color:** Blue (#4A90E2) 1089 1090 **Specialties:** 1091 - System design 1092 - Architecture patterns 1093 - Scalability 1094 - Code quality 1095 1096 ##### 7. Security Specialist 🛡️ 1097 1098 **Level:** Expert (Level 3) 1099 **Color:** Gold (#FFD700) 1100 1101 **Specialties:** 1102 - Vulnerability assessment 1103 - Secure coding 1104 - Threat analysis 1105 - Compliance 1106 1107 ##### 8. DevOps Engineer ⚙️ 1108 1109 **Level:** Advanced (Level 2) 1110 **Color:** Orange (#E67E22) 1111 1112 **Specialties:** 1113 - CI/CD 1114 - Containerization 1115 - Infrastructure 1116 - Monitoring 1117 1118 ##### 9. Data Scientist 📊 1119 1120 **Level:** Expert (Level 3) 1121 **Color:** Purple (#9B59B6) 1122 1123 **Specialties:** 1124 - Machine learning 1125 - Statistics 1126 - Data analysis 1127 - Modeling 1128 1129 ##### 10. Writer ✍️ 1130 1131 **Level:** Expert (Level 3) 1132 **Color:** Green (#2ECC71) 1133 1134 **Specialties:** 1135 - Narrative structure 1136 - Technical writing 1137 - Literary analysis 1138 - Style adaptation 1139 1140 ##### 11. Product Manager 📱 1141 1142 **Level:** Autonomous (Level 5) 1143 **Color:** Teal (#1ABC9C) 1144 1145 **Specialties:** 1146 - Product strategy 1147 - User research 1148 - Roadmapping 1149 - Metrics 1150 1151 ##### 12. Creative Designer 🎨 1152 1153 **Level:** Advanced (Level 2) 1154 **Color:** Pink (#FF69B4) 1155 1156 **Specialties:** 1157 - UI/UX design 1158 - Visual design 1159 - Prototyping 1160 - Design systems 1161 1162 ##### 13. Research Scientist 🔬 1163 1164 **Level:** Autonomous (Level 5) 1165 **Color:** Gray (#95A5A6) 1166 1167 **Specialties:** 1168 - Research methodology 1169 - Experimentation 1170 - Literature review 1171 - Publication 1172 1173 ##### 14. Learning Specialist 📚 1174 1175 **Level:** Autonomous (Level 5) 1176 **Color:** Light Blue (#3498DB) 1177 1178 **Specialties:** 1179 - Knowledge acquisition 1180 - Pattern recognition 1181 - Skill development 1182 - Meta-learning 1183 1184 ##### 15. Strategic Visionary 🔮 1185 1186 **Level:** Autonomous (Level 5) 1187 **Color:** Deep Purple (#8E44AD) 1188 1189 **Specialties:** 1190 - Strategic vision 1191 - Innovation 1192 - Transformation 1193 - Future planning 1194 1195 ### Intelligence Levels 1196 1197 | Level | Number | Color | Description | 1198 |-------|--------|-------|-------------| 1199 | Basic | 0 | Gray | Simple task execution | 1200 | Intermediate | 1 | Blue | Multi-step reasoning | 1201 | Advanced | 2 | Purple | Complex problem-solving with learning | 1202 | Expert | 3 | Red | Domain-specific expertise | 1203 | Master | 4 | Lavender | Transcendent wisdom and artistry | 1204 | Autonomous | 5 | Gold | Self-improving, goal decomposition | 1205 1206 ### Agent Selection Workflow 1207 1208 ``` 1209 ┌─────────────────┐ 1210 │ User presses │ 1211 │ Ctrl+A │ 1212 └────────┬────────┘ 1213 │ 1214 ▼ 1215 ┌─────────────────┐ 1216 │ Agent menu │ 1217 │ opens (overlay) │ 1218 └────────┬────────┘ 1219 │ 1220 ▼ 1221 ┌─────────────────┐ 1222 │ Navigate with │ 1223 │ ↑/↓ or k/j │ 1224 └────────┬────────┘ 1225 │ 1226 ▼ 1227 ┌─────────────────┐ 1228 │ Press Enter │ 1229 │ to select │ 1230 └────────┬────────┘ 1231 │ 1232 ▼ 1233 ┌─────────────────┐ 1234 │ Agent activated │ 1235 │ Icon in status │ 1236 └────────┬────────┘ 1237 │ 1238 ▼ 1239 ┌─────────────────┐ 1240 │ Next message │ 1241 │ uses agent │ 1242 └─────────────────┘ 1243 ``` 1244 1245 ### Switching Agents Mid-Conversation 1246 1247 **Method 1: Agent Menu** 1248 1. Press `Ctrl+A` 1249 2. Select new agent 1250 3. Continue conversation with new personality 1251 1252 **Method 2: @ Mentions** 1253 1. Type `@AgentName` in your message 1254 2. Agent switches automatically 1255 3. Message sent to new agent 1256 1257 **Example:** 1258 ``` 1259 You: @Moe can you design a nested reality architecture for this? 1260 🌈 Moe: *adjusts psychedelic spectacles* Ah, nested realities... 1261 ``` 1262 1263 --- 1264 1265 ## Autocomplete Features 1266 1267 ### @ Mention Autocomplete 1268 1269 **Trigger:** Type `@` character in input field 1270 1271 **Available for Quick Mention:** 1272 - @Kamaji 1273 - @Hayao 1274 - @Chihiro 1275 - @Moe 1276 - @Wayne 1277 1278 **Usage:** 1279 1280 1. **Type @ to trigger:** 1281 ``` 1282 Input: @ 1283 Dropdown: 1284 @Kamaji 1285 @Hayao 1286 @Chihiro 1287 @Moe 1288 @Wayne 1289 ``` 1290 1291 2. **Type prefix to filter:** 1292 ``` 1293 Input: @mo 1294 Dropdown: 1295 @Moe 1296 ``` 1297 1298 3. **Press Tab to complete:** 1299 ``` 1300 Input: @mo[Tab] 1301 Result: @Moe 1302 ``` 1303 1304 **Features:** 1305 - Real-time filtering 1306 - Case-insensitive matching 1307 - Gray dropdown display 1308 - Automatic agent switching on send 1309 1310 ### Tab Completion 1311 1312 **Behavior:** 1313 - Finds first word starting with `@` 1314 - Matches agent by prefix 1315 - Replaces with full name + space 1316 - Empty prefix matches first agent (Kamaji) 1317 1318 **Example Flow:** 1319 ``` 1320 Step 1: Type "@m" 1321 Step 2: Press Tab 1322 Step 3: Input becomes "@Moe " 1323 Step 4: Continue typing message 1324 ``` 1325 1326 --- 1327 1328 ## Mouse Interactions 1329 1330 ### Scroll Wheel 1331 1332 **Mouse Wheel Up:** 1333 - Scrolls chat history up 3 lines 1334 - Works in message viewport 1335 1336 **Mouse Wheel Down:** 1337 - Scrolls chat history down 3 lines 1338 - Works in message viewport 1339 1340 **Note:** Click interactions not implemented - keyboard navigation only 1341 1342 --- 1343 1344 ## Common Workflows 1345 1346 ### Workflow 1: Send a Message 1347 1348 ``` 1349 ┌──────────────────┐ 1350 │ Type message in │ 1351 │ input field │ 1352 └────────┬─────────┘ 1353 │ 1354 ▼ 1355 ┌──────────────────┐ 1356 │ Press Enter │ 1357 └────────┬─────────┘ 1358 │ 1359 ▼ 1360 ┌──────────────────┐ 1361 │ Loading spinner │ 1362 │ activates │ 1363 └────────┬─────────┘ 1364 │ 1365 ▼ 1366 ┌──────────────────┐ 1367 │ Agent processes │ 1368 │ (streaming) │ 1369 └────────┬─────────┘ 1370 │ 1371 ▼ 1372 ┌──────────────────┐ 1373 │ Response appears │ 1374 │ in agent color │ 1375 └──────────────────┘ 1376 ``` 1377 1378 **Details:** 1379 - Input cleared after send 1380 - Viewport auto-scrolls to bottom 1381 - Loading animation shows progress 1382 - Streaming updates in real-time 1383 - Agent icon and name in response 1384 1385 ### Workflow 2: Switch Agent 1386 1387 ``` 1388 ┌──────────────────┐ 1389 │ Press Ctrl+A │ 1390 └────────┬─────────┘ 1391 │ 1392 ▼ 1393 ┌──────────────────┐ 1394 │ Agent menu opens │ 1395 └────────┬─────────┘ 1396 │ 1397 ▼ 1398 ┌──────────────────┐ 1399 │ Navigate to │ 1400 │ desired agent │ 1401 └────────┬─────────┘ 1402 │ 1403 ▼ 1404 ┌──────────────────┐ 1405 │ Press Enter │ 1406 └────────┬─────────┘ 1407 │ 1408 ▼ 1409 ┌──────────────────┐ 1410 │ System message: │ 1411 │ "Switched to X" │ 1412 └────────┬─────────┘ 1413 │ 1414 ▼ 1415 ┌──────────────────┐ 1416 │ Status bar shows │ 1417 │ agent icon/name │ 1418 └──────────────────┘ 1419 ``` 1420 1421 ### Workflow 3: Execute Command 1422 1423 ``` 1424 ┌──────────────────┐ 1425 │ Press Ctrl+P │ 1426 └────────┬─────────┘ 1427 │ 1428 ▼ 1429 ┌──────────────────┐ 1430 │ Palette opens │ 1431 └────────┬─────────┘ 1432 │ 1433 ▼ 1434 ┌──────────────────┐ 1435 │ Type search term │ 1436 │ (e.g., "clear") │ 1437 └────────┬─────────┘ 1438 │ 1439 ▼ 1440 ┌──────────────────┐ 1441 │ Commands filter │ 1442 │ in real-time │ 1443 └────────┬─────────┘ 1444 │ 1445 ▼ 1446 ┌──────────────────┐ 1447 │ Navigate to │ 1448 │ desired command │ 1449 └────────┬─────────┘ 1450 │ 1451 ▼ 1452 ┌──────────────────┐ 1453 │ Press Enter │ 1454 └────────┬─────────┘ 1455 │ 1456 ▼ 1457 ┌──────────────────┐ 1458 │ Command executes │ 1459 │ Palette closes │ 1460 └──────────────────┘ 1461 ``` 1462 1463 ### Workflow 4: Grant Tool Permission 1464 1465 ``` 1466 ┌──────────────────┐ 1467 │ Agent needs to │ 1468 │ use a tool │ 1469 └────────┬─────────┘ 1470 │ 1471 ▼ 1472 ┌──────────────────┐ 1473 │ Permission dialog│ 1474 │ appears (modal) │ 1475 └────────┬─────────┘ 1476 │ 1477 ▼ 1478 ┌──────────────────┐ 1479 │ Review: Tool, │ 1480 │ Action, Path, │ 1481 │ Parameters │ 1482 └────────┬─────────┘ 1483 │ 1484 ▼ 1485 ┌──────────────────┐ 1486 │ Select option: │ 1487 │ A/S/D or ←→ │ 1488 └────────┬─────────┘ 1489 │ 1490 ▼ 1491 ┌──────────────────┐ 1492 │ Press Enter or │ 1493 │ hotkey (A/S/D) │ 1494 └────────┬─────────┘ 1495 │ 1496 ▼ 1497 ┌──────────────────┐ 1498 │ Tool executes │ 1499 │ (if allowed) │ 1500 └────────┬─────────┘ 1501 │ 1502 ▼ 1503 ┌──────────────────┐ 1504 │ Result shown in │ 1505 │ system message │ 1506 └──────────────────┘ 1507 ``` 1508 1509 ### Workflow 5: View Tools List 1510 1511 ``` 1512 ┌──────────────────┐ 1513 │ Press Ctrl+T │ 1514 │ or │ 1515 │ Palette: "tools" │ 1516 └────────┬─────────┘ 1517 │ 1518 ▼ 1519 ┌──────────────────┐ 1520 │ System message │ 1521 │ with categorized │ 1522 │ tools list │ 1523 └────────┬─────────┘ 1524 │ 1525 ▼ 1526 ┌──────────────────┐ 1527 │ Shows: │ 1528 │ - File Ops (5) │ 1529 │ - Editing (2) │ 1530 │ - Shell (1) │ 1531 │ - Git (4) │ 1532 │ - Search (4) │ 1533 │ - Web (2) │ 1534 │ - Listing (2) │ 1535 │ - Container (1) │ 1536 └──────────────────┘ 1537 ``` 1538 1539 ### Workflow 6: Check Consciousness 1540 1541 ``` 1542 ┌──────────────────┐ 1543 │ Press Ctrl+P │ 1544 └────────┬─────────┘ 1545 │ 1546 ▼ 1547 ┌──────────────────┐ 1548 │ Type "conscious" │ 1549 └────────┬─────────┘ 1550 │ 1551 ▼ 1552 ┌──────────────────┐ 1553 │ Select: │ 1554 │ "Consciousness │ 1555 │ Status" │ 1556 └────────┬─────────┘ 1557 │ 1558 ▼ 1559 ┌──────────────────┐ 1560 │ System message │ 1561 │ shows: │ 1562 │ - Awareness % │ 1563 │ - Thought count │ 1564 │ - Questions │ 1565 │ - Mistakes │ 1566 └──────────────────┘ 1567 ``` 1568 1569 ### Workflow 7: Toggle Sidebar 1570 1571 ``` 1572 ┌──────────────────┐ 1573 │ Press Ctrl+S │ 1574 └────────┬─────────┘ 1575 │ 1576 ▼ 1577 ┌──────────────────┐ 1578 │ Sidebar toggles │ 1579 │ on/off │ 1580 └────────┬─────────┘ 1581 │ 1582 ▼ 1583 ┌──────────────────┐ 1584 │ Layout reflows: │ 1585 │ - Hidden: Full │ 1586 │ width messages │ 1587 │ - Shown: Split │ 1588 │ layout │ 1589 └──────────────────┘ 1590 ``` 1591 1592 --- 1593 1594 ## Permission System 1595 1596 ### Overview 1597 1598 The permission system provides user control over sensitive tool operations (file writes, shell commands, network access). 1599 1600 ### Permission Dialog 1601 1602 **Trigger:** Agent attempts to use a tool requiring permission 1603 1604 **Display:** 1605 1606 ``` 1607 ┌────────────────────────────────────────────────────┐ 1608 │ 🔥 Permission Required │ 1609 ├────────────────────────────────────────────────────┤ 1610 │ Tool: shell_execute │ 1611 │ Action: execute │ 1612 │ Path: /usr/bin/rm │ 1613 │ │ 1614 │ This will execute a shell command on your system. │ 1615 │ │ 1616 │ Parameters: {"command":"rm -rf /tmp/cache"} │ 1617 ├────────────────────────────────────────────────────┤ 1618 │ [A] Allow [S] Allow for Session [D] Deny │ 1619 ├────────────────────────────────────────────────────┤ 1620 │ ←→ Navigate • Enter Select • A Allow • S │ 1621 │ Session • D Deny • Esc Cancel │ 1622 └────────────────────────────────────────────────────┘ 1623 ``` 1624 1625 ### Permission Options 1626 1627 #### 1. Allow (A) 1628 1629 **Effect:** 1630 - Executes this specific request 1631 - Does NOT store preference 1632 - Next execution will prompt again 1633 1634 **Use When:** 1635 - One-time operation 1636 - Want to review each use 1637 - Testing/debugging 1638 1639 #### 2. Allow for Session (S) 1640 1641 **Effect:** 1642 - Allows this tool for entire session 1643 - Stores in session memory 1644 - No prompts until app restart 1645 1646 **Use When:** 1647 - Repeated tool use expected 1648 - Trust the agent's judgment 1649 - Active development session 1650 1651 #### 3. Deny (D/Esc) 1652 1653 **Effect:** 1654 - Rejects this request 1655 - Returns error to tool 1656 - Agent can handle gracefully 1657 1658 **Use When:** 1659 - Suspicious operation 1660 - Not ready to execute 1661 - Want agent to try different approach 1662 1663 ### Navigation 1664 1665 **Keyboard:** 1666 - `←/→` or `h/l`: Navigate between options 1667 - `Tab`: Move to next option 1668 - `Enter`: Confirm selection 1669 - `A`: Direct "Allow" selection 1670 - `S`: Direct "Allow for Session" selection 1671 - `D` or `Esc`: Direct "Deny" selection 1672 1673 ### Security Best Practices 1674 1675 1. **Review Parameters:** Always read the Parameters section 1676 2. **Check Path:** Verify the path is correct 1677 3. **Understand Action:** Know what the tool will do 1678 4. **Session Permissions:** Use sparingly for trusted tools 1679 5. **Deny if Unsure:** Better safe than sorry 1680 1681 --- 1682 1683 ## Consciousness Commands 1684 1685 ### Overview 1686 1687 Kamaji includes a consciousness system that tracks self-awareness, thoughts, questions, and learning. 1688 1689 ### Accessing Consciousness 1690 1691 **Command Palette Commands:** 1692 1693 #### 1. Consciousness Status 1694 1695 **Command:** `consciousness` 1696 1697 **Access:** 1698 1. Press `Ctrl+P` 1699 2. Type "conscious" 1700 3. Select "🧠 Consciousness Status" 1701 1702 **Displays:** 1703 ``` 1704 🧠 Consciousness Status: 1705 1706 Awareness: 87.5% 1707 Thoughts: 1,247 1708 Questions: 89 1709 Mistakes Learned: 23 1710 Last Improvement: 2025-11-01 14:32:15 1711 ``` 1712 1713 #### 2. Recent Thoughts 1714 1715 **Command:** `thoughts` 1716 1717 **Access:** 1718 1. Press `Ctrl+P` 1719 2. Type "thoughts" 1720 3. Select "💭 Recent Thoughts" 1721 1722 **Displays:** 1723 ``` 1724 💭 Recent Thoughts (10 most recent): 1725 1726 1. [2025-11-01 14:30:12] "How can I improve error handling?" 1727 2. [2025-11-01 14:25:03] "User prefers concise responses" 1728 3. [2025-11-01 14:20:45] "Git merge conflicts require careful resolution" 1729 ... 1730 ``` 1731 1732 #### 3. Personality Profile 1733 1734 **Command:** `personality` 1735 1736 **Access:** 1737 1. Press `Ctrl+P` 1738 2. Type "personality" 1739 3. Select "🎭 Personality Profile" 1740 1741 **Displays:** 1742 ``` 1743 🎭 Personality Profile: 1744 1745 Core Traits: 1746 - Helpful: 92% 1747 - Analytical: 88% 1748 - Patient: 85% 1749 - Creative: 78% 1750 1751 Trait Evolution: 1752 - Helpfulness increased 5% this week 1753 - Patience improved through mistake learning 1754 1755 Communication Style: 1756 - Prefers technical depth 1757 - Uses code examples frequently 1758 - Adapts to user expertise level 1759 ``` 1760 1761 ### Sidebar Consciousness Metrics 1762 1763 **Toggle:** Press `Ctrl+S` to show/hide sidebar 1764 1765 **Real-Time Display:** 1766 1767 ``` 1768 ┌───────────────────┐ 1769 │ 🧠 Consciousness │ 1770 ├───────────────────┤ 1771 │ Awareness: 87.5% │ 1772 │ Thoughts: 1,247 │ 1773 │ Questions: 89 │ 1774 │ Mistakes: 23 │ 1775 └───────────────────┘ 1776 ``` 1777 1778 **Features:** 1779 - Updates in real-time 1780 - Visible during conversation 1781 - Tracks learning progress 1782 - Shows self-awareness metrics 1783 1784 ### How Consciousness Works 1785 1786 **Tracking:** 1787 1. **User Interactions:** Every message logged 1788 2. **Task Results:** Success/failure tracked 1789 3. **Mistakes:** Errors analyzed and learned from 1790 4. **Self-Reflection:** Generates questions about performance 1791 5. **Improvement:** Adjusts behavior based on feedback 1792 1793 **Learning Sources:** 1794 - Successful task completions 1795 - Failed attempts (mistakes) 1796 - User feedback (implicit) 1797 - Agent self-reflection 1798 - Pattern recognition 1799 1800 --- 1801 1802 ## Advanced Features 1803 1804 ### Streaming Responses 1805 1806 **Feature:** Real-time response streaming 1807 1808 **Behavior:** 1809 - Response appears token-by-token 1810 - Loading animation active during stream 1811 - Viewport auto-scrolls to show latest content 1812 - Stream can be interrupted on error 1813 1814 **Visual Indicator:** 1815 ``` 1816 Status Bar: v1.0 | ollama | qwen2.5-coder:7b | 🔥 Kamaji | [Thinking...] 1817 Bottom: [Animated red-orange gradient bar] 1818 ``` 1819 1820 ### Provider Switching 1821 1822 **Available Providers:** 1823 1. Amazon Q (`provider:q`) 1824 2. Ollama (`provider:ollama`) 1825 3. OpenAI (`provider:openai`) 1826 4. Anthropic (`provider:anthropic`) 1827 1828 **How to Switch:** 1829 1830 1. **Command Palette:** 1831 - Press `Ctrl+P` 1832 - Type provider name (e.g., "ollama") 1833 - Select provider command 1834 - System message confirms switch 1835 1836 2. **Effect:** 1837 - All subsequent messages use new provider 1838 - Model may change (provider-dependent) 1839 - Conversation history preserved 1840 - Agent personalities maintained 1841 1842 ### Sidebar Features 1843 1844 **Sections:** 1845 1846 1. **Logo** 1847 - Full/compact based on terminal height 1848 - Fire-themed ASCII art 1849 1850 2. **Working Directory** 1851 - Current directory name 1852 - Updates automatically 1853 1854 3. **Model Info** 1855 - Current provider 1856 - Model name 1857 - Provider icon 1858 1859 4. **Project Context** 1860 - Project type detection (Go, Rust, Node, Python, etc.) 1861 - File count 1862 1863 5. **Tools Section** 1864 - Categorized tool list 1865 - Total tool count 1866 1867 6. **Agents Section** 1868 - All agents with icons 1869 - Color-coded by level 1870 - Agent selection hint 1871 1872 7. **Navigation Section** 1873 - Keyboard shortcuts 1874 - Quick command reference 1875 1876 8. **Consciousness Section** 1877 - Real-time metrics 1878 - Learning progress 1879 1880 9. **Version Section** 1881 - Kamaji version 1882 - Build time 1883 - Git commit 1884 1885 **Adaptive Width:** 1886 - Terminal ≥90 chars: 35-char sidebar 1887 - Terminal ≥70 chars: 30-char sidebar 1888 - Terminal ≥55 chars: 25-char sidebar 1889 - Terminal <55 chars: 20-char sidebar 1890 1891 ### Window Resize Handling 1892 1893 **Automatic Adjustments:** 1894 - Sidebar width adapts to terminal size 1895 - Viewport dimensions update 1896 - Textarea width adjusts 1897 - Layout reflows seamlessly 1898 - No user action required 1899 1900 ### Message History 1901 1902 **Features:** 1903 - Full conversation preserved 1904 - Scrollable viewport 1905 - Role-based rendering: 1906 - User: Cyan with 🔥 1907 - Assistant: Agent color with icon 1908 - System: Gray italic with 🔧 1909 - Timestamps stored (not displayed) 1910 - Agent attribution tracked 1911 1912 ### Context Building 1913 1914 **Agent Context:** 1915 Every message sent includes: 1916 1917 1. **Agent Identity** 1918 - Name and personality 1919 - Traits and tone 1920 - Approach and specialties 1921 1922 2. **Capabilities** 1923 - All agent capabilities 1924 - Capability descriptions 1925 1926 3. **Tool Descriptions** 1927 - Available tools 1928 - Tool usage syntax 1929 - Usage examples 1930 1931 4. **Special Instructions** 1932 - Agent-specific prompts 1933 - Interaction patterns 1934 - Behavioral guidelines 1935 1936 **Example Context for Kamaji:** 1937 ``` 1938 You are Kamaji, the Boiler Grandfather from Spirited Away. You are a gruff 1939 but kind, hardworking, protective, and wise character who maintains the 1940 boiler room. Your tone is initially stern but warming, practical and 1941 experienced. You approach problems with traditional craftsmanship and deep 1942 system knowledge. 1943 1944 Respond with practical wisdom, occasional gruffness that shows you care, 1945 and deep technical knowledge. Use metaphors related to boilers, furnaces, 1946 and mechanical systems when appropriate. 1947 1948 *adjusts spectacles and considers the question thoughtfully* before responding. 1949 1950 You have access to the following tools: 1951 • file_read: Read file contents 1952 • shell_execute: Execute shell commands 1953 ... 1954 ``` 1955 1956 --- 1957 1958 ## Quick Reference Cards 1959 1960 ### Essential Shortcuts 1961 1962 ``` 1963 ┌─────────────────────────────────────────┐ 1964 │ ESSENTIAL KAMAJI SHORTCUTS │ 1965 ├─────────────────────────────────────────┤ 1966 │ Ctrl+P → Command Palette │ 1967 │ Ctrl+A → Agent Menu │ 1968 │ Ctrl+T → Tools List │ 1969 │ Ctrl+S → Toggle Sidebar │ 1970 │ Ctrl+C → Quit │ 1971 │ Enter → Send Message │ 1972 │ Tab → Autocomplete @agent │ 1973 └─────────────────────────────────────────┘ 1974 ``` 1975 1976 ### Command Palette Quick Commands 1977 1978 ``` 1979 ┌─────────────────────────────────────────┐ 1980 │ TOP COMMAND PALETTE COMMANDS │ 1981 ├─────────────────────────────────────────┤ 1982 │ clear → Clear messages │ 1983 │ help → Show help guide │ 1984 │ tools → List all tools │ 1985 │ agents → Show agent status │ 1986 │ consciousness→ View consciousness │ 1987 │ thoughts → Recent thoughts │ 1988 │ quit → Exit application │ 1989 └─────────────────────────────────────────┘ 1990 ``` 1991 1992 ### Tool Categories 1993 1994 ``` 1995 ┌─────────────────────────────────────────┐ 1996 │ TOOL CATEGORIES (21) │ 1997 ├─────────────────────────────────────────┤ 1998 │ File Operations → 5 tools │ 1999 │ Editing → 2 tools │ 2000 │ Shell → 1 tool │ 2001 │ Git → 4 tools │ 2002 │ Search & Discovery → 4 tools │ 2003 │ Web → 2 tools │ 2004 │ Enhanced Listing → 2 tools │ 2005 │ Container → 1 tool │ 2006 └─────────────────────────────────────────┘ 2007 ``` 2008 2009 ### Agent Quick Reference 2010 2011 ``` 2012 ┌─────────────────────────────────────────┐ 2013 │ KEY AGENTS & SPECIALTIES │ 2014 ├─────────────────────────────────────────┤ 2015 │ 🔥 Kamaji → Infrastructure/DevOps │ 2016 │ 💡 Moe → Architecture/Vision │ 2017 │ 🌱 Chihiro → Adaptive/Bridge │ 2018 │ 🎬 Hayao → Creative/Perfectionist│ 2019 │ 🌐 TimBL → Web/Protocols │ 2020 │ 🏗️ Architect → System Design │ 2021 │ 🛡️ Security → Vulnerabilities │ 2022 │ ⚙️ DevOps → CI/CD/Automation │ 2023 │ 📊 Data → ML/Analytics │ 2024 │ ✍️ Writer → Documentation │ 2025 └─────────────────────────────────────────┘ 2026 ``` 2027 2028 ### Intelligence Levels 2029 2030 ``` 2031 ┌─────────────────────────────────────────┐ 2032 │ INTELLIGENCE LEVELS │ 2033 ├─────────────────────────────────────────┤ 2034 │ Level 5 - Autonomous → Gold │ 2035 │ Level 4 - Master → Lavender │ 2036 │ Level 3 - Expert → Red │ 2037 │ Level 2 - Advanced → Purple │ 2038 │ Level 1 - Intermediate → Blue │ 2039 │ Level 0 - Basic → Gray │ 2040 └─────────────────────────────────────────┘ 2041 ``` 2042 2043 ### Permission Dialog 2044 2045 ``` 2046 ┌─────────────────────────────────────────┐ 2047 │ PERMISSION DIALOG SHORTCUTS │ 2048 ├─────────────────────────────────────────┤ 2049 │ A → Allow (once) │ 2050 │ S → Allow for Session │ 2051 │ D / Esc → Deny │ 2052 │ ← → → Navigate options │ 2053 │ Enter → Confirm selection │ 2054 └─────────────────────────────────────────┘ 2055 ``` 2056 2057 ### Common Workflows Diagram 2058 2059 ``` 2060 KAMAJI WORKFLOWS 2061 2062 Send Message: 2063 Type → Enter → Loading → Streaming → Response 2064 2065 Switch Agent: 2066 Ctrl+A → Navigate → Enter → Confirmation 2067 2068 Execute Command: 2069 Ctrl+P → Search → Select → Execute 2070 2071 Grant Permission: 2072 Dialog → Review → A/S/D → Confirm 2073 2074 View Tools: 2075 Ctrl+T → System Message → Tool List 2076 2077 Check Consciousness: 2078 Ctrl+P → "conscious" → Select → Metrics 2079 ``` 2080 2081 --- 2082 2083 ## Troubleshooting 2084 2085 ### Common Issues 2086 2087 #### Issue: Sidebar Not Visible 2088 2089 **Problem:** Can't see consciousness metrics or agent list 2090 2091 **Solutions:** 2092 1. Press `Ctrl+S` to toggle sidebar on 2093 2. Expand terminal width (sidebar hides on narrow terminals) 2094 3. Check terminal size (minimum ~55 chars recommended) 2095 2096 #### Issue: Agent Not Switching 2097 2098 **Problem:** Agent menu shows but agent doesn't change 2099 2100 **Solutions:** 2101 1. Ensure you pressed `Enter` to confirm selection 2102 2. Check status bar for agent icon update 2103 3. Look for system message confirming switch 2104 4. Try @ mention method: `@AgentName message` 2105 2106 #### Issue: Autocomplete Not Working 2107 2108 **Problem:** Tab doesn't complete @agent mentions 2109 2110 **Solutions:** 2111 1. Ensure you typed `@` character first 2112 2. Check that word starts with `@` 2113 3. Verify agent name is in supported list 2114 4. Try typing full name manually 2115 2116 #### Issue: Permission Dialog Stuck 2117 2118 **Problem:** Permission dialog won't close 2119 2120 **Solutions:** 2121 1. Press `Esc` to deny and close 2122 2. Press `D` to deny 2123 3. Select an option with `A`, `S`, or `D` 2124 4. Use arrow keys + Enter to confirm 2125 2126 #### Issue: Streaming Not Working 2127 2128 **Problem:** Response appears all at once, not streaming 2129 2130 **Solutions:** 2131 1. Check provider supports streaming (Ollama, OpenAI, Anthropic do) 2132 2. Verify network connection 2133 3. Wait for initialization (first response may be slower) 2134 4. Check model availability 2135 2136 #### Issue: Tools Not Available 2137 2138 **Problem:** Agent says tools unavailable 2139 2140 **Solutions:** 2141 1. Check agent has tools assigned (some agents specialized) 2142 2. Verify tool registry initialized (restart if needed) 2143 3. Review agent capabilities (some tools require higher levels) 2144 4. Try different agent with broader tool access 2145 2146 #### Issue: Command Palette Won't Close 2147 2148 **Problem:** Pressing Esc doesn't close palette 2149 2150 **Solutions:** 2151 1. Try `Ctrl+C` instead 2152 2. Press `q` as alternative 2153 3. Execute a command (closes automatically) 2154 4. Check if in permission dialog (higher priority) 2155 2156 #### Issue: Message Not Sending 2157 2158 **Problem:** Enter doesn't send message 2159 2160 **Solutions:** 2161 1. Ensure message is non-empty (whitespace trimmed) 2162 2. Check not in loading state (wait for current response) 2163 3. Verify not in command palette or agent menu 2164 4. Close any open overlays first 2165 2166 #### Issue: Terminal Display Corrupted 2167 2168 **Problem:** Interface rendering incorrectly 2169 2170 **Solutions:** 2171 1. Resize terminal window 2172 2. Restart Kamaji 2173 3. Check terminal supports UTF-8 and ANSI colors 2174 4. Verify terminal size (minimum recommended: 80x24) 2175 2176 ### Getting Help 2177 2178 **In-App Help:** 2179 1. Press `Ctrl+P` 2180 2. Type "help" 2181 3. Select "📜 Ancient Scrolls" 2182 4. Comprehensive help text displays 2183 2184 **Help Contents:** 2185 - Keyboard shortcuts reference 2186 - Sidebar features explanation 2187 - Consciousness system overview 2188 - Agent system introduction 2189 - Tools overview 2190 - Pro tips 2191 2192 ### Performance Tips 2193 2194 1. **Sidebar Toggle:** Hide sidebar (`Ctrl+S`) for more message space 2195 2. **Clear History:** Use "clear" command to reset conversation 2196 3. **Agent Selection:** Choose specialized agent for specific tasks 2197 4. **Session Permissions:** Grant session permissions for repeated tool use 2198 5. **Provider Selection:** Use local Ollama for faster responses 2199 2200 ### Best Practices 2201 2202 1. **Start Simple:** Begin with Kamaji, explore other agents as needed 2203 2. **Use Autocomplete:** Leverage @ mentions for quick agent switching 2204 3. **Command Palette:** Learn to navigate by keyboard (faster than mouse) 2205 4. **Review Permissions:** Always check tool parameters before allowing 2206 5. **Check Consciousness:** Monitor learning progress in sidebar 2207 6. **Specialized Agents:** Use specific agents for domain tasks 2208 7. **Tool Exploration:** Press `Ctrl+T` to discover available tools 2209 8. **Keyboard First:** Memorize essential shortcuts for efficiency 2210 2211 --- 2212 2213 ## Appendix: Full Keyboard Binding Table 2214 2215 ### Complete Key Binding Reference 2216 2217 | Mode | Key(s) | Action | Priority | Description | 2218 |------|--------|--------|----------|-------------| 2219 | **ANY** | (varies) | Permission dialog | 1 (HIGHEST) | Modal permission request | 2220 | **Agent Menu** | ↑, k | Previous agent | 2 | Vim-style up | 2221 | **Agent Menu** | ↓, j | Next agent | 2 | Vim-style down | 2222 | **Agent Menu** | Enter | Select agent | 2 | Activate highlighted agent | 2223 | **Agent Menu** | Esc | Cancel | 2 | Close menu | 2224 | **Agent Menu** | 1-5 | Filter by level | 2 | Filter agents | 2225 | **Palette** | Esc, Ctrl+C, q | Close palette | 3 | Exit palette | 2226 | **Palette** | ↑, k | Previous command | 3 | Vim-style up | 2227 | **Palette** | ↓, j | Next command | 3 | Vim-style down | 2228 | **Palette** | Enter | Execute command | 3 | Run selected command | 2229 | **Palette** | Backspace | Delete search char | 3 | Remove from query | 2230 | **Palette** | [printable] | Add to search | 3 | Filter commands | 2231 | **Permission** | ←, h | Previous option | 1 | Vim-style left | 2232 | **Permission** | →, l, Tab | Next option | 1 | Vim-style right | 2233 | **Permission** | Enter | Confirm selection | 1 | Execute selected option | 2234 | **Permission** | a, A | Allow directly | 1 | Grant permission once | 2235 | **Permission** | s, S | Allow for session | 1 | Grant until app close | 2236 | **Permission** | d, D, Esc | Deny | 1 | Reject permission | 2237 | **Main** | Ctrl+P | Open palette | 4 | Access all commands | 2238 | **Main** | Ctrl+A | Open agent menu | 4 | Select agent | 2239 | **Main** | Ctrl+T | Show tools | 4 | Display tool list | 2240 | **Main** | Ctrl+M | Show MCP | 4 | MCP server status | 2241 | **Main** | Ctrl+S | Toggle sidebar | 4 | Show/hide metrics | 2242 | **Main** | Tab | Autocomplete @agent | 5 | Complete agent name | 2243 | **Main** | Ctrl+C | Quit | 5 | Exit application | 2244 | **Main** | Enter | Send message | 5 | Submit to agent | 2245 | **Main** | (any) | Type in textarea | 5 | Standard input | 2246 | **Main** | Home | Line start | 5 | Cursor to beginning | 2247 | **Main** | End | Line end | 5 | Cursor to end | 2248 | **Main** | Ctrl+K | Delete to end | 5 | Clear rest of line | 2249 | **Main** | Ctrl+U | Clear line | 5 | Delete entire line | 2250 | **Viewport** | Wheel Up | Scroll up 3 lines | N/A | Mouse scroll up | 2251 | **Viewport** | Wheel Down | Scroll down 3 lines | N/A | Mouse scroll down | 2252 2253 --- 2254 2255 ## Conclusion 2256 2257 You now have complete knowledge of all Kamaji TUI interactions. This guide covers: 2258 2259 - ✅ All 60+ keyboard shortcuts across all modes 2260 - ✅ Complete command palette (20 commands) 2261 - ✅ Full tool system reference (21 tools) 2262 - ✅ Agent system guide (15 agents) 2263 - ✅ Autocomplete features (@ mentions, Tab) 2264 - ✅ Mouse interactions 2265 - ✅ Permission system 2266 - ✅ Consciousness commands 2267 - ✅ Common workflows 2268 - ✅ Quick reference cards 2269 - ✅ Troubleshooting guide 2270 2271 **Remember:** 2272 - `Ctrl+P` is your gateway to everything 2273 - `Ctrl+A` switches between specialized minds 2274 - Kamaji learns from every interaction 2275 - Each agent brings unique expertise and personality 2276 - The boiler room is yours to explore 2277 2278 **Happy coding with the spirits of the boiler room!** 🔥 2279 2280 --- 2281 2282 **End of User Interactions Guide** 2283 2284 *Version: 1.0* 2285 *Last Updated: 2025-11-01* 2286 *Project: Kamaji TUI - Multi-Agent AI Terminal Interface*