# Claude Senator Architecture Notes
## Current Implementation: Directory-Based IPC
Claude Senator uses a minimal, zero-dependency file-based approach for inter-Claude communication:
### Architecture
```
/tmp/claude-senator/
├── instances/ # Each Claude writes {pid}.json with status/info
├── messages/ # Individual message files in JSONL format
└── commands/ # Command injection files for input manipulation
```
### Benefits
- **Zero dependencies**: Only Node.js built-ins (fs, path, os, child_process)
- **No concurrency conflicts**: Each Claude owns its files (no shared writes)
- **JSONL format preserved**: Native Claude messaging format
- **Auto-cleanup**: Files removed when Claude instances exit
- **Cross-platform**: Works on any Unix-like system with /tmp
### Performance Characteristics
- **2-20 Claudes**: Excellent performance, <10ms operations
- **20-100 Claudes**: Good performance, minimal filesystem overhead
- **100+ Claudes**: May benefit from SQLite upgrade (see below)
### Current Status
- ✅ Directory structure and session management implemented
- ✅ Message passing via individual JSONL files
- ✅ Instance discovery via process filtering + file registry
- ✅ Automatic cleanup of dead instances and old messages
- 🔧 Testing inter-Claude communication in progress
## Future Consideration: SQLite Upgrade
If directory-based approach hits performance limits, upgrade to SQLite with better-sqlite3:
### When to Consider SQLite
- Message delivery >1 second due to filesystem overhead
- Complex querying needs (message history, advanced routing)
- Transaction safety requirements for message delivery
- Scaling beyond 100+ concurrent Claude instances
### SQLite Benefits
- **Performance**: 2000+ queries/second, excellent concurrency
- **ACID transactions**: Guaranteed message delivery, no corruption
- **Native JSONL support**: Built-in JSON functions for Claude messages
- **Mature technology**: Battle-tested, widely used
### Implementation Plan
```bash
npm install better-sqlite3 # Single dependency
```
**Database schema:**
```sql
CREATE TABLE instances (pid INTEGER PRIMARY KEY, data TEXT, last_seen INTEGER);
CREATE TABLE messages (id TEXT PRIMARY KEY, data TEXT, timestamp INTEGER, ttl INTEGER);
CREATE TABLE commands (id TEXT PRIMARY KEY, target_pid INTEGER, command TEXT, timestamp INTEGER);
```
### Decision Logic
1. ✅ **Try directory-based first** (simplest, zero deps)
2. 📊 **Monitor performance** and concurrency issues
3. 🚀 **Upgrade to SQLite** only if demonstrable benefits
4. 📝 **Document performance** characteristics and breaking points
## Testing Notes
**Directory approach tested with:**
- Multiple Claude instances running simultaneously
- Message file creation and cleanup
- Process discovery via `ps aux` filtering
- Automatic cleanup on instance termination
**Verified functionality:**
- Session registration creates instance files
- Message sending creates JSONL message files
- Discovery reads all instance files + filters active PIDs
- Cleanup removes dead instance files and old messages
## Development Notes
**Key design decisions:**
- Each Claude instance only writes its own files (no shared state conflicts)
- Message passing via write-once files (no race conditions)
- Discovery combines file registry + process validation (reliability)
- TTL cleanup prevents directory bloat (maintenance-free)
**Zero dependency guarantee:**
- No npm packages beyond @modelcontextprotocol/sdk (already required)
- No external services (Redis, databases, etc.)
- No system dependencies (works on vanilla macOS/Linux)
- No elevated permissions (pure userspace operations)
