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
Metadata
1 maintainer
Release files for tunacode-cli 0.2.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| tunacode_cli-0.2.3.tar.gz | 1.9 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| tunacode_cli-0.2.3-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.3 MB
Release files / tunacode_cli-0.2.3.tar.gz
| Download URL | tunacode_cli-0.2.3.tar.gz |
|---|---|
| Size | 1.9 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
170b1b14582d461d69f0c9c6edd30747bfcad171e646832a566be739fae6de29
|
|
BLAKE2b-256 checksum How to use checksums |
0102fd8ec415c54e0c8a8c5b52bfe641fff1f6ada34e97f2b86b71c3ee0a10bb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Release files / tunacode_cli-0.2.3-py3-none-any.whl
| Download URL | tunacode_cli-0.2.3-py3-none-any.whl |
|---|---|
| Size | 419.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bdc5768b427ac4a1de1048c7f4b5ef91b94d3889b303a0e0652da9985caae5ed
|
|
BLAKE2b-256 checksum How to use checksums |
aab3f9e753d5f7f3e66a5843de2a629e406ff89f18d8e802c6ac2b55c4abae04
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
