---
## 🌟 Why Catui?
> **"The only AI coding assistant that truly learns from you"**
Catui isn't just another AI coding tool. It's a **terminal-native AI agent** with **persistent memory** and **evolving personality** — designed for developers who live in the terminal.
### What Makes It Different?
| | Other Tools | Catui |
|---|---|---|
| **Memory** | ❌ Starts fresh every session | ✅ Remembers your projects, preferences, and coding style |
| **Personality** | ❌ Generic responses | ✅ Evolves a unique personality based on your interactions |
| **Terminal Native** | ❌ GUI wrappers or plugins | ✅ Pure TUI built for terminal workflows |
| **Model Freedom** | ❌ Vendor lock-in | ✅ 10+ providers, switch instantly |
| **Offline Ready** | ❌ Cloud dependent | ✅ Local models via Ollama |
---
## ✨ Features
### 🧠 Persistent Memory (NanoMem)
Your projects have context. So should your AI.
- **Project Knowledge** — API endpoints, database schemas, architecture decisions
- **Error Patterns** — Remembers bugs and their solutions
- **User Preferences** — Coding style, naming conventions, framework choices
- **Smart Retrieval** — Automatically recalls relevant context when needed
### 💫 AI Personality Evolution (NanoSoul)
Your AI assistant develops its own character.
- **Big Five Traits** — Openness, Conscientiousness, Extraversion, Agreeableness, Neuroticism
- **Coding Style** — Verbosity, abstraction level, safety margins
- **Domain Expertise** — Frontend, Backend, DevOps, AI/ML specializations
- **Emotional States** — Confidence, curiosity, flow state
> *After 50 sessions, your Catui will code differently than anyone else's.*
### 🎨 Beautiful TUI
A terminal interface that feels alive.
- **Three Themes** — Dark, Light, and Warm (eye-friendly)
- **Smooth Animations** — Breathing catui loader
- **Intuitive Navigation** — Vim-like keybindings, fuzzy search
- **Real-time Streaming** — Watch the AI think in real-time
### 🔌 MCP Protocol Support
Extend with the Model Context Protocol.
Built-in tools include:
- 📁 Filesystem operations
- 🌐 HTTP requests (Fetch)
- 🎭 Browser automation (Puppeteer)
- 🗄️ Database queries (SQLite)
- 🔧 Git operations
### 🌐 Multi-Model Support
Use the best model for each task.
- 🇨🇳 **Alibaba DashScope / Token Plan** — Qwen, GLM, MiniMax, DeepSeek text models
- 🤖 **OpenAI** — GPT-4, GPT-3.5
- 💬 **Anthropic** — Claude 3 Opus/Sonnet/Haiku
- 🔍 **Google** — Gemini Pro/Ultra
- 🏠 **Local** — Ollama (Qwen, Llama, Mistral, etc.)
---
## 🚀 Quick Start
### Installation
```bash
npm install -g catui-agent
```
### First Run
```bash
catui
```
1. **Select your model** — Choose from available providers
2. **Enter API key** — Securely stored in `~/.catui/agents/default/auth.json`
3. **Start coding** — Just type what you want to build
### Example Session
```
You: Create a JWT authentication middleware for Express
AI: [Analyzing project structure...]
[Creating auth.middleware.ts...]
[Adding TypeScript types...]
[Writing tests...]
✅ Done! Created:
- src/middleware/auth.middleware.ts
- src/types/auth.d.ts
- tests/auth.middleware.test.ts
Features:
• JWT verification with RS256
• Refresh token rotation
• Role-based access control
• Rate limiting integration
```
---
## 🎮 Usage
### Interactive Mode
```bash
catui # Start new session
catui -c # Continue last session
catui -r # Resume from history
catui -m qwen-max # Use specific model
```
### Print Mode (Scripts)
```bash
# Single query
catui -p "Refactor this to use async/await"
# Pipe input
cat bug-report.md | catui -p "Analyze this bug"
# Chain commands
catui -p "Generate API" | catui -p "Write tests for it"
```
### Slash Commands
| Command | Description |
|---------|-------------|
| `/model` | Switch AI model |
| `/thinking` | Adjust reasoning depth |
| `/fork` | Branch conversation |
| `/tree` | Browse session history |
| `/memory` | View project memories |
| `/soul` | Check AI personality |
| `/settings` | Configure preferences |
| `/export` | Save as HTML |
---
## 📊 Comparison
| Feature | Catui | Cursor | Claude Code | Aider |
|---------|:----------:|:------:|:-----------:|:-----:|
| Terminal Native | ✅ | ❌ | ✅ | ✅ |
| Persistent Memory | ✅ | ❌ | ❌ | ❌ |
| AI Personality | ✅ | ❌ | ❌ | ❌ |
| Session Branching | ✅ | ✅ | ✅ | ❌ |
| Multi-Model | ✅ | ✅ | ❌ | ✅ |
| MCP Support | ✅ | ❌ | ✅ | ❌ |
| Offline Mode | ✅ | ❌ | ❌ | ✅ |
| Chinese Optimized | ✅ | ❌ | ❌ | ❌ |
---
## 🏗️ Architecture Philosophy
Catui is built on three pillars:
```
┌─────────────────────────────────────────┐
│ 🧠 COGNITIVE LAYER │
│ (Memory + Personality + Context) │
├─────────────────────────────────────────┤
│ 🔧 TOOL LAYER │
│ (File Ops + Bash + Search + MCP) │
├─────────────────────────────────────────┤
│ 🎨 INTERFACE LAYER │
│ (TUI + Themes + Keybindings) │
└─────────────────────────────────────────┘
```
**Design Principles:**
- **Terminal First** — No Electron, no browser, pure terminal
- **Privacy First** — Local storage by default; opt-in diagnostics/eval telemetry only when explicitly configured
- **Extensible** — Plugin system for tools, themes, and behaviors
- **Fast** — Sub-second startup, instant response
---
## 📚 Documentation
- [Installation Guide](docs/INSTALL.md)
- [Configuration](docs/CONFIG.md)
- [Memory System](docs/记忆系统.md)
- [MCP Guide](docs/MCP集成指南.md)
- [Keybindings](docs/KEYBINDINGS.md)
- [Extensions](docs/EXTENSIONS.md)
---
## 🌍 Community
- 💬 [Discussions](https://github.com/catui-agent/catui-agent/discussions)
- 🐛 [Issues](https://github.com/catui-agent/catui-agent/issues)
- 📝 [Changelog](CHANGELOG.md)
---
## 📄 License
MIT © [Catui Agent](https://github.com/catui-agent)
---
