# Xsh

**Repository Path**: js-25/xsh

## Basic Information

- **Project Name**: Xsh
- **Description**: Xsh是一个开源终端工具集，基于Zsh,专注于提升开发效率，提供简洁高效的命令行与脚本解决方案，助力开发者快速构建与调试。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-15
- **Last Updated**: 2026-08-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Xsh — A Custom Zsh Distribution with AI Integration

Xsh is a fork of [Zsh](https://www.zsh.org/) (Z shell) with built-in AI-powered features: **AI command completion**, **syntax highlighting**, and **inline AI chat**. It is built on top of the standard Zsh source code with all custom code isolated in the `custom/` directory, making it easy to rebase on upstream updates.

---

## Features

### 1. AI-Powered Command Completion (Ctrl+V)
- Press **Ctrl+V** to request AI completion based on your current input
- View the suggestion in the message line
- Press **→** (Right Arrow) to accept the suggestion
- Press **Esc** to cancel
- AI model configuration is stored in `~/.ai.json`, API Key and Base URL are read from environment variables (`AI_API_KEY`, `AI_BASE_URL`)
- The AI uses all available system commands and your input context as reference

### 2. AI Chat GUI (Ctrl+I)
- Press **Ctrl+I** to open a floating GUI chat window
- Chat with AI directly from your terminal
- Enter to send message, **Ctrl+Enter** for newline
- Model configuration is shared with AI completion
- AI can **read terminal content** (current directory, environment, recent commands) and **execute commands** on your behalf
- Supports web search via user-provided API key

### 3. Syntax Highlighting
Real-time syntax highlighting as you type:

| Element | Color |
|---|---|
| Commands / Functions | Light Yellow |
| Programs (executables) | Gold |
| Non-existent commands | Red |
| Files / Directories | Green |
| Options (flags) | Dark Blue |
| Keywords (if, for, while, etc.) | Purple |
| Default text | Light Blue |

### 4. Custom Prompt
- **Prompt format**: `Xsh: (current_directory) >`
- **Xsh:** in blue, `(path) >` in orange-yellow
- Displays Git branch, dirty status (`*`), and upstream sync (`↑`/`↓`) before the prompt

### 5. OpenFool — Configuration Manager
A CLI tool (`openfool`, shortcut `opfo`) for managing Xsh configuration:
- **Plugin management** — install/remove/update/downgrade Zsh plugins via Git
- **Alias management** — add/remove/list aliases
- **Backup & restore** — create, list, restore, and diff backups
- **Module management** — enable/disable AI completion, AI chat, syntax highlighting
- **Theme management** — set/list/preview prompt themes
- **PATH management** — add/remove/list custom PATH entries
- **Diagnostics** — doctor checks, startup profiling, config cleanup
- **Templates** — save/apply configuration templates
- **Setup wizard** — interactive guided configuration

---

## Build & Install

### Prerequisites

Standard Zsh build dependencies:
- C compiler (GCC, Clang)
- autoconf / automake
- ncurses development libraries
- make

For AI features (Rust binaries):
- Rust toolchain (cargo, rustc)

### Quick Build

```bash
# 1. Generate configure script
./Util/preconfig

# 2. Configure with Xsh custom features
./configure --enable-custom-prompt

# 3. Build Rust AI components (optional, for AI features)
cd custom/ai-complete && cargo build --release && cd ../..
cd custom/ai-chat && cargo build --release && cd ../..

# 4. Build Xsh
make -j$(nproc)

# 5. Install
make install
```

### Configure Options

| Option | Description |
|---|---|
| `--enable-custom-prompt[=DIR]` | Enable Xsh custom features. Installs custom files to `DIR` (default: `DATADIR/zsh/custom`) |
| `--prefix=PREFIX` | Installation prefix (default: `/usr/local`) |

**Note**: `--enable-custom-prompt` is required to enable the Xsh prompt, AI completion, AI chat, and syntax highlighting. Without this flag, Xsh behaves like a standard Zsh.

### Installation Paths

| Component | Default Path |
|---|---|
| Binary | `PREFIX/bin/xsh` |
| Custom files | `PREFIX/share/zsh/custom/` |
| AI complete binary | `PREFIX/share/zsh/custom/ai-complete/target/release/ai-complete` |
| AI chat binary | `PREFIX/share/zsh/custom/ai-chat/target/release/ai-chat` |

---

## Configuration

### AI Model Configuration

Create `~/.ai.json` with your model settings:

```json
{
  "model": "gpt-4o"
}
```

Set environment variables:

```bash
export AI_API_KEY="your-api-key"
export AI_BASE_URL="https://api.openai.com/v1"  # Optional, defaults to OpenAI
export AI_SEARCH_API_KEY="your-search-api-key"   # Optional, for web search
```

`AI_BASE_URL` supports any OpenAI-compatible API endpoint, so you can use:
- OpenAI
- Azure OpenAI
- Local models (e.g., Ollama, vLLM, LM Studio)
- Any OpenAI-compatible proxy

---

## Usage

### Start Xsh

```bash
xsh
```

### Key Bindings

| Key | Feature |
|---|---|
| **Ctrl+V** | Request AI completion |
| **→** (Right Arrow) | Accept AI suggestion |
| **Esc** | Cancel AI suggestion |
| **Ctrl+I** | Open AI Chat GUI (overrides Tab) |
| **Ctrl+Enter** | Newline in AI Chat |

### AI Chat Capabilities

The AI chat can:
1. **Read terminal context** — current directory, recent command history, environment
2. **Execute commands** — the AI can run shell commands and show you the output
3. **Search the web** — if `AI_SEARCH_API_KEY` is configured

---

## OpenFool Configuration Manager

OpenFool is a CLI tool for managing Xsh configuration. It provides plugin management, alias management, backup/restore, theme switching, and more.

### Installation

```bash
# Build OpenFool
cd custom/openfool
go build -o openfool

# Add to PATH
export PATH="$(pwd):$PATH"

# Set up alias (optional)
alias opfo='openfool'
```

### Quick Start

```bash
# Initialize configuration
openfool init

# Install a plugin
openfool git clone https://github.com/zsh-users/zsh-autosuggestions

# Add an alias
openfool alias add ll 'ls -la'

# View help
openfool help
```

### Command Reference

#### Basic Commands

| Command | Description |
|---------|-------------|
| `init` | Initialize clean .zshrc |
| `import [shell] [file]` | Import configuration from another shell |
| `setup` | Interactive setup wizard |

#### Plugin Management

| Command | Description |
|---------|-------------|
| `git clone <repo-url>` | Install plugin from Git repository |
| `rm <plugin-name>` | Remove plugin |
| `up <plugin-name>` | Update plugin |
| `du <plugin-name>` | Downgrade plugin |
| `list` | List installed plugins |

#### Alias Management

| Command | Description |
|---------|-------------|
| `alias add <name> <command>` | Add alias |
| `alias remove <name>` | Remove alias |
| `alias list` | List all aliases |

#### Backup & Restore

| Command | Description |
|---------|-------------|
| `backup create [name]` | Create backup |
| `backup list` | List all backups |
| `restore <name>` | Restore from backup |
| `diff <name>` | Show differences |

#### Module Management

| Command | Description |
|---------|-------------|
| `module enable <name>` | Enable module |
| `module disable <name>` | Disable module |
| `module list` | List enabled modules |

Supported modules:
- `ai-complete` — AI completion
- `ai-chat` — AI chat
- `syntax-highlighting` — Syntax highlighting

#### Theme Management

| Command | Description |
|---------|-------------|
| `theme set <name>` | Apply theme |
| `theme list` | List available themes |
| `theme preview <name>` | Preview theme |

#### PATH Management

| Command | Description |
|---------|-------------|
| `path add <directory>` | Add directory to PATH |
| `path remove <directory>` | Remove directory from PATH |
| `path list` | List custom PATH entries |

#### Diagnostics

| Command | Description |
|---------|-------------|
| `doctor` | Check for configuration issues |
| `profile` | Profile shell startup time |
| `clean` | Clean unused configuration |

#### Template Management

| Command | Description |
|---------|-------------|
| `template use <name>` | Apply template |
| `template create <name>` | Create template from current config |
| `template list` | List available templates |

### Usage Examples

#### Installing Plugins

```bash
# Install zsh-autosuggestions
openfool git clone https://github.com/zsh-users/zsh-autosuggestions

# Or use the shortcut
opfo git clone https://github.com/zsh-users/zsh-syntax-highlighting
```

#### Managing Aliases

```bash
# Add aliases
openfool alias add gs 'git status'
openfool alias add gc 'git commit'

# List all aliases
openfool alias list

# Remove an alias
openfool alias remove gs
```

#### Backup & Restore

```bash
# Create a backup
openfool backup create myconfig

# List backups
openfool backup list

# Restore a backup
openfool restore myconfig

# View differences
openfool diff myconfig
```

#### Enabling Modules

```bash
# Enable AI completion
openfool module enable ai-complete

# Enable syntax highlighting
openfool module enable syntax-highlighting

# List enabled modules
openfool module list
```

#### Diagnostics & Optimization

```bash
# Check for configuration issues
openfool doctor

# Profile startup time
openfool profile

# Clean unused configuration
openfool clean
```

### Directory Structure

```
~/.xsh/
├── plugins/          # Plugin directory
├── themes/           # Theme directory
├── templates/        # Template directory
└── backups/          # Backup directory
```

### Configuration Import

OpenFool supports importing configuration from:
- bash
- fish
- csh/tcsh
- ksh

```bash
# Import from bash
openfool import bash ~/.bashrc

# Import from fish
openfool import fish ~/.config/fish/config.fish
```

### Notes

1. Run `openfool init` to initialize configuration before first use
2. Plugins are automatically added to `.zshrc` and cleaned up when removed
3. Restart your shell or run `source ~/.zshrc` after making changes
4. The backup feature automatically saves previous configurations
5. Use the `opfo` alias to simplify command input

---

## Project Structure

```
zsh/                    # Zsh source tree (upstream)
├── custom/             # Custom Xsh code (isolated from upstream)
│   ├── zshrc           # Global zshrc with Xsh prompt
│   ├── ai-complete.zsh # Zsh integration for AI completion
│   ├── ai-complete/    # Rust AI completion binary
│   │   └── src/
│   │       └── main.rs
│   ├── ai-chat.zsh     # Zsh integration for AI chat
│   ├── ai-chat/        # Rust AI chat GUI binary (egui/eframe)
│   │   └── src/
│   │       └── main.rs
│   └── zsh-syntax-highlighting.zsh  # Pure Zsh syntax highlighter
├── Src/
│   └── xsh             # Compiled binary
└── Doc/
    └── ...
```

All custom code is in the `custom/` directory. This design minimizes merge conflicts when rebasing on upstream Zsh releases.

---

## Uninstall

```bash
make uninstall
```

Or manually:

```bash
rm -f /usr/local/bin/xsh
rm -rf /usr/local/share/zsh/custom
```

---

## License

Xsh inherits Zsh's license. See [LICENSE](LICENSE) for details.

Zsh is distributed under a standard BSD-like license. For more information, see the Zsh web site at [https://www.zsh.org/](https://www.zsh.org/).