AI-Powered Terminal Assistant — Beautiful TUI · Powerful CLI · Flexible SDK

Bring modern AI assistance directly to your terminal. Chat with Claude, GPT-4, Gemini, and local models using a rich interactive interface or simple CLI commands.

📖 Full Documentation

# Install with TUI (recommended) pip install 'consoul[tui]' # Or install SDK/CLI only pip install consoul

# Choose your provider export ANTHROPIC_API_KEY=your-key-here # Claude export OPENAI_API_KEY=your-key-here # GPT-4 export GOOGLE_API_KEY=your-key-here # Gemini

consoul tui

git diff | consoul ask --stdin "create a commit message and commit"

from consoul import Consoul console = Consoul() print(console.chat("What is 2+2?"))

Rich, interactive terminal interface powered by Textual

• Multi-turn conversations with streaming responses
• Conversation history and search
• File attachments and image analysis
• Customizable themes (light/dark)
• Mouse and keyboard navigation

Use your favorite AI model or run locally:

• Anthropic Claude - Claude 4.5 Sonnet, Opus, Haiku
• OpenAI - GPT-5, GPT-4, GPT-3.5
• Google Gemini - Gemini 3 Flash, Pro
• Ollama - Run models locally (Llama, Qwen, GPT-OSS etc.)
• LlamaCpp - GGUF/MLX models with GPU acceleration

File Editing Let AI create, modify, and delete files with safety controls:

consoul ask "Add error handling to calculate_total in src/utils.py" --tools

Code Search Navigate your codebase semantically:

consoul ask "Find all usages of deprecated_function" --tools

Image Analysis Debug with screenshots:

consoul ask "What's wrong with this error?" --attach screenshot.png

And More:

• Bash command execution with approval workflows
• Web search and URL fetching
• Session management and history

For quick questions without the TUI:

# One-off questions consoul ask "Explain Python decorators" # Interactive chat mode consoul chat

Embed AI capabilities in your Python applications:

from consoul import Consoul # Enable tools for file operations and code search console = Consoul(tools=True) # Stateful conversation console.chat("List all TODO comments in Python files") console.chat("Create a summary.md file with the results") # Rich responses with metadata response = console.ask("Summarize this project", show_tokens=True) print(f"Tokens: {response.tokens}") print(f"Cost: ${console.last_cost['total_cost']:.4f}")

📖 Full Documentation

Getting Started:

• Installation Guide
• Quick Start
• Configuration

TUI:

• Interface Guide
• Keyboard Shortcuts
• Themes

Tools:

• File Editing
• Image Analysis
• Code Search

SDK:

• SDK Overview
• Tutorial
• API Reference

Create ~/.consoul/config.yaml:

# Default profile profiles: default: model: provider: anthropic model: claude-3-5-sonnet-20241022 temperature: 0.7 tools: enabled: true permission_policy: balanced # Require approval for risky operations conversation: save_history: true max_history: 50 # Local model profile local: model: provider: ollama model: llama3.2:latest

Switch profiles:

consoul --profile local

See the Configuration Guide for all options.

Consoul includes comprehensive security controls for tool execution:

• Permission Policies - PARANOID, BALANCED, TRUSTING, UNRESTRICTED
• Approval Workflows - Interactive confirmation for dangerous operations
• Audit Logging - Complete execution history in JSONL format
• Command Validation - Pattern-based blocking of risky commands

See the Security Policy for best practices.

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

MIT License - see LICENSE file for details.

• Textual - Beautiful TUI framework
• LangChain - AI orchestration
• Anthropic - Claude AI models
• OpenAI - GPT models
• Google AI - Gemini models

Made with ❤️ by Jared Rummler