Folders and files
| Name | Name | Last commit date | ||
|---|---|---|---|---|
AI in your shell, not another shell
apesh is a lightweight terminal AI assistant that enhances your shell without replacing it. A product by ApeCode.ai — Build smarter with AI
Simply type ape <natural language> in any terminal to get AI assistance; use it and move on without blocking your normal shell workflow.
| Feature | Description |
|---|---|
| Non-blocking | Use it and move on, doesn't interrupt your shell workflow |
| Zero switching cost | Works in any terminal - iTerm2, Terminal, Windows Terminal, etc. |
| Smart fix | ape fix to fix the last failed command with one keystroke |
| Context-aware | Multiple ape calls in the same terminal share context |
| OpenAI compatible | Works with any OpenAI-compatible API (OpenAI, Claude, local models, etc.) |
| Open source | Apache-2.0 license |
┌─────────────────────────────────────────────────────────────────┐ │ │ │ Claude Code Mode apesh Mode │ │ ──────────────── ────────── │ │ │ │ $ claude $ git push │ │ > write an API for me error: rejected... │ │ > modify user.py │ │ > run tests $ ape fix ← use & go │ │ > exit ← exit to return to shell ✅ Fixed │ │ │ │ ┌──────────────────────┐ $ ls -la ← back to shell│ │ │ Enter AI's world │ $ npm install │ │ │ AI is the protagonist│ $ ape what does this error mean│ │ │ Blocking dialogue │ ... │ │ │ Heavyweight │ $ vim config.js ← normal shell│ │ └──────────────────────┘ │ │ ┌──────────────────────┐ │ │ │ AI works in your shell│ │ │ │ You are the protagonist│ │ │ │ Use & go, non-blocking│ │ │ │ Lightweight │ │ │ └──────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘
No Python installation required - the install script handles dependencies automatically:
# One-line install (recommended)
curl -fsSL https://apesh.dev/install.sh | shAfter installation, run ape init to install the shell hook (for recording command history).
# If you have uv
uv tool install apesh
# If you have pip/pipx
pip install apesh
pipx install apeshapesh uses OpenAI-compatible API format, so it works with various providers:
# OpenAI
export API_KEY="sk-..."
export BASE_URL="https://api.openai.com/v1"
export MODEL_NAME="gpt-4o"
# Anthropic (via OpenAI-compatible endpoint)
export API_KEY="your-api-key"
export BASE_URL="https://api.anthropic.com/v1"
export MODEL_NAME="claude-sonnet-4-20250514"
# Local models (Ollama, LM Studio, etc.)
export API_KEY="ollama"
export BASE_URL="http://localhost:11434/v1"
export MODEL_NAME="llama3"~/.ape/config.json:
{
"model": "gpt-4o",
"base_url": "https://api.openai.com/v1",
"max_turns": 10,
"auto_confirm_low_risk": false
}Also supports .env files (~/.ape/.env or .env in project directory):
API_KEY=your-api-key
BASE_URL=https://api.openai.com/v1
MODEL_NAME=gpt-4o# Execute commands with natural language
ape find the process using port 3000 and kill it
# Fix the last failed command
ape fix
# or simply
ape
# Pure Q&A
ape what is a Docker volume
# Auto-execute mode (skip confirmations)
ape --auto format all Python files in current directory| Command | Description |
|---|---|
| ape <natural language> | Main entry point, starts the Agent to process your request |
| ape or ape fix | Fix the last failed command |
| ape --auto <text> | Auto-execute mode (skip confirmations for non-risky commands) |
| ape new | Create a new Session, clear current context |
| ape init | Install shell hook |
| ape uninit | Uninstall shell hook |
| ape --help | Show help |
| ape --version | Show version |
$ ape find the process using port 3000 and kill it
🔍 I'll execute the following steps:
1. Find the process using port 3000
lsof -i :3000
[Enter to confirm / n to cancel] _
# User presses Enter
COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME
node 12345 user 23u IPv4 ... 0t0 TCP *:3000 (LISTEN)
2. Found process PID 12345, terminating...
kill 12345
[Enter to confirm / n to cancel] _
# User presses Enter
✅ Process 12345 terminated$ git push
error: failed to push some refs to 'origin/main'
hint: Updates were rejected because the remote contains work...
$ ape fix
🔧 Detected failed command: git push (exit code: 1)
Analysis: Remote has new commits, need to pull before pushing.
I'll execute:
git pull --rebase && git push
[Enter to confirm / n to cancel] _$ ape what is a Docker volume
Docker volume is a data persistence mechanism provided by Docker...$ ape what framework does this project use
This is an Express + TypeScript project.
# Later...
$ ape help me add a health check endpoint
Sure, I know this is an Express + TypeScript project, let me add a health check endpoint...apesh uses an Agent Loop architecture: the LLM decides whether to respond with text or call tools (execute commands).
┌─────────────────────────────────────────────────────────────┐ │ │ │ User Input ───────► LLM Decision │ │ ▲ │ │ │ │ ▼ │ │ │ ┌───────────────┐ │ │ │ │ Response(text)│ ─────► Output to user │ │ │ └───────────────┘ │ │ │ │ │ │ │ ▼ │ │ │ ┌───────────────┐ │ │ │ │Tool call(shell)│ │ │ │ └───────────────┘ │ │ │ │ │ │ │ ▼ │ │ │ Show command, wait for confirmation │ │ │ (unless --auto) │ │ │ │ │ │ │ ▼ │ │ │ Execute command, get result │ │ │ │ │ │ └─────────────────────┘ │ │ (Result returns to LLM, loop until done) │ │ │ └─────────────────────────────────────────────────────────────┘
- One Terminal Tab = One Session
- Multiple ape calls within the same Session share context
- Shell Hook records command history so LLM has full context
Even in --auto mode, the following high-risk commands require confirmation:
- Bulk deletion (rm -rf, find ... -delete)
- Git force operations (git push --force, git reset --hard)
- Permission changes (chmod 777, chown -R)
- System directory writes (/etc/*, /usr/*, /bin/*)
- Pipe execution (curl ... | sh)
- Privilege escalation (sudo ...)
# Clone the repo
git clone https://github.com/ApeCodeAI/apesh.git
cd apesh
# Run in development mode
uv run ape <natural language>
# Add dependencies
uv add <package>apesh is part of the ApeCode.ai product lab:
| Product | Description |
|---|---|
| apecode | Full-featured AI coding assistant (like Claude Code) |
| apesh | Lightweight terminal AI assistant (this project) |
Visit apecode.ai for more AI-powered developer tools.
AI in your shell, not another shell
apesh 是一个轻量级终端 AI 助手，增强你的 shell 而不是替代它。
在任意终端中输入 ape <自然语言>，即可获得 AI 辅助；用完即走，不阻塞正常的 shell 使用。
# 自然语言执行命令
ape 帮我找到占用 3000 端口的进程并杀掉
# 修复上一条失败的命令
ape fix
# 纯问答
ape 什么是 Docker volume
# 自动执行模式
ape --auto 格式化当前目录下所有 Python 文件apesh 使用 OpenAI 兼容的 API 格式，支持多种 Provider：
# OpenAI
export API_KEY="sk-..."
export BASE_URL="https://api.openai.com/v1"
export MODEL_NAME="gpt-4o"
# 本地模型 (Ollama 等)
export API_KEY="ollama"
export BASE_URL="http://localhost:11434/v1"
export MODEL_NAME="llama3"详细文档请参考上方英文部分。
Made with ❤️ by ApeCode.ai