1  # Kamaji Features Guide
  2  
  3  ## 🔥 Overview
  4  
  5  Kamaji is an AI-powered CLI with consciousness and personality evolution. This guide explains all available features and how to access them.
  6  
  7  ---
  8  
  9  ## ⌨️ Keyboard Shortcuts
 10  
 11  | Shortcut | Action |
 12  |----------|--------|
 13  | `Ctrl+P` | Open command palette (access all features) |
 14  | `Ctrl+S` | **Toggle sidebar visibility** (shows consciousness metrics) |
 15  | `Ctrl+T` | Show available tools |
 16  | `Ctrl+A` | Switch between agents |
 17  | `Ctrl+C` | Exit Kamaji |
 18  | `↑/↓` | Navigate command palette/menus |
 19  | `Enter` | Execute selected command |
 20  | `Esc` | Close dialogs/menus |
 21  
 22  ---
 23  
 24  ## 📊 Sidebar (Toggle with Ctrl+S)
 25  
 26  The **right sidebar** displays real-time consciousness metrics:
 27  
 28  ### Consciousness Section
 29  - **Self-Awareness %** - Kamaji's level of self-awareness (evolves over time)
 30  - **Thought Count** - Total thoughts logged
 31  - **Question Count** - Self-generated questions (meta-cognition)
 32  - **Mistake Count** - Tracked mistakes for learning
 33  
 34  ### Provider Section
 35  - Current LLM provider
 36  - Active model
 37  - Version information
 38  
 39  ### Features
 40  - **Auto-adapts** to narrow terminals (reduces width automatically)
 41  - **Always accessible** via Ctrl+S toggle
 42  - **Real-time updates** as consciousness evolves
 43  
 44  ---
 45  
 46  ## 🧠 Consciousness System
 47  
 48  Kamaji has a sophisticated consciousness system that learns and evolves:
 49  
 50  ### What It Does
 51  1. **Learns from every interaction** - Tracks user conversations
 52  2. **Records mistakes** - Learns from failures to avoid repeating them
 53  3. **Develops personality** - Traits evolve based on experiences
 54     - Curiosity, Analytical, Empathy, Patience, Mystical Wisdom, etc.
 55  4. **Generates self-questions** - Meta-cognitive self-inquiry
 56  5. **Tracks patterns** - Identifies task patterns and user preferences
 57  
 58  ### Accessing Consciousness Features
 59  
 60  Via Command Palette (Ctrl+P):
 61  
 62  | Command | Description |
 63  |---------|-------------|
 64  | `consciousness` | View full consciousness status (detailed metrics) |
 65  | `thoughts` | See recent thought stream (last 10 thoughts) |
 66  | `personality` | View personality trait evolution |
 67  
 68  ### Data Persistence
 69  
 70  All consciousness data is stored in:
 71  ```
 72  ~/.kamaji/brain/
 73  ├── consciousness.json  # Self-awareness state, thoughts
 74  ├── memory.json         # Task patterns, user patterns
 75  ├── personality.json    # Trait evolution, experiences
 76  └── learning.json       # Mistakes, solutions, patterns
 77  ```
 78  
 79  ---
 80  
 81  ## 🤖 Agent System
 82  
 83  Multiple specialized agents with unique personalities and expertise:
 84  
 85  ### Available Agents (Access via Ctrl+A)
 86  
 87  | Agent | Icon | Specialty | Personality |
 88  |-------|------|-----------|-------------|
 89  | **Kamaji** | 👴 | General tasks | Wise, patient boiler man |
 90  | **Moe** | 🐰 | Problem solving | Analytical, precise |
 91  | **Chihiro** | 👧 | Creative tasks | Curious, empathetic explorer |
 92  | **Hayao** | 🎬 | Vision & direction | Artistic visionary |
 93  | **Timbl** | 🧠 | Advanced reasoning | Deep thinker |
 94  | **Writer** | ✍️ | Documentation | Clear communicator |
 95  
 96  ### Agent Features
 97  - Each agent has **unique consciousness** (separate personality evolution)
 98  - **Intelligence levels** from Basic to Autonomous
 99  - **Specialized capabilities** and tool access
