aicheat

A command-line based AI coding assistant

Features

• Supports OpenAI-compatible inference servers (such as vLLM/llama.cpp/OpenAI, ...)
• Powerful line editing/completion capabilities: powered by prompt-toolkit
• Theming support using pygments
• Extensibility via custom tool definitions
• Skills support

Requirements

• Python 3.8+
• An OpenAI-compatible API server (like vLLM or llama.cpp)
• ripgrep (optional, for improved search functionality)
• cht.sh CLI tool (optional, for cheat.sh functionality)

Quick Start

Installation

# Install a stable version
uv pip install aicheat

# Install the latest main
uv pip install git+https://git.decapod.one/brethil/aicheat@main

# Install the latest dev (unstable)
uv pip install git+https://git.decapod.one/brethil/aicheat@dev

# Clone and install (development)
git clone https://git.decapod.one/brethil/aicheat
uv pip install -e ".[dev]"

Configuration requires an OpenAI API key or an a OpenAI-compatible server. These can be configured via environment variables or command-line arguments.

Environment Variables

• AICHEAT_HOST: path to an OpenAI-compatible server, such as vllm, or llama.cpp, see instructions in docs
• OPENAI_API_KEY: (optional) set if API Key is required to connect to AICHEAT_HOST
• AICHEAT_MODEL: (optional) set default model. If a single model is available on AICHEAT_HOST, it is automatically selected. If multiple models are available, user is prompted to select the model.

Note: this should also work with the official OpenAI API, although this is untested.

Command-Line Flags

aicheat [--host <host or endpoint url>] [--api-key <api key>]

Provider Documentation

See docs/providers/ for detailed instructions on using aicheat with different OpenAI-compatible API providers:

• OpenAI API
• vLLM
• llama.cpp

Usage

aicheat --help
# to start chatting:
aicheat
# optionally, a starting message can be provided:

aicheat "What's the current status of this git repo?"

In the aicheat "REPL":

• Type /help for available commands
• Type /tools to see available tools
• Use /theme list to list/select available themes, using /config save to persist the theme choice.
• Prefix messages with ! to run a shell command, e.g. !uptime calls uptime.
• Type a question to start chatting

Additional command-line flags

# Skip confirmation prompts for tool calls (YOLO mode)
aicheat --no-confirm "Fix this bug"

# Skip loading AGENTS.md and memory.md files
aicheat --no-agent-files --no-memory "Explain this code"
# Always load AGENTS.md and memory.md files
aicheat --agent-files --memory "Explain this code"

# Disable all tools
aicheat --no-tools

# Start a session in incognito mode (no persistence)
aicheat --no-confirm --no-agent-files --no-memory

For a complete list of flags, use:

aicheat --help

In-Chat Commands

Once in the chat, you can use these commands:

• /help - List available commands
• /tools - List available tools
• /clear - Clear the conversation history (or hit ctrl-c twice)
• /multiline - Toggle multiline input mode, also see Editor/Multiline section below
• /model - Show/set the active model
• /fragment <file> [prompt] - Include a file in the session with optional instructions
• /config - Show/save configuration, including token usage display settings

Tools

aicheat comes with several built-in tools

File Operations

• read_file(filename) - Read the content of a file
• write_file(filename, content) - Write content to a file
• apply_patch(filename, content) - Patch a file
• search(pattern, path) - Search for patterns in files using ripgrep

System & Shell

• execute_shell_command(cmd) - Execute shell commands (with confirmation)
• man(program_name) - Retrieve man pages for programs
• pwd() - Get current working directory
• cd(path) - Change directory

Git Integration

• git_status() - Show git status as a diff
• git_updates(from_refish) - Show commits since last tag/release
• git_show_patch(commit_id) - Show patch for a specific commit
• git_list_files() - List all git-tracked files

Code Execution

• execute_python_code(code) - Execute Python code snippets (with confirmation)

Web & Documentation

• cheat_sh_search(program_name) - Search cheat.sh for program documentation

Other tools

Use the /tools in-chat command to get an up-to-date list of tools with descriptions.

Restoring sessions

Sessions are automatically saved to ~/.local/share/aicheat/sessions.db and can be resumed:

