AGENTS.md

1# Claude Code Personalities
2 
3> Dynamic text-face personalities for Claude Code's statusline that change based on what Claude is doing
4 
5## Important Rules
6 
7- **NO EMOJIS**: Never use emojis in any files or output
8- **Nerd Font Icons Only**: If icons are needed, use Nerd Font UTF-8 byte sequences only (e.g., `\u{f07b}` for folder icon)
9- **Never replace local binary directly**: The developer is an end user too. Always use `claude-code-personalities update` or download from releases - never `cp` the binary directly. This ensures the update flow is tested.
10 
11## What is This?
12 
13Claude Code Personalities is a personality system that gives Claude Code a dynamic, context-aware statusline with text-face emoticons that change based on Claude's current activity. Instead of a static prompt, you get a fun, informative statusline that shows Claude's "mood" and what it's currently working on.
14 
15**Rust Implementation**: The project is implemented in pure Rust for lightning-fast performance, better error handling, and zero external dependencies. No shell scripts needed!
16 
17### Features
18 
19- **30+ Text-Face Personalities**: From `ʕ•ᴥ•ʔ Code Wizard` to `(┛ಠДಠ)┛彡┻━┻ Frustrated Developer`
20- **Context-Aware**: Personalities change based on files being edited, commands run, and errors encountered
21- **Git Status Indicator**: Real-time display of working tree status with file counts (`±5` for dirty, `✓` for clean)
22- **Interactive Configuration**: Use `config` command to customize what appears in statusline
23- **Activity Tracking**: Monitors Claude's tool usage (Edit, Bash, Grep, etc.) via hooks
24- **Error State Management**: Claude gets progressively more frustrated with errors
25- **Nerd Font Icons**: Visual indicators for folders, activities, and status
26- **Session Persistence**: Maintains personality state across a Claude Code session
27- **Model-Specific Indicators**: Different icons for Opus, Sonnet, and Haiku
28 
29## How It Works
30 
31```mermaid
32graph LR
33    A[Claude Code] -->|JSON Input| B[claude-code-personalities --statusline]
34    A -->|Hook Events| C[claude-code-personalities --hook]
35    C -->|Updates State| D[/tmp/claude_session_*.json]
36    D -->|Reads State| B
37    B -->|Displays| E[Terminal Statusline]
38```
39 
401. **Claude Code** calls the binary with `--statusline` and passes JSON input containing session and workspace info
412. **Hook system** intercepts tool usage (PreToolUse/PostToolUse) and calls binary with `--hook` to track Claude's activities
423. **State management** updates personality and activity based on context (files, tools, errors)
434. **Persistent state** maintained in `/tmp/claude_session_*.json` files across the session
445. **Statusline display** shows personality, current directory, activity, and model
45 
46## Architecture
47 
48### Pure Rust Binary
49 
50The entire system is contained in a single Rust binary that operates in different modes:
51 
52```
53claude-code-personalities
54├── --statusline          # Generate statusline output (called by Claude Code)
55├── --hook <type>         # Handle hook events (pre-tool, post-tool, session-end)
56├── init                  # Initialize Claude Code settings for personalities
57├── config                # Interactive configuration menu
58├── status                # Check installation status
59├── update                # Update to latest version
60└── uninstall             # Remove personalities
61```
62 
63### File Structure
64 
65```
66~/.claude/
67├── claude-code-personalities           # Main Rust binary
68├── settings.json                       # Claude Code configuration (modified by installer)
69└── personalities_config.json          # User preferences (created by config command)
70 
71/tmp/
72└── claude_session_<session_id>.json    # Session state (personality, activity, error count)
73```
74 
75### Configuration in settings.json
76 
77The installer modifies Claude Code's `~/.claude/settings.json` to add:
78 
79```json
80{
81  "statusLine": {
82    "type": "command", 
83    "command": "/Users/user/.claude/claude-code-personalities",
84    "args": ["--statusline"],
85    "padding": 0
86  },
87  "hooks": {
88    "PreToolUse": [{
89      "matcher": "*",
90      "hooks": [{
91        "type": "command",
92        "command": "/Users/user/.claude/claude-code-personalities",
93        "args": ["--hook", "pre-tool"]
94      }]
95    }],
96    "PostToolUse": [{
97      "matcher": "*", 
98      "hooks": [{
99        "type": "command",
100        "command": "/Users/user/.claude/claude-code-personalities",
101        "args": ["--hook", "post-tool"]
102      }]
103    }],
104    "Stop": [{
105      "hooks": [{
106        "type": "command",
107        "command": "/Users/user/.claude/claude-code-personalities",
108        "args": ["--hook", "session-end"]
109      }]
110    }]
111  }
112}
113```
114 
115## How Personalities Work
116 
117### Personality Assignment Logic
118 
119The Rust binary analyzes tool usage and context to determine personalities:
120 
121```rust
122// Error-based frustration (highest priority)
123if error_count >= 5 { "(╯°□°)╯︵ ┻━┻ Table Flipper" }
124else if error_count >= 3 { "(┛ಠДಠ)┛彡┻━┻ Frustrated Developer" }
125 
126// Tool-based personalities  
127else if tool == "Bash" && args.contains("git") { "┗(▀̿Ĺ̯▀̿ ̿)┓ Git Manager" }
128else if tool == "Grep" || activity == "searching" { "( ͡° ͜ʖ ͡°) Search Detective" }
129else if tool == "Edit" && file.ends_with(".md") { "(͡• ͜໒ ͡• ) Documentation Writer" }
130else if tool == "Edit" && file.ends_with(".rs") { "\ue7a8 Rust Developer" }
131 
132// Activity-based fallbacks
133else if activity == "editing" { "ʕ•ᴥ•ʔ Code Wizard" }
134else if activity == "reading" { "(⌐■_■) File Inspector" }
135else { "(｡◕‿◕｡) Helpful Assistant" }
136```
137 
138### Session State Format
139 
140State is stored in `/tmp/claude_session_<session_id>.json`:
141 
142```json
143{
144  "session_id": "abc-123",
145  "activity": "editing", 
146  "personality": "ʕ•ᴥ•ʔ Code Wizard",
147  "consecutive_actions": 5,
148  "error_count": 0,
149  "last_updated": "2024-08-27T10:30:00Z"
150}
151```
152 
153## Installation Process
154 
155The `install.sh` script:
156 
1571. **Downloads binary** from GitHub releases
1582. **Installs binary** to `~/.local/bin/claude-code-personalities`
1593. **Runs `init`** automatically to configure Claude Code
160 
161The `claude-code-personalities init` command:
162 
1631. **Creates/verifies** `~/.claude/` directory exists
1642. **Backs up** existing `settings.json` (timestamped)
1653. **Configures statusline** and hooks in `settings.json`
1664. **Validates setup** by verifying configuration
167 
168## Configuration
169 
170### Interactive Configuration
171 
172```bash
173claude-code-personalities config
174```
175 
176Opens a multi-select menu to toggle. The menu displays your current configuration with checkboxes pre-selected for enabled options, so you can immediately see what's active and make changes as needed:
177- Show Personality (text faces)
178- Show Activity (current action)
179- Show Activity Context (files/commands)
180- Show Git Branch
181- Show Git Status (working tree changes with count)
182- Show Current Directory
183- Show Model Indicator
184- Use Nerd Font Icons
185- Use ANSI Colors
186- Show Separators
187- Compact Mode
188- Debug Info
189- Theme Selection
190 
191Settings saved to `~/.claude/personalities_config.json`:
192 
193```json
194{
195  "show_personality": true,
196  "show_activity": true,
197  "show_context": true,
198  "show_git_branch": true,
199  "show_git_status": true,
200  "show_current_dir": false,
201  "show_model": true,
202  "use_icons": true,
203  "use_colors": true,
204  "display": {
205    "show_separators": true,
206    "compact_mode": false,
207    "show_debug_info": false
208  },
209  "theme": "Dark"
210}
211```
212 
213#### Git Status Display
214 
215The git status feature shows real-time working tree status:
216 
217- **Dirty state**: `±5` (orange/yellow) - Shows number of uncommitted files
218- **Clean state**: `✓` (green) - Indicates no uncommitted changes
219- **Performance**: 2-second caching to minimize git command overhead
220- **Smart**: Only updates when cache expires or state changes
221 
222Example statusline with git status:
223```
224ʕ•ᴥ•ʔ Code Wizard •  main ±5 • Editing src/main.rs • Sonnet
225```
226 
227### Custom Personalities
228 
229Personalities are defined in Rust code (`src/statusline/personality.rs`). To add custom ones, modify the personality determination logic and rebuild:
230 
231```rust
232else if file_path.ends_with(".py") {
233    "\ue73c Python Developer".to_string()
234}
235```
236 
237## Nerd Font Icons Reference
238 
239Icons are defined using UTF-8 sequences:
240 
241| UTF-8 Bytes    | Unicode | Description     |
242| -------------- | ------- | --------------- |
243| `\xef\x81\xbb` | U+F07B  | Folder          |
244| `\xef\x84\xa1` | U+F121  | Code            |
245| `\xef\x86\x88` | U+F188  | Bug             |
246| `\xef\x80\x82` | U+F002  | Search          |
247| `\xef\x81\x84` | U+F044  | Edit            |
248| `\xef\x83\xa7` | U+F0E7  | Lightning/Run   |
249| `\xef\x81\xae` | U+F06E  | Eye/Review      |
250| `\xef\x83\xab` | U+F0EB  | Lightbulb/Think |
251| `\xef\x84\xb5` | U+F135  | Rocket          |
252| `\xef\x81\xb1` | U+F071  | Warning         |
253| `\xef\x81\x97` | U+F057  | Error           |
254| `\xef\x81\xad` | U+F06D  | Fire            |
255| `\xef\x80\x93` | U+F013  | Gear            |
256| `\xef\x84\xa0` | U+F120  | Terminal        |
257 
258## Testing
259 
260### Test Statusline Generation
261```bash
262# Simulate Claude Code input
263echo '{"session_id":"test","model":{"display_name":"Opus"},"workspace":{"current_dir":"/project"}}' | claude-code-personalities --statusline
264```
265 
266### Test Hook Processing
267```bash
268# Simulate tool usage hook
269echo '{"session_id":"test","tool_name":"Edit","tool_input":{"file_path":"main.rs"}}' | claude-code-personalities --hook pre-tool
270```
271 
272### Debug Mode
273```bash
274# Check what's in the state file
275cat /tmp/claude_session_test.json
276 
277# Check installation status
278claude-code-personalities status
279```
280 
281## Troubleshooting
282 
283### Icons Not Displaying
2841. Install Nerd Fonts: `brew install --cask font-hack-nerd-font`
2852. Set terminal font to a Nerd Font
2863. Test: `printf '\xef\x81\xbb'` should show folder icon
287 
288### Personality Not Changing
2891. Check installation: `claude-code-personalities status`
2902. Verify hooks in `~/.claude/settings.json`
2913. Check state file exists: `ls /tmp/claude_session_*.json`
2924. Test hook manually with echo command above
293 
294### Always Shows Default Personality
295- State file isn't being created/updated
296- Check that hooks are configured correctly
297- Ensure session_id is being passed from Claude Code
298 
299### Update Issues
3001. Check binary location: `which claude-code-personalities`
3012. Run status check: `claude-code-personalities status`
3023. Reinitialize if needed: `claude-code-personalities init`
303 
304### Performance Issues
305The Rust implementation is designed for speed:
306- Binary startup: ~1ms
307- State file I/O: ~0.1ms  
308- Personality calculation: ~0.01ms
309- Total statusline generation: <2ms
310 
311If experiencing slowness, check:
312- Disk space in `/tmp`
313- File permissions on state files
314- Multiple concurrent hook executions
315 
316## Development
317 
318### Building from Source
319 
320**Use `just` for development commands** - the project uses a justfile for common tasks:
321```bash
322just              # Show available commands
323just build        # Build release binary
324just test         # Run tests
325just lint         # Run clippy
326just develop-link # Link dev binary for testing (creates symlink)
327just develop-unlink # Restore original binary
328```
329 
330Manual build:
331```bash
332cargo build --release
333# Binary at target/release/claude-code-personalities
334```
335 
336### Adding New Personalities
3371. Edit `src/statusline/personality.rs`
3382. Add new personality patterns to `determine_personality()`
3393. Add corresponding kaomoji to `src/kaomoji/`
3404. Rebuild and test
341 
342### Releasing a New Version
343 
344Use the `just release` command for the full release workflow:
345 
346```bash
347just release 0.4.3
348```
349 
350This automatically:
3511. Updates version in `Cargo.toml`
3522. Builds for all platforms (via `build-cross.sh`)
3533. Commits the version bump
3544. Creates and pushes a git tag
3555. GitHub Actions builds and publishes the release
356 
357**Config Versioning**: When making breaking changes to `personalities_config.json`:
3581. Increment `CONFIG_VERSION` in `src/config/preferences.rs`
3592. Add migration logic in the `migrate()` function
3603. Document the change in the version comments
361 
362### Contributing
363- Follow existing code patterns
364- Add tests for new functionality
365- Update documentation
366- Use `cargo fmt` and `cargo clippy`
367 
368## Architecture Benefits
369 
370The pure Rust implementation provides:
371 
372- **Performance**: 10-100x faster than shell scripts
373- **Reliability**: Better error handling and recovery
374- **Maintainability**: Single codebase vs scattered scripts
375- **Portability**: Same binary works across platforms
376- **Security**: No shell injection vulnerabilities
377- **Dependencies**: Zero external runtime dependencies
378 
379# important-instruction-reminders
380Do what has been asked; nothing more, nothing less.
381NEVER create files unless they're absolutely necessary for achieving your goal.
382ALWAYS prefer editing an existing file to creating a new one.
383NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.
384