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 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

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:

• 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.

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