语言 / Language: 中文 | English

AIS – Context-Aware Error-Analysis Learning Assistant

<div align="center">

📖 Installation Guide · 🌏 Official Docs · 🎞️ Feature Demo (Mainland China) · ✨ Interactive Demo

</div>

Overview

Through a deep shell-integration architecture, AIS achieves multi-dimensional context awareness and intelligent error analysis. It automatically collects execution-environment information and pinpoints issues precisely; inside the terminal it provides context-based solutions and structured learning guidance. This eliminates the usual search hopping and blind trial-and-error in traditional error handling, significantly improving both problem-solving efficiency and the speed of skill accumulation.

🌟 Core Features

🔍 Intelligent Error Analysis

• Automatic detection – Automatically analyzes the cause when a command fails
• Context awareness – Combines current directory, Git status, project type, and other environment info
• Personalized suggestions – Offers targeted solutions based on the user’s skill level
• Safety levels – Every suggestion is labeled with a risk level to keep operations safe

📚 Intelligent Learning System

• Interactive teaching – Explains the “why,” not just the “how”
• Topic learning – Dive into focused topics like Git, Docker, and Vim
• Progressive content – Adjusts depth according to user level
• Practice-oriented – Provides runnable command examples and best practices

🎯 Intelligent Context Awareness

• Environment-aware Q&A – ais ask delivers precise answers based on the current system environment
• Three-level context collection – Configurable information-collection levels: minimal/standard/detailed
• System status analysis – Automatically detects hardware configuration, network status, and running services
• Project-type recognition – Intelligently identifies tech stacks using Git status and project files

🔌 Strong Integrations

• Shell integration – Automatic error capture for Bash and Zsh
• Multi-AI support – Compatible with OpenAI, Ollama, Claude, and more
• Privacy protection – Local data storage; sensitive information is automatically filtered
• Cross-platform – Supports Linux and macOS

---

<a id="installation"></a>📦 Installation

System Requirements

• Python: 3.9+ (3.11+ recommended)
• Operating Systems: Linux, macOS
• Network: Required to download dependencies and access AI services
• Disk Space: At least 100 MB free space

⚡ One-Click Install (Recommended)

# Smart install – automatically detects the environment and chooses the best method
curl -sSL https://raw.githubusercontent.com/kangvcar/ais/main/scripts/install.sh | bash

# Mainland China users can use the Gitee mirror (faster and more stable)
curl -sSL https://gitee.com/kangvcar/ais/raw/main/scripts/install.sh | bash

The install script will automatically:

• 🔍 Detect the current environment (personal/team/container)
• 🎯 Choose the best installation method (pipx per-user/system-wide/containerized)
• 📦 Install pipx and AIS
• 🔧 Configure shell integration
• ✓ Run a health check

🗑️ One-Click Uninstall

# Smart uninstall – automatically detects how AIS was installed and cleans it completely
curl -sSL https://raw.githubusercontent.com/kangvcar/ais/main/scripts/uninstall.sh | bash

# Mainland China users can use the Gitee mirror
curl -sSL https://gitee.com/kangvcar/ais/raw/main/scripts/uninstall.sh | bash

The uninstall script will automatically:

• 🔍 Detect how AIS was installed (pipx per-user/system-wide)
• 🗑️ Uninstall the AIS package and dependencies
• 🧹 Clean shell-integration configuration
• 📁 Let you choose to keep or delete user data
• ✓ Verify that uninstallation is complete

🎯 Installation by Scenario

<details> <summary><b>🐳 Docker Container (Recommended – zero configuration)</b></summary>

# Run the latest version directly
docker run -it --rm kangvcar/ais:latest

# Or use it interactively
docker run -it --rm -v $(pwd):/workspace kangvcar/ais:latest bash

# Use Docker Compose (recommended for persistent configuration)
curl -O https://raw.githubusercontent.com/kangvcar/ais/main/docker-compose.yml
docker-compose up -d ais
docker-compose exec ais bash

