tunacode-cli 0.2.0

Your agentic CLI developer.

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 (Anthropic, OpenAI, Google, Ollama, vLLM, etc.)
• Native tinyagent tools - Direct tinyagent tool contracts with no legacy wrapper compatibility layer
• 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
• LSP diagnostics - Real-time code errors after file writes (Python, TypeScript, Go, Rust)
• 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 dev-setup

Or without make:

git clone https://github.com/alchemiststudiosDOTai/tunacode.git
cd tunacode
./scripts/dev-setup.sh

Development

Common development tasks:

make dev-setup  # Full setup for fresh clone
make install    # Install/update dependencies
make run        # Run the development server
make test       # Run test suite
make lint       # Run linters
make clean      # Clean build artifacts

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

Confirm Parallel Tool Calls

Run /debug to enable lifecycle logs. During agent execution, parallel batches are reported with lines prefixed by:

• [LIFECYCLE] Parallel tool calls active: ...
• [LIFECYCLE] Parallel tool calls update: ...
• [LIFECYCLE] Parallel tool calls complete

If no Parallel tool calls lifecycle lines appear, that request did not execute a parallel tool batch.

Tools

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

TunaCode now uses the native tinyagent tool surface directly. Legacy wrapper-based tools such as update_file, glob, grep, and list_dir are removed rather than translated through a compatibility layer.

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.

LSP Integration

Automatic code diagnostics when LSP servers are in PATH:

Language	Server
Python	ruff server
TypeScript/JS	typescript-language-server
Go	gopls
Rust	rust-analyzer

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