tunacode-cli
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
discoverfor 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+yorctrl+shift+c - Agent loop - Powered by tinyAgent
Built With
- tinyAgent - Core agent loop handling LLM interaction and tool execution
- 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
uv tool install tunacode-cli
Or with pip:
pip install tunacode-cli
Developers (Fresh Clone)
git clone https://github.com/alchemiststudiosDOTai/tunacode.git
cd tunacode
make install
Or without make:
git clone https://github.com/alchemiststudiosDOTai/tunacode.git
cd tunacode
./scripts/dev-setup.sh
Development
Common development tasks:
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:
uv run python scripts/todo_scanner.py --format text
Quick Start
# Configure API key
tunacode --setup
# Start coding
tunacode
Configuration
Set your API key as an environment variable:
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.
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:
bashaccepts optionalcwd,env,timeout, andcapture_outputarguments in addition to the requiredcommand.discoveris the semantic repository mapper; use it to find code related to a concept or feature instead of manually chaining search tools.read_filesupports paging withoffsetandlimit, wraps results in<file>...</file>, and each read replaces the editable cache window for that file.hashline_editonly supportsreplace,replace_range, andinsert_afterusing<line>:<hash>refs from the currentread_fileoutput.write_fileis create-only: it creates missing parent directories but refuses to overwrite an existing file.web_fetchonly fetches publichttporhttpsURLs and blocks localhost, private, and reserved addresses.
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
License
MIT
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file tunacode_cli-0.2.3.tar.gz.
File metadata
- Download URL: tunacode_cli-0.2.3.tar.gz
- Upload date:
- Size: 1.9 MB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.12.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
170b1b14582d461d69f0c9c6edd30747bfcad171e646832a566be739fae6de29
|
|
| MD5 |
6be1ee6b1747fd2be80f09cde78c16af
|
|
| BLAKE2b-256 |
0102fd8ec415c54e0c8a8c5b52bfe641fff1f6ada34e97f2b86b71c3ee0a10bb
|
File details
Details for the file tunacode_cli-0.2.3-py3-none-any.whl.
File metadata
- Download URL: tunacode_cli-0.2.3-py3-none-any.whl
- Upload date:
- Size: 419.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.12.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
bdc5768b427ac4a1de1048c7f4b5ef91b94d3889b303a0e0652da9985caae5ed
|
|
| MD5 |
cb3477e87abdff953909119bd4973ed6
|
|
| BLAKE2b-256 |
aab3f9e753d5f7f3e66a5843de2a629e406ff89f18d8e802c6ac2b55c4abae04
|
