Metadata-Version: 2.4
Name: aicheat
Version: 0.10.0rc2
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 :: GNU General Public License v3 (GPLv3)
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: powered by [`prompt-toolkit`](https://github.com/prompt-toolkit/python-prompt-toolkit)
- Theming support using `pygments`
- Extensibility via custom tool definitions
- Skills support

## Requirements

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

## Quick Start

### Installation

```bash
# Install a stable version
uv tool install aicheat

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

# Install the latest dev (unstable)
uv tool 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](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)

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

```bash
aicheat --help
```

#### In-Chat Commands

Once in the chat, you can use these commands:

- `/help` - List available commands
- `/tools` - List available tools
- `/session` - Manage sessions (list, resume, delete, rename, summarize)
- `/skill` - Manage skills (list, load, unload, enable, disable)
- `/model` - Show/set the active model
- `/config` - Show/save configuration
- `/yolo` - Toggle YOLO mode (skip tool call confirmations)
- `/reasoning` - Toggle reasoning display and effort level
- `/messages` - Show conversation messages
- `/fragment <file> [prompt]` - Include a file in the session with optional instructions

Use `/help` for the full list of commands.

#### Tools

aicheat comes with several built-in tools:

- **File operations**: read, write, and patch files, search file contents
- **Shell**: execute shell commands, navigate directories, retrieve man pages
- **Git**: view status, commits, patches, and tracked files (automatically enabled in git repos)
- **Python**: execute Python code snippets
- **Web**: search cheat.sh for command cheat sheets, search Wikipedia (disabled by default)
- **Tmux**: manage tmux sessions and panes, can be used to orchestrate aicheat agents, see the [tmux-aicheat skill](skills/aicheat/references/tmux-aicheat.md)

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:

```console
$ 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:

```console
$ 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/`](./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](./AGENTS.md)

### Adding custom tools

You can extend aicheat with custom tools by creating new modules in `src/aicheat/tools/`. For simple function-based tools, use the `@tool` decorator. For tools requiring lifecycle hooks (`on_success`, `on_error`, `on_first_output`) or access to the `Conversation` instance, subclass `ToolBase`.

Simple tool using `@tool`:

```python
from aicheat.tools.core import tool


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

    from subprocess import check_output, CalledProcessError, STDOUT
    result = check_output(["ping", "-c", str(count), host], text=True, stderr=STDOUT)
    return result
```

Advanced tool using `ToolBase` (for lifecycle hooks, streaming output, etc.):

```python
from aicheat.tools.core import ToolBase

class Ping(ToolBase):
    """Ping a host using the unix `ping` tool"""

    name = "ping"
    requires_confirmation = False
    message_template = "🌐 Pinging {host} {count} times"

    def execute(self, host: str, count: int) -> str:
        from subprocess import check_output, STDOUT
        return check_output(["ping", "-c", str(count), host], text=True, stderr=STDOUT)
```

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

- Hit `ctrl-c` twice to clear the conversation history. Use `ctrl-l` to clear the screen without clearing the conversation, then `/messages -1` to display the last message again.
- Prefix a message with `!` to run a shell command. Anything after `#` is treated as a shell comment and included in the output, so you can add instructions for the model: `! ls -la # list files and explain what this project does`
- Commands like `/fragment <file> [prompt]`, `/cd <dir> [prompt]`, and `/cwd [prompt]` accept an optional prompt that is sent to the model along with the command output.

### Token Usage Display

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

```
119.4k (22.77%) ❯
```

Where:

- `119.4k` = total tokens used
- `22.77%` = percentage of context used

Cycle token usage display with `ctrl-t` or use `/config`:

```bash
/config show_tokens no          # Disable (default)
/config show_tokens percentage  # Show: "968 (0.36%) ❯"
/config show_tokens verbose     # Show: "ctx: 301/119.9k/524.3k (22.87%) ❯"
/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:

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