Content
# MewCode
> A coding cat, your terminal AI programming assistant 🐱
MewCode is an AI programming assistant that runs in the terminal, supporting multiple LLM providers, MCP protocol, sub-agent scheduling, and agent team collaboration. Inspired by Claude Code, built with Python + Textual for TUI interaction.
## Features
- **Multi-provider support** — Anthropic, OpenAI, and OpenAI-compatible protocols are all supported, with multi-model hot switching
- **Terminal graphical interface** — TUI based on the Textual framework, supporting mouse/keyboard operations, command completion, and file `@` reference
- **Permission control** — Four permission modes: `default`, `accept-edits`, `plan`, and `bypass`
- **Slash commands** — Built-in `/help`, `/compact`, `/clear`, `/plan`, `/session`, `/memory`, `/mcp`, `/status`, `/rewind`, `/permission`, `/tasks`, `/trace`, `/worktree`, `/skill`, and `/review` commands
- **MCP protocol** — Complete support for the Model Context Protocol, allowing access to external tool servers
- **Skill system** — Built-in `commit`, `review`, `test`, and `backend-interview` skill packages, supporting custom extensions
- **Sub-agents** — Built-in Explore, Plan, General-purpose, and Verification sub-agents
- **Agent teams** — Supporting Coordinator mode, Leader Agent can create multiple Teammate and collaborate in parallel
- **Git Worktree** — Integrated Git Worktree management, sub-agents can work in isolated worktrees
- **Session management** — Session persistence, recovery, summary generation, and conversation rewind
- **Context compression** — Automatic compression of super-long conversations, breaking through context window limitations
- **Memory system** — User memory, project memory, and feedback memory, persisting across sessions
- **Prompt caching** — Automatic prompt caching under the Anthropic protocol, reducing costs
- **Hook system** — Supporting `startup` and `shutdown` lifecycle hooks
- **Non-interactive mode** — Directly executing prompts and outputting results through the `-p` parameter, suitable for script/CI scenarios
## Requirements
- Python >= 3.11
- At least one LLM API Key (Anthropic or OpenAI)
## Quick Start
```bash
git clone <repo-url> mewcode && cd mewcode && uv sync && uv run mewcode
```
## Installation
```bash
# Clone the project
git clone <repo-url> mewcode
cd mewcode
# Install dependencies (project uses uv management)
uv sync
```
## Configuration
MewCode is configured through YAML files, with loading priorities from low to high (the latter overrides the former):
1. `~/.mewcode/config.yaml` — User-level global configuration
2. `.mewcode/config.yaml` — Project-level configuration
3. `.mewcode/config.local.yaml` — Local override (recommended to add to .gitignore)
### Minimal Configuration
```yaml
providers:
- name: anthropic
protocol: anthropic
base_url: https://api.anthropic.com
model: claude-sonnet-4-6
api_key: ${ANTHROPIC_API_KEY}
permission_mode: default
```
### Complete Configuration Example
```yaml
# Multiple providers can be configured, select one at startup
providers:
- name: anthropic
protocol: anthropic
base_url: https://api.anthropic.com
model: claude-sonnet-4-6
api_key: ${ANTHROPIC_API_KEY}
thinking: true # Enable extended thinking
context_window: 0 # 0=auto detect (recommended), or manually specify
max_output_tokens: 8192
- name: openai
protocol: openai
base_url: https://api.openai.com/v1
model: gpt-4o
api_key: ${OPENAI_API_KEY}
# Permission mode: default | accept-edits | plan | bypass
permission_mode: default
# MCP tool server (optional)
mcp_servers:
- name: filesystem
command: npx
args: ["-y", "@anthropic-ai/mcp-server-filesystem", "/path/to/allowed"]
- name: github
url: https://api.github.com/mcp
headers:
Authorization: Bearer ${GITHUB_TOKEN}
# Git Worktree configuration
worktree:
symlink_directories:
- node_modules
- .venv
- vendor
stale_cleanup_interval: 3600 # seconds
stale_cutoff_hours: 24
# Agent team mode
teammate_mode: "" # empty string = default, "in-process" = in-process collaboration
enable_coordinator_mode: false # whether to enable coordinator mode
# Feature switches
enable_fork: false # whether to allow fork conversation
enable_verification_agent: true # whether to enable verification agent
# Lifecycle hooks
hooks:
- event: startup
command: echo "MewCode started"
- event: shutdown
command: echo "MewCode stopped"
```
### API Key
The `api_key` in the configuration supports the `${ENV_VAR}` syntax to reference environment variables. Environment variable mapping:
| Protocol | Environment Variable |
|----------|----------------------|
| `anthropic` | `ANTHROPIC_API_KEY` |
| `openai` | `OPENAI_API_KEY` |
| `openai-compat` | `OPENAI_API_KEY` |
## Usage
```bash
# Interactive mode (TUI)
uv run mewcode
# Non-interactive mode: execute a single prompt and output the result
uv run mewcode -p "Explain the architecture of this project"
# Specify permission mode
uv run mewcode --mode plan
uv run mewcode --mode bypass
```
### Shortcuts
| Shortcut | Function |
|----------|----------|
| `Enter` | Send message |
| `Shift+Enter` / `Ctrl+J` | New line |
| `Tab` | Command/file completion |
| `Shift+Tab` | Switch permission mode |
| `Ctrl+O` | Expand/collapse tool call details |
| `Esc` | Cancel current operation |
| `Ctrl+C` | Exit program |
| `Up` / `Down` | Browse history/completion menu |
### Slash Commands
| Command | Alias | Description |
|----------|--------|----------|
| `/help` | `/h`, `/?` | Display help information |
| `/clear` | | Clear conversation history |
| `/compact` | `/c` | Compress context |
| `/plan` | `/p` | Switch to Plan mode |
| `/session` | | Session management (list/recover/delete) |
| `/memory` | | Memory management |
| `/mcp` | | View MCP server status |
| `/permission` | | Permission rule management |
| `/status` | `/s` | Display current status |
| `/rewind` | | Rewind to previous conversation node |
| `/tasks` | `/task` | View/cancel background tasks |
| `/trace` | `/tree` | View agent parent-child tracking tree |
| `/worktree` | `/wt` | Git Worktree management |
| `/skill` | `/skills` | Skill package management |
| `/review` | | Review code changes |
### File @ Reference
In the input box, type `@` to quickly reference project files, supporting automatic completion.
```
Help me refactor the class in @app.py
```
## Project Structure
```
mewcode/
├── pyproject.toml # Project metadata and dependencies
├── uv.lock # Dependency lock file
├── mewcode/
│ ├── __main__.py # Entry point: parameter parsing and startup
│ ├── app.py # TUI main application (Textual App)
│ ├── agent.py # Core agent engine
│ ├── client.py # LLM client (Anthropic/OpenAI)
│ ├── config.py # Configuration loading and model
│ ├── conversation.py # Conversation manager
│ ├── prompts.py # System prompt construction
│ ├── serialization.py # Message serialization
│ ├── validator.py # Configuration validation
│ ├── cache.py # File cache
│ ├── driver.py # Textual driver
│ ├── teammate_tree.py # Teammate tree UI component
│ ├── styles.tcss # TUI style sheet
│ ├── agents/ # Sub-agent system
│ │ ├── loader.py # Agent loader
│ │ ├── task_manager.py # Background task manager
│ │ ├── trace.py # Agent tracking tree
│ │ └── builtins/ # Built-in agent definitions
│ ├── commands/ # Slash command system
│ │ ├── registry.py # Command registry
│ │ ├── completion.py # Command completion
│ │ └── handlers/ # Command handlers
│ ├── context/ # Context window management
│ ├── hooks/ # Hook engine
│ ├── mcp/ # MCP protocol support
│ ├── memory/ # Memory system
│ ├── permissions/ # Permission system
│ ├── skills/ # Skill system
│ │ ├── loader.py # Skill loader
│ │ ├── executor.py # Skill executor
│ │ └── builtins/ # Built-in skill packages
│ ├── teams/ # Agent team collaboration
│ ├── tools/ # Tool system
│ │ ├── agent_tool.py # Sub-agent tool call
│ │ ├── team_create.py # Team creation tool
│ │ └── ... # Other built-in tools
│ └── worktree/ # Git Worktree management
└── tests/ # Tests
```
## Developers
### Run Tests
```bash
uv run pytest
```
### Tech Stack
- **TUI**: [Textual](https://textual.textualize.io/) — Python terminal UI framework
- **LLM SDK**: `anthropic` + `openai` — Dual protocol support
- **Serialization**: Pydantic — Configuration and data model validation
- **Package management**: uv + hatchling
## License
MIT
Connection Info
You Might Also Like
No recommendations available