Advantages: Zero-config startup, environment isolation, cross-platform consistency, ARM64 supported

</details> <details> <summary><b>👨‍💻 Individual Developer (Python environment)</b></summary>

# Per-user install (safest)
curl -sSL https://raw.githubusercontent.com/kangvcar/ais/main/scripts/install.sh | bash -s -- --user

# Mainland China users can use the Gitee mirror
curl -sSL https://gitee.com/kangvcar/ais/raw/main/scripts/install.sh | bash -s -- --user

# Or install manually
pipx install ais-terminal
ais setup

# HTML report visualization is now included by default

Advantages: Maximum safety, isolated virtual environment, no sudo required

</details> <details> <summary><b>🏢 Team/Enterprise Environment</b></summary>

# System-wide installation (available to all users)
curl -sSL https://raw.githubusercontent.com/kangvcar/ais/main/scripts/install.sh | bash -s -- --system

# Mainland China users can use the Gitee mirror
curl -sSL https://gitee.com/kangvcar/ais/raw/main/scripts/install.sh | bash -s -- --system

Advantages: Available to all users, maintains safety isolation, centralized management and updates

</details> <details> <summary><b>🐳 Container/Cloud Environment</b></summary>

# Dockerized installation
curl -sSL https://raw.githubusercontent.com/kangvcar/ais/main/scripts/docker-install.sh | bash

# Or run directly
docker run -it --rm ais:latest

Advantages: Environment consistency, rapid deployment, easy scaling, full isolation

</details> <details> <summary><b>🔧 Developers/Contributors</b></summary>

# Install from source
git clone https://github.com/kangvcar/ais.git
cd ais
pipx install -e .

# Or use a virtual environment
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,html]"  # Includes dev and HTML visualization dependencies

Advantages: Live edits, complete dev toolchain, easy debugging

</details>

✓ Verify Installation

# Check version
ais --version

# Test basic functionality
ais ask "Hello, AIS!"

# Test automatic error analysis (enter a command with an intentional typo)
mkdirr /tmp/test

---

<a id="quickstart"></a>🚀 Quick Start

Basic Configuration

# View current configuration
ais config

# Set context-collection level
ais config --set context_level=detailed

Core Feature Walkthrough

💬 Environment-Aware Q&A

# Environment-aware Q&A based on the current system
ais ask "What is my system configuration like? How is the hardware performance?"
ais ask "Is my network connection normal? Any security suggestions?"
ais ask "Given my current project type, how can I optimize performance?"

# Traditional technical Q&A (still supported)
ais ask "How do I check system memory usage?"
ais ask "How do Docker containers mount directories?"
ais ask "How do I resolve Git merge conflicts?"

# Configure context-collection level
ais config --set context_level=minimal   # Basic information
ais config --set context_level=standard  # Standard information  
ais config --set context_level=detailed  # Full information

📖 Topic Learning

ais learn git      # Learn Git version control
ais learn docker   # Learn containerization
ais learn vim      # Learn the text editor
ais learn ssh      # Learn remote access

🔍 Intelligent Error Analysis

# These erroneous commands will automatically trigger AI analysis
pytho --version        # Spelling error
ls /not/exist          # Path does not exist
git statuss            # Command error

📊 Learning Growth Report

ais report                                 # Generate a text-format learning report
ais report --html                          # Generate an HTML visualization report
ais report --html -o my_report.html --open # Generate and open the HTML report

# History management
ais history                # View recent command history
ais history --limit 20     # Show 20 command records
ais history 3              # View detailed analysis of record #3

---

📚 Detailed Features

Environment-Aware Q&A – ais ask

Intelligent Q&A based on the current system environment, automatically sensing hardware configuration, network status, project type, and more:

# 🖥️ System environment-aware Q&A
ais ask "How is my system performance? Do I need to optimize?"
ais ask "Are my currently open ports secure?"
ais ask "What is the status of my network connection?"

# 🚀 Proj