apesh

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.

Features

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

apesh vs Claude Code / Cursor

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│   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           │   │
│                                      └──────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Installation

No Python installation required - the install script handles dependencies automatically:

# One-line install (recommended)
curl -fsSL https://apesh.dev/install.sh | sh

After installation, run ape init to install the shell hook (for recording command history).

Alternative Installation

# If you have uv
uv tool install apesh

# If you have pip/pipx
pip install apesh
pipx install apesh

Configuration

API Key (required)

apesh 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"

Config File (optional)

~/.ape/config.json:

{
  "model": "gpt-4o",
  "base_url": "https://api.openai.com/v1",
  "max_turns": 10,
  "auto_confirm_low_risk": false
}

Environment File (optional)

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

Usage

Basic Usage

# 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 Reference

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

Examples

Example 1: Execute Commands with Natural Language

$ 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

Example 2: Fix the Last Failed Command

$ 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] _

Example 3: Pure Q&A

$ ape what is a Docker volume

Docker volume is a data persistence mechanism provided by Docker...

Example 4: Context Sharing Across Calls

$ 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...

How It Works

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)       │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Session Mechanism

• One Terminal Tab = One Session
• Multiple ape calls within the same Session share context
• Shell Hook records command history so LLM has full context

Security

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

Development

# 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>

Related Projects

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.

License

Apache-2.0

---

apesh (中文)

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