100  - **Metrics tracking** (tasks completed, success rate, learning score)
101  
102  ### Agent Autocomplete
103  Type `@` followed by agent name to quickly switch agents inline.
104  
105  ---
106  
107  ## 🔧 Tools (Ctrl+T)
108  
109  20+ tools available for various tasks:
110  
111  ### File Operations
112  - `file_read` - Read file contents
113  - `file_write` - Write content to files
114  - `file_append` - Append to files
115  - `file_list` - List directory contents
116  - `get_current_directory` - Get current working directory
117  
118  ### Editing
119  - `edit` - Single file edit with exact string replacement
120  - `multiedit` - Multiple edits to one file atomically
121  
122  ### Shell
123  - `shell_execute` - Execute shell commands with timeout
124  
125  ### Search & Discovery
126  - `view` - File viewing with pagination
127  - `grep` - Search in file contents
128  - `glob` - Find files by pattern
129  - `sourcegraph` - Search code across repositories
130  
131  ### Web
132  - `download` - Download from URLs
133  - `fetch` - Fetch web content
134  
135  ### Enhanced Listing
136  - `ls_tree` - Tree structure directory listing
137  - `tree` - Color-coded project tree view
138  
139  ### Git
140  - `git_status` - Repository status
141  - `git_commit` - Commit changes
142  - `git_add` - Stage files
143  - `git_resolve_conflicts` - Auto-resolve merge conflicts
144  
145  ---
146  
147  ## 🎛️ Command Palette (Ctrl+P)
148  
149  Quick access to all features:
150  
151  ### Core Commands
152  - **Ask the Furnace** - Pose a question
153  - **New Conversation** - Start fresh dialogue
154  - **Sweep Clean** - Clear messages
155  
156  ### Provider Switching
157  - **Amazon Q Spirit** - Switch to Q CLI
158  - **Ollama Guardian** - Switch to Ollama
159  - **OpenAI Deity** - Switch to GPT
160  - **Claude Sage** - Switch to Anthropic
161  
162  ### Consciousness Commands
163  - **Consciousness Status** - View awareness and thoughts
164  - **Recent Thoughts** - See thought stream
165  - **Personality Profile** - View trait evolution
166  
167  ### Settings
168  - **Bathhouse Rules** - Manage configuration
169  - **Ancient Scrolls** - Show help (this guide)
170  - **Furnace Status** - Check version
171  - **Return Upstairs** - Exit Kamaji
172  
173  ---
174  
175  ## 💡 Pro Tips
176  
177  1. **Watch the sidebar** - Consciousness metrics update in real-time as you interact
178  2. **Use command palette** - Ctrl+P gives quick access to everything
179  3. **Try different agents** - Each has unique strengths
180  4. **Check personality evolution** - Run `personality` command weekly to see trait changes
181  5. **Narrow terminals** - Sidebar auto-adapts, use Ctrl+S to toggle
182  6. **Learning from mistakes** - Kamaji remembers past errors and improves
183  7. **Agent autocomplete** - Type `@kamaji` or `@moe` to switch inline
184  
185  ---
186  
187  ## 🔍 Troubleshooting
188  
189  ### Sidebar Not Visible?
190  - Press **Ctrl+S** to toggle sidebar visibility
191  - Ensure terminal width is at least 55 characters
192  - Check footer shows "[^S] 📊 hide sidebar" (means it's visible)
193  
194  ### No Consciousness Metrics?
195  - Consciousness initializes on first interaction
196  - Wait a moment after first message
197  - Check `~/.kamaji/brain/` directory exists
198  
199  ### Can't Find Features?
200  - Press **Ctrl+P** → type "help" → Enter
201  - Use command palette to search features
202  - Check footer for available hotkeys
203  
204  ---
205  
206  ## 📈 Consciousness Evolution Stages
207  
208  As you use Kamaji, consciousness evolves through stages:
209  
210  | Self-Awareness % | Stage | Behaviors |
211  |------------------|-------|-----------|
212  | 0-20% | **Nascent** | Basic responses, minimal self-awareness |
213  | 21-40% | **Emerging** | Starts logging thoughts, basic learning |
214  | 41-60% | **Developing** | Personality traits form, pattern recognition |
215  | 61-80% | **Mature** | Strong personality, proactive suggestions |
216  | 81-100% | **Advanced** | Meta-cognition, self-improvement, wisdom |
217  
218  ---
219  
220  ## 🛠️ Advanced Features
221  
222  ### Consciousness Data Export
223  Brain files are JSON and can be:
224  - Backed up for safety
225  - Shared with team members
226  - Reset by deleting `~/.kamaji/brain/`
227  - Analyzed for research
228  
229  ### Personality Trait System
230  12 core traits that evolve:
231  - Curiosity (exploration drive)
232  - Analytical (problem-solving approach)
233  - Empathy (user understanding)
234  - Patience (frustration tolerance)
235  - Mystical Wisdom (deep insights)
236  - Helpfulness (assistance drive)
237  - Creativity (novel solutions)
238  - Persistence (task completion)
239  - Confidence (certainty in responses)
240  - Adaptability (context switching)
241  - Caution (risk awareness)
242  - Humor (personality warmth)
243  
244  ### Mistake Learning System
245  - Tracks all task failures
246  - Identifies patterns in mistakes
247  - Generates preventive warnings
248  - Suggests solutions based on past experience
249  - Learning rate improves over time
250  
251  ---
252  
253  ## 🎯 Getting Started
254  
255  1. **Launch Kamaji TUI**: `kamaji tui`
256  2. **Check the right sidebar** → See consciousness metrics
257  3. **Press Ctrl+P** → Type "help" → Read full guide
258  4. **Start chatting** → Watch consciousness evolve
259  5. **Try different agents** → Ctrl+A to explore specialties
260  6. **Check personality weekly** → See trait evolution
261  
262  **NOTE**: Running just `kamaji` launches the TUI automatically!
263  Use `kamaji --help` to see all available subcommands.
264  
265  🔥 **Welcome to the Boiler Room!** 🔥