English | [įŽäŊä¸æ](README_CN.md)
---
# AISH
Empower the Shell to think. Evolve Operations.
[](https://www.aishell.ai)
[](https://github.com/AI-Shell-Team/aish/)
[](https://www.rust-lang.org/)
[](#)
[](LICENSE)
**A Real AI Shell: Complete PTY + Configurable Security & Risk Control**
---
## Table of Contents
- [Why Choose AISH](#why-choose-aish)
- [Quick Start](#quick-start)
- [Installation](#installation)
- [Uninstallation](#uninstallation)
- [Configuration](#configuration)
- [Usage](#usage)
- [Security & Risk Control](#security--risk-control)
- [Skills (Plugins)](#skills-plugins)
- [Data & Privacy](#data--privacy)
- [Documentation](#documentation)
- [Community & Support](#community--support)
- [Development & Testing](#development--testing)
- [Contributing](#contributing)
- [License](#license)
---
## Why Choose AISH
- **True Interactive Shell**: Full PTY support, runs interactive programs like `vim` / `ssh` / `top`
- **AI Native Integration**: Describe tasks in natural language, generate, explain and execute commands
- **Secure & Controllable**: AI commands have risk grading and confirmation flow; optional sandbox pre-run for change assessment
- **Extensible**: Skills plugin system with hot loading and priority override
- **Low Migration Cost**: Compatible with regular commands and workflows, everything in terminal by default
---
## Feature Comparison
| Feature | AISH | Claude Code |
|---------|------|-------------|
| đ¯ **Core Positioning** | Ops/System Troubleshooting CLI | Development Coding Assistant |
| đ¤ **Multi-Model Support** | â
Fully Open | â ī¸ Mainly Claude |
| đ§ **Sub-Agent System** | â
ReAct Diagnostic Agent | â
Multiple Agent Types |
| 𧊠**Skills Support** | â
Hot Loading | â
|
| đĨī¸ **Native Terminal Integration** | â
Full PTY Support | â ī¸ Limited Support |
| đĄī¸ **Security Risk Assessment** | â
Security Confirmation | â
Security Confirmation |
| đ **Local Model Support** | â
Fully Supported | Fully Supported |
| đ **File Operation Tools** | â
Minimal Essential Suppport | â
Full Support |
| đ° **Completely Free** | â
Open Source | â Paid Service |
| đ **Observability** | â
Langfuse Optional | â ī¸ Built-in |
| đ **Multi-language Output** | â
Auto Detection | â
|
---
## Quick Start
### 1) Install and Launch
#### Option 1: One-line install (Recommended)
```bash
curl -fsSL https://www.aishell.ai/repo/install.sh | bash
```
#### Option 2: Manual bundle install
Download the matching `aish--linux-.tar.gz` bundle from the official release directory, then run:
```bash
tar -xzf aish--linux-.tar.gz
cd aish--linux-
sudo ./install.sh
```
Then launch:
```bash
aish
```
Note: `aish` without subcommands is equivalent to `aish run`.
### 2) Use Like a Regular Shell
```bash
aish> ls -la
aish> cd /etc
aish> vim hosts
```
### 3) Let AI Do the Work (Start with ;)
Starting with `;` or `īŧ` enters AI mode:
```bash
aish> ;find files larger than 100M in current directory and sort by size
aish> ;explain this command: tar -czf a.tgz ./dir
```
---
## Installation
### Linux Release Bundle
```bash
curl -fsSL https://www.aishell.ai/repo/install.sh | bash
```
The installer resolves the latest stable version, downloads the matching bundle for your architecture, and installs `aish`, `aish-sandbox`, and `aish-uninstall` into `/usr/local/bin`.
### Run from Source (Development/Trial)
```bash
cargo run --bin aish
```
---
## Uninstallation
Uninstall (keep configuration files):
```bash
sudo aish-uninstall
```
Complete uninstallation (also removes system-level security policies):
```bash
sudo aish-uninstall --purge-config
```
Optional: Clean user-level configuration (will clear model/API keys etc.):
```bash
rm -rf ~/.config/aish
```
---
## Configuration
### Configuration File Location
- Default: `~/.config/aish/config.yaml` (or `$XDG_CONFIG_HOME/aish/config.yaml` if `XDG_CONFIG_HOME` is set)
### Priority (High to Low)
1. Command-line arguments
2. Environment variables
3. Configuration file
### Minimal Configuration Example
```yaml
# ~/.config/aish/config.yaml
model: openai/deepseek-chat
api_base: https://openrouter.ai/api/v1
api_key: your_api_key
```
Alternatively via environment variables (more suitable for secrets):
```bash
export AISH_MODEL="openai/deepseek-chat"
export AISH_API_BASE="https://openrouter.ai/api/v1"
export AISH_API_KEY="your_api_key"
```
> Tip: LiteLLM also supports reading vendor-specific environment variables (e.g., `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`).
Interactive configuration (optional):
```bash
aish setup
```
Tool calling compatibility check (confirm selected model/channel supports tool calling):
```bash
aish check-tool-support --model openai/deepseek-chat --api-base https://openrouter.ai/api/v1 --api-key your_api_key
```
Langfuse (optional observability):
1) Enable in configuration:
```yaml
enable_langfuse: true
```
2) Set environment variables:
```bash
export LANGFUSE_PUBLIC_KEY="..."
export LANGFUSE_SECRET_KEY="..."
export LANGFUSE_HOST="https://cloud.langfuse.com"
```
`aish check-langfuse` will run checks when `check_langfuse.py` exists in project root.
---
## Usage
### Common Input Types
| Type | Example | Description |
|:----:|---------|-------------|
| Shell Commands | `ls -la`, `cd /path`, `git status` | Execute regular commands directly |
| AI Requests | `;how to check port usage`, `;find files larger than 100M` | Enter AI mode with `;`/`īŧ` prefix |
| Built-in Commands | `help`, `clear`, `exit`, `quit` | Shell built-in control commands |
| Model Switching | `/model gpt-4` | View or switch model |
### Shell Compatibility (PTY)
```bash
aish> ssh user@host
aish> top
aish> vim /etc/hosts
```
---
## Security & Risk Control
AI Shell only performs security assessment on **AI-generated and ready-to-execute** commands.
### Risk Levels
- **LOW**: Allowed by default
- **MEDIUM**: Confirmation before execution
- **HIGH**: Blocked by default
### Security Policy File Path
Policy files are resolved in this order:
1. `/etc/aish/security_policy.yaml` (system-level)
2. `~/.config/aish/security_policy.yaml` (user-level; auto-generated template if not exists)
### Sandbox Pre-run (Optional, Recommended for Production)
Default policy has sandbox pre-run **disabled**. To enable:
1) Set in security policy:
```yaml
global:
enable_sandbox: true
```
2) Start privileged sandbox service (systemd):
```bash
sudo systemctl enable --now aish-sandbox.socket
```
Default socket: `/run/aish/sandbox.sock`.
When sandbox is unavailable, it will fallback according to `sandbox_off_action` (BLOCK/CONFIRM/ALLOW) in policy.
---
## Skills (Plugins)
Skills extend AI's domain knowledge and workflows, supporting hot loading and priority override.
Default scan directories and priority:
- `~/.config/aish/skills/` (or `$AISH_CONFIG_DIR/skills`)
- `~/.claude/skills/`
---
## Data & Privacy
This project stores the following data locally (for troubleshooting and traceability):
- **Logs**: Default `~/.config/aish/logs/aish.log`
- **Sessions/History**: Default `~/.local/share/aish/sessions.db` (SQLite)
- **Large Output Offload**: Default `~/.local/share/aish/offload/`
Recommendations:
- Don't commit real API keys to repository; prefer environment variables or secret management systems.
- Production environments can combine security policies to limit AI-accessible directory scope.
---
## Documentation
- Configuration Guide: `CONFIGURATION.md`
- Quick Start: `QUICKSTART.md`
- Command Correction Mechanism: `docs/command-interaction-correction.md`
---
## Community & Support
| Link | Description |
|------|-------------|
| [Official Website](https://www.aishell.ai) | Project homepage and more information |
| [GitHub Repository](https://github.com/AI-Shell-Team/aish/) | Source code and issue tracking |
| [GitHub Issues](https://github.com/AI-Shell-Team/aish/issues) | Bug reports |
| [GitHub Discussions](https://github.com/AI-Shell-Team/aish/discussions) | Community discussions |
| [Discord](https://discord.com/invite/Pw2mjZt3) | Join the community |
| [LINUX DO](https://linux.do) | Community friend link |
> If you find AISH helpful, please consider giving us a Star â
>It helps more people discover the project and keeps us motivated to continue improving it.
---
## Development & Testing
This repository is now the Rust implementation of aish. The remaining Python scripts under `packaging/scripts/` are release automation helpers and are covered by shell smoke tests.
```bash
# Build
cargo build --release
# Run Rust tests
cargo test --workspace
# Lint Rust code
cargo clippy --all-targets -- -D warnings
# Run packaging release script smoke tests
./packaging/tests/release_scripts_smoke.sh
```
#### Architecture (14 crates)
| Crate | Description |
|-------|-------------|
| `aish-core` | Error types, shared enums (RiskLevel, MemoryCategory, etc.) |
| `aish-config` | YAML config loading with XDG paths and env overrides |
| `aish-i18n` | Internationalization with 6 locales and embedded fallback |
| `aish-pty` | PTY executor with fork/exec, select()-based I/O, output offload |
| `aish-llm` | OpenAI-compatible HTTP client with SSE streaming and tool calling |
| `aish-session` | SQLite session persistence with WAL mode |
| `aish-context` | Sliding-window context manager with tiktoken token counting |
| `aish-security` | Security policy engine with glob-to-regex pattern matching |
| `aish-skills` | Skill plugin discovery with hot-reload via notify |
| `aish-memory` | Markdown-based long-term memory with relevance scoring |
| `aish-tools` | Built-in tools: bash, WebFetch, fs (read/write/edit), ask_user, memory, skill |
| `aish-scripts` | .aish script system with frontmatter, ai "prompt" syntax, hooks |
| `aish-shell` | Main shell: REPL loop, AI handler, built-in commands, animation |
| `aish-cli` | CLI entry point with clap derive macros |
---
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
---
## License
`LICENSE` (Apache 2.0)