| Name | rune-code JSON |
| Version |
0.14.0
JSON |
| download |
| home_page | None |
| Summary | A terminal first, opinionated AI coding agent written in Python. Works with almost any model via Pydantic-AI. |
| upload_time | 2025-07-20 01:23:01 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | Apache-2.0 |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Rune Code
Rune's a terminal first coding agent, it's my personal forever ongoing personal project.
It builds on the excellent [Pydantic-AI](https://github.com/pydantic/pydantic-ai) which among many things lets you easily switch between different models (Claude vs Gemini) as well as providers (Claude on Bedrock, Gemini on Vertex AI, etc.)
<img width="1490" height="902" alt="rune" src="https://github.com/user-attachments/assets/40490fc9-aa55-4fa6-ac15-3a56eb2dc256" />
---
## Table of Contents
1. [Features](#features)
2. [Prerequisites](#prerequisites)
3. [Installation & Configuration](#installation--configuration)
4. [Quick Start: Your First Session](#quick-start-your-first-session)
5. [Usage Cheatsheet](#usage-cheatsheet)
6. [Core Capabilities](#core-capabilities)
7. [For Developers](#for-developers)
8. [License](#license)
---
## Features
| Capability | Description |
|---|---|
| **Interactive Chat** | Multi-line editing, history, and command completion via `prompt-toolkit`. |
| **Advanced Tooling** | Edit files with fuzzy diffs, `grep` the codebase, run shell commands, and execute Python in a persistent Jupyter kernel. |
| **Rich TUI** | A clean, colorful terminal UI powered by **Rich**, with syntax highlighting, tables, and live-streaming output. |
| **Session Management** | Conversations and session context are automatically saved, allowing you to resume a session exactly where you left off. For example todos are automatically saved and loaded along with messages. |
| **Task Planning** | Rune can manage a TODO list to break down complex tasks, track progress, and ensure it completes all steps. |
| **Extensible** | Easily add new tools by dropping a function into the `src/rune/tools/` directory. |
---
## Prerequisites
- Python 3.10 or higher.
- An API key for a supported LLM provider (e.g., OpenAI, Google, Anthropic).
---
## Installation & Configuration
### 1. Installation
Install Rune - I'd recommend `uv` nowadays.
```bash
# Recommended
uv add rune-code
# Alternatively, using pip
pip install rune-code
```
### 2. Configuration
Rune builds on top of Pydantic-AI - make sure to setup auth/config correctly. See [here](https://ai.pydantic.dev/models/).
```bash
# Example for OpenAI
export OPENAI_API_KEY="sk-..."
# Example for Google
export GOOGLE_API_KEY="..."
```
You can also specify which model to use. If not set, Rune defaults to a safe but capable model. Model list [here](https://ai.pydantic.dev/api/models/base/).
```bash
# Optional: Specify a model
export RUNE_MODEL="google-gla:gemini-2.5-pro"
# Google Vertex Example
export RUNE_MODEL="google-vertex:gemini-2.5-pro"
# OpenAI Example
export RUNE_MODEL="openai:gpt-4"
# Anthropic Example
export RUNE_MODEL="anthropic:claude-sonnet-4-20250514"
# Bedrock Example
export RUNE_MODEL="bedrock:us.anthropic.claude-sonnet-4-20250514-v1:0"
```
Within the chat you can also use the slash command `/model <model_name>` to switch models. It'll allow you to tab complete the model name.
---
## Quick Start: Your First Session
Let's run a simple task to see Rune in action: listing the files in the current directory.
**Step 1: Start Rune**
Run the `rune` command in your terminal.
```bash
rune
```
You will be prompted to start a new session.
**Step 2: Ask Rune to List Files**
At the prompt, ask Rune to list the files.
```
> Use the list_files tool to show me the files in the current directory.
```
**Step 3: See the Result**
Rune will execute the `list_files` tool and display the output in a clean, tree-like format.
This simple interaction demonstrates the core loop: you give Rune a goal, and it uses its tools to accomplish it.
---
## Usage Cheatsheet
| Action | Command | Notes |
|---|---|---|
| Start a new chat | `rune` | Choose "Start new session" from the menu. |
| Resume a session | `rune` | Pick a recent session from the list. |
| Exit the chat | `/exit` or `Ctrl-D` | |
| Interrupt a task | `Ctrl-C` | Stops the current operation. |
| Save a snapshot | `/save [name]` | Saves the current session state to `.rune/snapshots/`. |
| Change model | `/model <name>` | e.g., `/model google:gemini-1.5-pro`. Use Tab to complete. |
| List models | `rune models list`| Lists all supported models grouped by provider. |
| Change directory | `run_command("cd path/to/dir")` | Changes the agent's working directory for tool use. |
---
## Core Capabilities
Rune's power comes from its built-in tools. Here are a few examples of what you can ask it to do.
- **Grep the codebase:**
> "Find all occurrences of the `run_command` function."
- **Edit a file with a precise diff:**
> "In `src/rune/main.py`, find the `run_agent_turn` function and add a print statement at the beginning that says 'Starting turn'."
- **Run a shell command and analyze its output:**
> "Run `ls -l` and tell me which file was modified most recently."
- **Manage a task list for a complex change:**
> "I need to add a new feature. First, create a new file called `features.py`. Second, add a function to it called `new_feature`. Finally, add a test for it in `tests/test_features.py`."
---
## For Developers
The following sections are for those interested in contributing to or learning about the architecture of Rune.
### Architecture Overview
```mermaid
flowchart TD
subgraph CLI
A["chat.py
prompt-toolkit"]
end
subgraph Agent
B["pydantic_ai.Agent"] --> C["rich_tool wrapper"]
end
subgraph Tools
D["edit_file
run_python
grep
…"]
end
subgraph UI
E["render.py
Rich console
LiveDisplayManager"]
end
subgraph Persistence
F[".rune/sessions/*.json"]
end
A -->|prompt| B
B -->|XML tool call| C
C -->|exec| D
D -->|ToolResult| C
C -->|renderable| E
B -->|assistant text| E
A <--> F
```
### Core Libraries
| Domain | Library |
|---|---|
| LLM Orchestration | **pydantic-ai** |
| Terminal UI | **Rich** |
| CLI Framework | **Typer** + **prompt-toolkit** |
| Diff/Patch Engine | Custom `DiffApplyer` + `difflib` |
| HTTP & Markdown | `httpx`, `html-to-markdown` |
| Interactive Python | `jupyter_client`, `ipykernel` |
| Git-style Ignores | `pathspec` |
### Testing & Linting
We use `pytest` for testing, `ruff` for linting and formatting, and `mypy` for type checking.
```bash
# Run all unit tests
pytest
# Check for linting errors and format code
ruff check .
ruff format .
# Run static type checking
mypy src
```
### Contributing
Contributions are welcome! Please follow these steps:
1. Fork the repository and create a feature branch.
2. Follow the style conventions enforced by `ruff`.
3. Add unit tests for any new functionality.
4. Ensure all checks (`pytest`, `ruff`, `mypy`) pass.
5. Submit a pull request.
---
## License
Rune is licensed under the **Apache 2.0 License**.
Raw data
{
"_id": null,
"home_page": null,
"name": "rune-code",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Binal Patel <binalkp91@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/f6/2d/60bc1fc963d956f9a1cd1ce66d1ba79eb1f03cf789303bf4800963de8f18/rune_code-0.14.0.tar.gz",
"platform": null,
"description": "# Rune Code\n\nRune's a terminal first coding agent, it's my personal forever ongoing personal project.\n\nIt builds on the excellent [Pydantic-AI](https://github.com/pydantic/pydantic-ai) which among many things lets you easily switch between different models (Claude vs Gemini) as well as providers (Claude on Bedrock, Gemini on Vertex AI, etc.)\n\n<img width=\"1490\" height=\"902\" alt=\"rune\" src=\"https://github.com/user-attachments/assets/40490fc9-aa55-4fa6-ac15-3a56eb2dc256\" />\n\n---\n\n## Table of Contents\n\n1. [Features](#features)\n2. [Prerequisites](#prerequisites)\n3. [Installation & Configuration](#installation--configuration)\n4. [Quick Start: Your First Session](#quick-start-your-first-session)\n5. [Usage Cheatsheet](#usage-cheatsheet)\n6. [Core Capabilities](#core-capabilities)\n7. [For Developers](#for-developers)\n8. [License](#license)\n\n---\n\n## Features\n\n| Capability | Description |\n|---|---|\n| **Interactive Chat** | Multi-line editing, history, and command completion via `prompt-toolkit`. |\n| **Advanced Tooling** | Edit files with fuzzy diffs, `grep` the codebase, run shell commands, and execute Python in a persistent Jupyter kernel. |\n| **Rich TUI** | A clean, colorful terminal UI powered by **Rich**, with syntax highlighting, tables, and live-streaming output. |\n| **Session Management** | Conversations and session context are automatically saved, allowing you to resume a session exactly where you left off. For example todos are automatically saved and loaded along with messages. |\n| **Task Planning** | Rune can manage a TODO list to break down complex tasks, track progress, and ensure it completes all steps. |\n| **Extensible** | Easily add new tools by dropping a function into the `src/rune/tools/` directory. |\n\n---\n\n## Prerequisites\n\n- Python 3.10 or higher.\n- An API key for a supported LLM provider (e.g., OpenAI, Google, Anthropic).\n\n---\n\n## Installation & Configuration\n\n### 1. Installation\n\nInstall Rune - I'd recommend `uv` nowadays.\n\n```bash\n# Recommended\nuv add rune-code\n\n# Alternatively, using pip\npip install rune-code\n```\n\n### 2. Configuration\n\nRune builds on top of Pydantic-AI - make sure to setup auth/config correctly. See [here](https://ai.pydantic.dev/models/).\n\n```bash\n# Example for OpenAI\nexport OPENAI_API_KEY=\"sk-...\"\n\n# Example for Google\nexport GOOGLE_API_KEY=\"...\"\n```\n\nYou can also specify which model to use. If not set, Rune defaults to a safe but capable model. Model list [here](https://ai.pydantic.dev/api/models/base/).\n\n```bash\n# Optional: Specify a model\nexport RUNE_MODEL=\"google-gla:gemini-2.5-pro\"\n\n# Google Vertex Example\n\nexport RUNE_MODEL=\"google-vertex:gemini-2.5-pro\"\n\n# OpenAI Example\nexport RUNE_MODEL=\"openai:gpt-4\"\n\n# Anthropic Example\nexport RUNE_MODEL=\"anthropic:claude-sonnet-4-20250514\"\n\n# Bedrock Example\nexport RUNE_MODEL=\"bedrock:us.anthropic.claude-sonnet-4-20250514-v1:0\"\n```\n\nWithin the chat you can also use the slash command `/model <model_name>` to switch models. It'll allow you to tab complete the model name.\n\n---\n\n## Quick Start: Your First Session\n\nLet's run a simple task to see Rune in action: listing the files in the current directory.\n\n**Step 1: Start Rune**\n\nRun the `rune` command in your terminal.\n\n```bash\nrune\n```\n\nYou will be prompted to start a new session.\n\n**Step 2: Ask Rune to List Files**\n\nAt the prompt, ask Rune to list the files.\n\n```\n> Use the list_files tool to show me the files in the current directory.\n```\n\n**Step 3: See the Result**\n\nRune will execute the `list_files` tool and display the output in a clean, tree-like format.\n\nThis simple interaction demonstrates the core loop: you give Rune a goal, and it uses its tools to accomplish it.\n\n---\n\n## Usage Cheatsheet\n\n| Action | Command | Notes |\n|---|---|---|\n| Start a new chat | `rune` | Choose \"Start new session\" from the menu. |\n| Resume a session | `rune` | Pick a recent session from the list. |\n| Exit the chat | `/exit` or `Ctrl-D` | |\n| Interrupt a task | `Ctrl-C` | Stops the current operation. |\n| Save a snapshot | `/save [name]` | Saves the current session state to `.rune/snapshots/`. |\n| Change model | `/model <name>` | e.g., `/model google:gemini-1.5-pro`. Use Tab to complete. |\n| List models | `rune models list`| Lists all supported models grouped by provider. |\n| Change directory | `run_command(\"cd path/to/dir\")` | Changes the agent's working directory for tool use. |\n\n---\n\n## Core Capabilities\n\nRune's power comes from its built-in tools. Here are a few examples of what you can ask it to do.\n\n- **Grep the codebase:**\n > \"Find all occurrences of the `run_command` function.\"\n\n- **Edit a file with a precise diff:**\n > \"In `src/rune/main.py`, find the `run_agent_turn` function and add a print statement at the beginning that says 'Starting turn'.\"\n\n- **Run a shell command and analyze its output:**\n > \"Run `ls -l` and tell me which file was modified most recently.\"\n\n- **Manage a task list for a complex change:**\n > \"I need to add a new feature. First, create a new file called `features.py`. Second, add a function to it called `new_feature`. Finally, add a test for it in `tests/test_features.py`.\"\n\n---\n\n## For Developers\n\nThe following sections are for those interested in contributing to or learning about the architecture of Rune.\n\n### Architecture Overview\n\n```mermaid\nflowchart TD\n subgraph CLI\n A[\"chat.py\n prompt-toolkit\"]\n end\n subgraph Agent\n B[\"pydantic_ai.Agent\"] --> C[\"rich_tool wrapper\"]\n end\n subgraph Tools\n D[\"edit_file\n run_python\n grep\n \u2026\"]\n end\n subgraph UI\n E[\"render.py\n Rich console\n LiveDisplayManager\"]\n end\n subgraph Persistence\n F[\".rune/sessions/*.json\"]\n end\n\n A -->|prompt| B\n B -->|XML tool call| C\n C -->|exec| D\n D -->|ToolResult| C\n C -->|renderable| E\n B -->|assistant text| E\n A <--> F\n```\n\n### Core Libraries\n\n| Domain | Library |\n|---|---|\n| LLM Orchestration | **pydantic-ai** |\n| Terminal UI | **Rich** |\n| CLI Framework | **Typer** + **prompt-toolkit** |\n| Diff/Patch Engine | Custom `DiffApplyer` + `difflib` |\n| HTTP & Markdown | `httpx`, `html-to-markdown` |\n| Interactive Python | `jupyter_client`, `ipykernel` |\n| Git-style Ignores | `pathspec` |\n\n### Testing & Linting\n\nWe use `pytest` for testing, `ruff` for linting and formatting, and `mypy` for type checking.\n\n```bash\n# Run all unit tests\npytest\n\n# Check for linting errors and format code\nruff check .\nruff format .\n\n# Run static type checking\nmypy src\n```\n\n### Contributing\n\nContributions are welcome! Please follow these steps:\n1. Fork the repository and create a feature branch.\n2. Follow the style conventions enforced by `ruff`.\n3. Add unit tests for any new functionality.\n4. Ensure all checks (`pytest`, `ruff`, `mypy`) pass.\n5. Submit a pull request.\n\n---\n\n## License\n\nRune is licensed under the **Apache 2.0 License**.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "A terminal first, opinionated AI coding agent written in Python. Works with almost any model via Pydantic-AI.",
"version": "0.14.0",
"project_urls": {
"Bug Tracker": "https://github.com/caesarnine/rune-code/issues",
"Homepage": "https://github.com/caesarnine/rune-code"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e6873064040848d4c1e09f1d5bcbd1ffccf4d1557b75f6c3dd41dab537bb331b",
"md5": "91b5ddc7d34f70118e609ced0f6ebbee",
"sha256": "961bccf245b40336aec3552bbacf9452bbddeae06d44075f1ddd47867d64ab07"
},
"downloads": -1,
"filename": "rune_code-0.14.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "91b5ddc7d34f70118e609ced0f6ebbee",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 63005,
"upload_time": "2025-07-20T01:22:59",
"upload_time_iso_8601": "2025-07-20T01:22:59.507322Z",
"url": "https://files.pythonhosted.org/packages/e6/87/3064040848d4c1e09f1d5bcbd1ffccf4d1557b75f6c3dd41dab537bb331b/rune_code-0.14.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f62d60bc1fc963d956f9a1cd1ce66d1ba79eb1f03cf789303bf4800963de8f18",
"md5": "905b1301d1edf39347ee27a40be3272a",
"sha256": "efec7b0bb8c1eeebdd20c67fe5856a31ec5977cac6133f59a9f9a3591290173a"
},
"downloads": -1,
"filename": "rune_code-0.14.0.tar.gz",
"has_sig": false,
"md5_digest": "905b1301d1edf39347ee27a40be3272a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 54847,
"upload_time": "2025-07-20T01:23:01",
"upload_time_iso_8601": "2025-07-20T01:23:01.096091Z",
"url": "https://files.pythonhosted.org/packages/f6/2d/60bc1fc963d956f9a1cd1ce66d1ba79eb1f03cf789303bf4800963de8f18/rune_code-0.14.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-20 01:23:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "caesarnine",
"github_project": "rune-code",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "rune-code"
}
