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.)
• File operations - Read, write, update files with fuzzy matching for edits
• Shell access - Run bash commands with output capture
• Code search - Glob patterns and grep with ripgrep integration
• 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
• Copy-on-select - Automatically copies highlighted text to clipboard
• 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

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
/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
/theme	Open theme picker or switch theme
/resume	List, load, or delete persisted sessions.
/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
read_file	Read file contents with line ranges
write_file	Create new files
update_file	Edit existing files with fuzzy matching
bash	Execute shell commands
glob	Find files by pattern
grep	Search file contents
list_dir	List directory tree
web_fetch	Fetch web page content

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