AISH for macOS

Empower the Shell to think. Evolve Operations.

本仓库基于 AI-Shell-Team/aish 原始项目适配 macOS 平台而来。 macOS 适配的详细说明请参阅 docs/macOS_ADAPTATION.md。

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

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: Install from Source (Recommended)

# 克隆仓库
git clone git@github.com:Developer-cy/aish-mac.git
cd aish-mac

# 安装 Rust 工具链（如已安装可跳过）
brew install rustup
export PATH="/opt/homebrew/opt/rustup/bin:$PATH"

# 编译 Release 版
cargo build --release -p aish-cli

# 安装到 PATH
cp target/release/aish ~/.local/bin/aish
chmod +x ~/.local/bin/aish

Option 2: Direct Run (Development)

cargo run --bin aish

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

Install from Source (macOS)

# 克隆仓库
git clone git@github.com:Developer-cy/aish-mac.git
cd aish-mac

# 编译 Release 版
cargo build --release -p aish-cli

# 安装到 PATH（~/.local/bin 默认已在 PATH 中）
cp target/release/aish ~/.local/bin/aish
chmod +x ~/.local/bin/aish

Run from Source (Development/Trial)

cargo run --bin aish

Uninstallation

Remove the binary:

rm ~/.local/bin/aish

Optional: Clean configuration files (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)

Command-line arguments
Environment variables
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):

Enable in configuration:

enable_langfuse: true

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:

~/.config/aish/security_policy.yaml (user-level; auto-generated template if not exists)

Sandbox Pre-run (Optional, Linux Only)

Default policy has sandbox pre-run disabled. The sandbox uses Linux mount namespace isolation (unshare(CLONE_NEWNS)) and is not available on macOS.

On macOS, the sandbox will return SandboxUnavailable and agent interactions will fall back to policy rule evaluation (sandbox_off_action: BLOCK/CONFIRM/ALLOW). Security assessment still works via glob-matched policy rules.

To enable on Linux:

Set in security policy:

global:
  enable_sandbox: true

Start privileged sandbox service (systemd):

sudo systemctl enable --now aish-sandbox.socket

Default socket: /run/aish/sandbox.sock.

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
macOS Adaptation Guide: docs/macOS_ADAPTATION.md
Command Correction Mechanism: docs/command-interaction-correction.md

Community & Support

Link	Description
Official Website	Project homepage and more information
GitHub Repository	macOS adaptation source code
Original Repository	Original Linux project
GitHub Issues	Bug reports
Discord	Join the community

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 the Rust implementation of aish, adapted for macOS. The original project is AI-Shell-Team/aish.

# Build (Release)
cargo build --release -p aish-cli

# Run Rust tests
cargo test --workspace

# Lint Rust code
cargo clippy --all-targets -- -D warnings

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 for guidelines.

License

LICENSE (Apache 2.0)

Navigation Menu

Repository navigation

README.md

README.md

AISH for macOS

Table of Contents

Why Choose AISH

Feature Comparison

Quick Start

1) Install and Launch

Option 1: Install from Source (Recommended)

Option 2: Direct Run (Development)

2) Use Like a Regular Shell

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

Installation

Install from Source (macOS)

Run from Source (Development/Trial)

Uninstallation

Configuration

Configuration File Location

Priority (High to Low)

Minimal Configuration Example

Usage

Common Input Types

Shell Compatibility (PTY)

Security & Risk Control

Risk Levels

Security Policy File Path

Sandbox Pre-run (Optional, Linux Only)

Skills (Plugins)

Data & Privacy

Documentation

Community & Support

Development & Testing

Architecture (14 crates)

Contributing

See CONTRIBUTING.md for guidelines.

License

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

AISH for macOS

Table of Contents

Why Choose AISH

Feature Comparison

Quick Start

1) Install and Launch

Option 1: Install from Source (Recommended)

Option 2: Direct Run (Development)

2) Use Like a Regular Shell

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

Installation

Install from Source (macOS)

Run from Source (Development/Trial)

Uninstallation

Configuration

Configuration File Location

Priority (High to Low)

Minimal Configuration Example

Usage

Common Input Types

Shell Compatibility (PTY)

Security & Risk Control

Risk Levels

Security Policy File Path

Sandbox Pre-run (Optional, Linux Only)

Skills (Plugins)

Data & Privacy

Documentation

Community & Support

Development & Testing

Architecture (14 crates)

Contributing

See CONTRIBUTING.md for guidelines.

License