Metadata-Version: 2.4
Name: tunacode-cli
Version: 0.2.1
Summary: Your agentic CLI developer.
Project-URL: Homepage, https://tunacode.xyz/
Project-URL: Repository, https://github.com/alchemiststudiosDOTai/tunacode
Project-URL: Issues, https://github.com/alchemiststudiosDOTai/tunacode/issues
Project-URL: Documentation, https://github.com/alchemiststudiosDOTai/tunacode#readme
Author-email: larock22 <noreply@github.com>
License: MIT
License-File: LICENSE
Keywords: agent,automation,cli,development
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Python: <3.14,>=3.11
Requires-Dist: click<8.2.0,>=8.1.0
Requires-Dist: html2text>=2024.2.26
Requires-Dist: httpx>=0.27.0
Requires-Dist: pathspec>=0.12.1
Requires-Dist: prompt-toolkit<4.0.0,>=3.0.52
Requires-Dist: pydantic<3,>=2
Requires-Dist: pygments<3.0.0,>=2.19.2
Requires-Dist: pyperclip>=1.11.0
Requires-Dist: python-levenshtein>=0.21.0
Requires-Dist: rich<15.0.0,>=14.2.0
Requires-Dist: ruff>=0.14.0
Requires-Dist: textual-autocomplete>=4.0.6
Requires-Dist: textual<5.0.0,>=4.0.0
Requires-Dist: tiny-agent-os>=1.2.27
Requires-Dist: typer>=0.15.0
Provides-Extra: dev
Requires-Dist: autoflake>=2.0.0; extra == 'dev'
Requires-Dist: bandit; extra == 'dev'
Requires-Dist: build; extra == 'dev'
Requires-Dist: dead>=1.5.0; extra == 'dev'
Requires-Dist: deptry>=0.12.0; extra == 'dev'
Requires-Dist: grimp>=3.14; extra == 'dev'
Requires-Dist: hypothesis>=6.150.0; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pylint>=4.0.4; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest-json-report>=1.5.0; extra == 'dev'
Requires-Dist: pytest-randomly>=3.15.0; extra == 'dev'
Requires-Dist: pytest-timeout>=2.3.1; extra == 'dev'
Requires-Dist: pytest>=9.0.1; extra == 'dev'
Requires-Dist: ruff==0.14.9; extra == 'dev'
Requires-Dist: textual-dev; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Requires-Dist: unimport>=1.0.0; extra == 'dev'
Requires-Dist: vulture>=2.7; extra == 'dev'
Description-Content-Type: text/markdown

# tunacode-cli

<img src="assets/home.png" alt="tunacode" width="600"/>

