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.
# 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 # Geminiconsoul tuigit 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" --toolsCode Search Navigate your codebase semantically:
consoul ask "Find all usages of deprecated_function" --toolsImage Analysis Debug with screenshots:
consoul ask "What's wrong with this error?" --attach screenshot.pngAnd 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 chatEmbed 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}")Getting Started:
TUI:
Tools:
SDK:
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:latestSwitch profiles:
consoul --profile localSee 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 GoatBytes.IO