Metadata-Version: 2.4
Name: patchllm
Version: 1.0.0
Summary: An interactive agent for codebase modification using LLMs
Author: nassimberrada
License: MIT License
        
        Copyright (c) 2025 nassimberrada
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the “Software”), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: litellm
Requires-Dist: python-dotenv
Requires-Dist: rich
Requires-Dist: prompt_toolkit
Requires-Dist: InquirerPy
Provides-Extra: voice
Requires-Dist: SpeechRecognition; extra == "voice"
Requires-Dist: pyttsx3; extra == "voice"
Provides-Extra: url
Requires-Dist: html2text; extra == "url"
Provides-Extra: all
Requires-Dist: SpeechRecognition; extra == "all"
Requires-Dist: pyttsx3; extra == "all"
Requires-Dist: html2text; extra == "all"
Dynamic: license-file

<p align="center">
  <picture>
    <source srcset="./assets/logo_dark.png" media="(prefers-color-scheme: dark)">
    <source srcset="./assets/logo_light.png" media="(prefers-color-scheme: light)">
    <img src="./assets/logo_light.png" alt="PatchLLM Logo" height="200">
  </picture>
</p>

## About
PatchLLM is an interactive command-line agent that helps you modify your codebase. It uses an LLM to plan and execute changes, allowing you to review and approve every step.

## Key Features
- **Interactive Planning:** The agent proposes a step-by-step plan before writing any code. You stay in control.
- **Dynamic Context:** Build and modify the code context on-the-fly using powerful scope definitions (`@git:staged`, `@dir:src`, etc.).
- **Mobile-First TUI:** A clean, command-driven interface with autocompletion makes it easy to use on any device.
- **Resilient Sessions:** Automatically saves your progress so you can resume if you get disconnected.

## Getting Started

**1. Initialize a configuration file (optional):**
This creates a `scopes.py` file to define reusable file collections.
```bash
patchllm --init
```

**2. Start the Agent:**
Running `patchllm` with no arguments drops you into the interactive agentic TUI.
```bash
patchllm
```

**3. Follow the Agent Workflow:**
Inside the TUI, you direct the agent with simple slash commands.

```bash
# 1. Set the goal
>>> /task Add a health check endpoint to the API

# 2. Build the context
>>> /context @dir:src/api

# 3. Ask the agent to generate a plan
>>> /plan
1. Add a new route `/health` to `src/api/routes.py`.
2. Implement the health check logic to return a 200 OK status.

# 4. Execute the first step and review the proposed changes
>>> /run

# 5. If the changes look good, approve them
>>> /approve
```

## Agent Commands (TUI)
| Command | Description |
|---|---|
| `/task <goal>` | Sets the high-level goal for the agent. |
| `/plan [management]` | Generates a plan, or opens an interactive TUI to edit/add/remove steps. |
| `/run [all]` | Executes the next step, or all remaining steps with `/run all`. |
| `/approve` | Interactively select and apply changes from the last run. |
| `/diff [all \| file]`| Shows the full diff for the proposed changes. |
| `/retry <feedback>`| Retries the last step with new feedback. |
| `/skip` | Skips the current step and moves to the next. |
| `/revert` | Reverts the changes from the last `/approve`. |
| `/context <scope>` | Replaces the context with files from a scope. |
| `/scopes` | Opens an interactive menu to manage your saved scopes. |
| `/ask <question>` | Ask a question about the plan or code context. |
| `/refine <feedback>`| Refine the plan based on new feedback or ideas. |
| `/show [state]` | Shows the current state (goal, plan, context, history, step). |
| `/settings` | Configure the model and API keys. |
| `/help` | Shows the detailed help message. |
| `/exit` | Exits the agent session. |

## Headless Mode Flags
For scripting or single-shot edits, you can still use the original flags.

| Flag | Alias | Description |
|---|---|---|
| `-p`, `--patch` | **Main action:** Query the LLM and apply file changes. |
| `-t`, `--task` | Provide a specific instruction to the LLM. |
| `-s`, `--scope` | Use a static scope from `scopes.py` or a dynamic one. |
| `-r`, `--recipe` | Use a predefined task from `recipes.py`. |
| `-in`, `--interactive` | Interactively build the context by selecting files. |
| `-i`, `--init` | Create a new `scopes.py` file. |
| `-sl`, `--list-scopes`| List all available scopes. |
| `-ff`, `--from-file` | Apply patches from a local file. |
| `-fc`, `--from-clipboard` | Apply patches from the system clipboard. |
| `-m`, `--model` | Specify a different model (default: `gemini/gemini-1.5-flash`). |
| `-v`, `--voice` | Enable voice interaction (requires voice dependencies). |

## Setup
PatchLLM uses [LiteLLM](https://github.com/BerriAI/litellm). Set up your API keys (e.g., `OPENAI_API_KEY`, `GEMINI_API_KEY`) in a `.env` file.

The interactive TUI requires `prompt_toolkit` and `InquirerPy`. You can install all core dependencies with:```bash
pip install -r requirements.txt
```

Optional features require extra dependencies:
```bash
# For URL support in scopes
pip install "patchllm[url]"

# For voice commands (in headless mode)
pip install "patchllm[voice]"
```

## License
This project is licensed under the MIT License.