[![PyPI version](https://badge.fury.io/py/tunacode-cli.svg)](https://badge.fury.io/py/tunacode-cli)
[![Downloads](https://pepy.tech/badge/tunacode-cli)](https://pepy.tech/project/tunacode-cli)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Discord Shield](https://discord.com/api/guilds/1447688577126367346/widget.png?style=shield)](https://discord.gg/TN7Fpynv6H)

A terminal-based AI coding agent with a NeXTSTEP-inspired interface.

> **Early stage software — not production ready.** Under active development, expect bugs and breaking changes.

## Features

- **Any model** - Works with any OpenAI-compatible API
- **File operations** - Read files with hash-tagged lines, create files, and edit existing files with hash-validated references
- **Shell access** - Run bash commands with output capture
- **Repository discovery** - Use `discover` for natural-language code search and repository exploration
- **Session persistence** - Resume previous conversations with `/resume`
- **Themeable UI** - CSS-based theming with NeXTSTEP-inspired design
- **Text selection + clipboard copy** - Mouse selection works across Rich-rendered chat content; copy with `ctrl+y` or `ctrl+shift+c`
- **Agent loop** - Powered by [tinyAgent](https://github.com/alchemiststudiosDOTai/tinyAgent)

## Built With

- **[tinyAgent](https://github.com/alchemiststudiosDOTai/tinyAgent)** - Core agent loop handling LLM interaction and tool execution
- **[alchemy-rs](https://github.com/tunahorse/alchemy-rs)** - Rust-powered tokenizer and utilities via PyO3 bindings
- **Textual** - Terminal UI framework with CSS-based styling
- **Rich** - Terminal rendering with syntax highlighting
- **Typer** - CLI framework


## Installation

### End Users

```bash
uv tool install tunacode-cli
```

Or with pip:
```bash
pip install tunacode-cli
```

### Developers (Fresh Clone)

```bash
git clone https://github.com/alchemiststudiosDOTai/tunacode.git
cd tunacode
make install
```

Or without make:
```bash
git clone https://github.com/alchemiststudiosDOTai/tunacode.git
cd tunacode
./scripts/dev-setup.sh
```

## Development

Common development tasks:

```bash
make install    # Cleanly bootstrap the verified dev environment
make dev-setup  # Alias for make install
make run        # Run the development server
make test       # Run test suite
make lint       # Run linters
make clean      # Clean build artifacts
```

`make install` also installs repo-managed `pre-commit` and `pre-push` hooks from `.githooks/` using relative symlinks, so moving the checkout does not strand the hooks on an old absolute virtualenv path.

View technical debt:

```bash
uv run python scripts/todo_scanner.py --format text
```

## Quick Start

```bash
# Configure API key
tunacode --setup

# Start coding
tunacode
```

## Configuration

Set your API key as an environment variable:

```bash
export ANTHROPIC_API_KEY="your-key"
# or
export OPENAI_API_KEY="your-key"
```

Config file: `~/.config/tunacode.json`

TunaCode deep-merges partial config files onto built-in defaults and validates the merged result at startup. If the file is malformed, the app reports a configuration error instead of silently guessing.

For local models and advanced settings, see the [Configuration Guide](docs/configuration/README.md).

## Commands


Slash commands are command objects in `tunacode.ui.commands`; each one is a `Command` subclass and is registered in `COMMANDS`. `handle_command()` also routes shell commands (`!<cmd>`), legacy `exit`, and slash `/exit`.
| Command | Description |
|---------|-------------|
| `/cancel` | Cancel the current request or shell command. |
| `/help` | Show available commands |
| `/clear` | Clear transient agent state while preserving message history. |
| `/compact` | Force context compaction |
| `/debug` | Toggle debug logging to screen (includes parallel tool-call lifecycle lines) |
| `/model` | Open model picker or switch model |
| `/resume` | List, load, or delete persisted sessions. |
| `/skills` | Browse, search, or load session skills. |
| `/theme` | Open theme picker or switch theme |
| `/thoughts` | Toggle the streaming thought panel. |
| `/update` | Check for or install updates. |
| `!<cmd>` | Run shell command |
| `/exit` | Exit TunaCode |
| `exit` | Legacy alias for exit |


The agent has access to:

| Tool | Description |
|------|-------------|
| `bash` | Execute shell commands |
| `discover` | Search and explore the repository with a natural-language query |
| `read_file` | Read file contents with content-hash tagged lines |
| `hashline_edit` | Edit existing files using hash-validated line references from `read_file` |
| `web_fetch` | Fetch web page content |
| `write_file` | Create new files |


Important tool rules:

- `bash` accepts optional `cwd`, `env`, `timeout`, and `capture_output` arguments in addition to the required `command`.
- `discover` is the semantic repository mapper; use it to find code related to a concept or feature instead of manually chaining search tools.
- `read_file` supports paging with `offset` and `limit`, wraps results in `<file>...</file>`, and each read replaces the editable cache window for that file.
- `hashline_edit` only supports `replace`, `replace_range`, and `insert_after` using `<line>:<hash>` refs from the current `read_file` output.
- `write_file` is create-only: it creates missing parent directories but refuses to overwrite an existing file.
- `web_fetch` only fetches public `http` or `https` URLs and blocks localhost, private, and reserved addresses.

<img src="assets/hashline-edit.png" alt="hashline-edit tool in tunacode" width="600"/>

## Security

TunaCode has **full shell access** with no permission prompts. If you're concerned:
- Use git so you can revert changes
- Run in a container/sandbox

## Discord

[<img src="https://discord.com/api/guilds/1447688577126367346/widget.png?style=banner3" alt="Discord"/>](https://discord.gg/TN7Fpynv6H)

## License

MIT