$ aicheat
❯ Hello
 Hello! 👋
❯ /session
Session: wonderful-babbage
ID: d82b17fa-7e2b-4fb0-ab5e-553b5e9ae6bc
Messages: 2
Created: 2026-05-26 18:53
Updated: 2026-05-26 18:53

After exiting, the session can be resumed after starting aicheat using /session resume, or from the cli:

$ aicheat --resume wonderful-babbage

/session list can be used to list saved sessions:

❯ /session list
                                                Recent sessions
┏━━━┳━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃   ┃    ┃ session name               ┃ session id ┃ msg count ┃ date             ┃ description                ┃
┡━━━╇━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│   │  1 │ wonderful-babbage          │ d82b17fa   │ 2         │ 2026-05-26 18:53 │                            │
│   │  2 │ secret-session             │ a57c98ec   │ 81        │ 2026-05-26 18:52 │ Implementing a secret      │
│   │    │                            │            │           │                  │ feature for aicheat        │
│   │  3 │ determined-borg            │ 5cbe97c2   │ 48        │ 2026-05-26 15:42 │                            │
└───┴────┴────────────────────────────┴────────────┴───────────┴──────────────────┴────────────────────────────┘

The /session command can be used to set custom names, descriptions, create a descriptions using an LLM summary of the conversation and more.

See /help session for a full list of commands

Skills

Load skills using /skill load path/to/skill to extend aicheat's functionality with custom workflows and interaction patterns.

See ./skills/ for skills examples.

Hacking

An aicheat skill is available in ./skills/aicheat and can be loaded via /skill load ./skills/aicheat. This can help out with development, as well as loading AGENTS.md

Adding custom tools

You can extend aicheat with custom tools by creating new modules in src/aicheat/tools/.

Here's an example for a ping tool to check network status:

from aicheat.tools.core import tool
from subprocess import check_output, CalledProcessError, STDOUT
import re


@tool(
    message_template="🌐 Pinging {host} {count} times}"
    requires_confirmation=False,
)
def ping(host: str, count: int) -> str:
    """Pings a host using the unix `ping` tool"""
    if not host:
        return "No host provided"

    try:
        result = check_output(
            ["ping", "-c", str(count), host],
            text=True,
            stderr=STDOUT,  # redirect stderr to stdout
        )
    except CalledProcessError as exc:
        result = f"ping failed with returncode={exc.returncode}\noutput:\n{exc.stdout}"

    return result

Note: @tool() must always be called with parentheses.

For more examples, see:

• aicheat.tools.shell - Shell-related tools
• aicheat.tools.git - Git-related tools
• aicheat.tools.code.python - Python-related code tools

Tips & Tricks

Token Usage Display

aicheat can display token usage information in the prompt, showing the current conversation's token consumption:

ctx: 50/1664/262144 (0.63%) ❯

Where:

• 50 = completion tokens (last response)
• 1664 = total tokens (cumulative)
• 262144 = max model context length
• 0.63% = percentage of context used

Toggle token usage display with ctrl-T or use /config`:

/config show_tokens no          # Disable (default)
/config show_tokens percentage  # Show: "968 (0.36%) ❯"
/config show_tokens verbose     # Show: "ctx: 50/1664/262144 (0.63%) ❯"
/config save                     # Persist configuration

Token counts are per-conversation and reset when the conversation is cleared.

Shell Integration

Add an alias to aicheat so that it's prefixed by noglob, making it easier to give initial prompts from the shell without expanding globs:

echo "alias aicheat=\"noglob aicheat\"" >> ~/.zshrc

Editor/Multiline

The REPL uses prompt-toolkit to leverage its powerful line-editing capabilities. aicheat, depending on your $EDITOR value supports:

• emacs-style line-editing shortcuts:
  • use ctrl-x ctrl-e to open the current line in your $EDITOR)
  • ctrl-a/ctrl-e to move to beginning/end of the current line and other emacs-style movements
• vi-style line-editing shortcuts:
  • vv to open the current line in your $EDITOR
  • modal editing and other vi-style movement shortcuts

Multiline editing is also supported, either via /multiline or via ctrl-v. This can be useful to paste text/code.