aicheat 0.6.0

A command line AI coding assistant

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 thanks to prompt-toolkit
• Theming support using pygments
• Extensibility via custom tool definitions
• Skills support

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

Quick Start

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
• Local providers (Ollama, LM Studio, etc.)

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

# Disable all tools
aicheat --no-tools

# Start a session with no initial prompts
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

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.

Tool Calling

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

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

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.

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)

License

MIT

• aicheat.tools.shell shell-related tools
• aicheat.tools.git git-related tools
• aicheat.tools.code.python python-related code tools

Skills

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

See doc/README.md for more information about bundled skills.