English | 简体中文

---

AISH

Empower the Shell to think. Evolve Operations.

A Real AI Shell: Complete PTY + Configurable Security & Risk Control

---

Table of Contents

• Why Choose AISH
• Quick Start
• Installation
• Uninstallation
• Configuration
• Usage
• Security & Risk Control
• Skills (Plugins)
• Data & Privacy
• Documentation
• Community & Support
• Development & Testing
• Contributing
• 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)

curl -fsSL https://www.aishell.ai/repo/install.sh | bash

Option 2: Manual bundle install

Download the matching aish-<version>-linux-<arch>.tar.gz bundle from the official release directory, then run:

tar -xzf aish-<version>-linux-<arch>.tar.gz
cd aish-<version>-linux-<arch>
sudo ./install.sh

Then launch:

aish

Note: aish without subcommands is equivalent to aish run.

2) Use Like a Regular Shell

aish> ls -la
aish> cd /etc
aish> vim hosts

3) Let AI Do the Work (Start with ;)

Starting with ; or ； enters AI mode:

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

curl -fsSL https://www.aishell.ai/repo/install.sh | bash

The installer resolves the latest release directory under https://www.aishell.ai/repo, downloads the matching bundle for your architecture, and installs aish, aish-sandbox, and aish-uninstall into /usr/local/bin.

Run from Source (Development/Trial)

uv sync
uv run aish
# or
python -m aish

---

Uninstallation

Uninstall (keep configuration files):

sudo aish-uninstall

Complete uninstallation (also removes system-level security policies):

sudo aish-uninstall --purge-config

Optional: Clean user-level configuration (will clear model/API keys etc.):

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

# ~/.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):

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):

aish setup

Tool calling compatibility check (confirm selected model/channel supports tool calling):

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:

enable_langfuse: true

2. Set environment variables:

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)

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:

global:
  enable_sandbox: true

2. Start privileged sandbox service (systemd):

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/

Packaged versions will attempt to copy system-level skills to user directory on first launch (e.g., /usr/share/aish/skills).

For more details, see: docs/skills-guide.md

---

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
• Skills Usage: docs/skills-guide.md
• Command Correction Mechanism: docs/command-interaction-correction.md

---

Community & Support

Link	Description
Official Website	Project homepage and more information
GitHub Repository	Source code and issue tracking
GitHub Issues	Bug reports
GitHub Discussions	Community discussions
Discord	Join the community

---

Development & Testing

uv sync
uv run aish
uv run pytest

---

Contributing

See CONTRIBUTING.md for guidelines.

License

LICENSE (Apache 2.0)