Metadata-Version: 2.4
Name: aicheat
Version: 0.5.0.post1
Summary: A command line AI coding assistant
Author-email: brethil <bretello@distruzione.org>
License: GPLv3
Keywords: ai,cli,coding-assistant,llm,developer-tools,openai
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: openai>=2.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: prompt_toolkit>=3.0.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: pygments>=2.16.0
Requires-Dist: tomlkit>=0.14.0
Requires-Dist: pygit2>=1.19.1
Requires-Dist: pyyaml>=6
Provides-Extra: dev
Requires-Dist: ruff>=0.15.4; extra == "dev"
Requires-Dist: typing-extensions>=4.0.0; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"

# aicheat

A command-line based AI coding assistant

[![demo](https://git.decapod.one/brethil/aicheat/raw/tag/v0.4.0.post2/aicheat-demo.mp4)](https://asciinema.org/a/1vcAJJKvLWtSu6Ni)

## Features

- Supports OpenAI-compatible inference servers (such as vLLM/llama.cpp/OpenAI, ...)
- Powerful line editing/completion capabilities thanks to [`prompt-toolkit`](https://github.com/prompt-toolkit/python-prompt-toolkit)
- Theming support using `pygments`
- Extensibility via custom tool definitions
- Skills support

## Installation

```bash
# 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](https://github.com/vllm-project/vllm), or [llama.cpp](https://github.com/ggerganov/llama.cpp), see instructions in [docs](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

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

## Provider Documentation

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

- [OpenAI API](docs/providers/openai.md)
- [vLLM](docs/providers/vllm.md)
- [llama.cpp](docs/providers/llamacpp.md)
- [Local providers (Ollama, LM Studio, etc.)](docs/providers/local.md)

### Basic Usage

```bash
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

```bash
# 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:

```bash
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

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

```python
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:

```bash
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`](https://github.com/BurntSushi/ripgrep) (optional, for improved search functionality)
- `cht.sh` CLI tool (optional, for [cheat.sh](https://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](doc/README.md) for more information about bundled skills.
