ExoBrain

A toy AI assistant with tool calling capabilities and file system access, running in your terminal with or without TUI.

Features

• 💻 TUI Interface - Terminal UI based on Textual
• 🤖 Multi-Model Support - OpenAI, Gemini, local models (hosted via vLLM etc)
• 🛠️ Tools and Skills System - File operations, web search, shell execution. Integrated Anthropic Skills and allow user self defined skills.
• 🔌 MCP Support - Model Context Protocol integration (currently integrated Context7)
• 🔒 Permission Control - Fine-grained permission requests and access control
• 💬 Session Management - Project-level and global session storage
• 🎯 Background Tasks - Create, track, and manage background tasks.
• 📜 Constitutional AI - Customizable behavioral guidelines

For OpenAI apis, currently up to GPT-5 is supported, while GPT-5.2 is not (due to planning is not currently supported yet), but will be added in future updates. The purpose of this project is to experiment with building a modular AI assistant that can integrate multiple models, and tools, with full control and transparency. Only use it for fun, not for production.

Quick Start

Installation

Install from pip:

pip install exobrain

Install from source (development):

git clone https://github.com/visualdust/exobrain.git
cd exobrain

git submodule update --init --recursive

# Install with uv
uv sync

# Or with pip
pip install -e .

Setup

Run the configuration wizard:

exobrain config init

The wizard will guide you through:

• Selecting AI model providers (OpenAI, Gemini, or local models)
• Configuring API keys
• Setting up basic features and permissions

Quick Start

exobrain chat # Start interactive chat
exobrain chat --model openai/gpt-5 # Use specific model
exobrain chat --continue # Resume last session
exobrain chat --help # see other chat options

# Manage sessions
exobrain sessions list
exobrain sessions show <session-id>
exobrain sessions --help # see other session commands

# Manage skills
exobrain skills # manage skills in tui
exobrain skills --help # see other skill commands

# Background tasks
exobrain tasks submit "read file ./data/report.pdf and summarize" # Submit a background task
exobrain tasks list # List background tasks and status
exobrain tasks show <task-id> # Show task details
exobrain tasks --help # see other task commands

# Manage constitution
exobrain constitution list # List all constitutions
exobrain constitution use <name> # Switch constitution
exobrain constitution --help # see other constitution commands

# Make current folder a project folder
exobrain init

---

Documentation

Docs are comming soon!

---

Permission System

ExoBrain requests permission for sensitive operations:

• Once - Grant for this operation only
• Session - Grant for this chat session
• Always - Add to config permanently

Example:

╭─────────────── Permission Request ───────────────╮
│ ⚠️  Permission Required                          │
│                                                  │
│   Tool      shell_execute                        │
│   Action    Execute shell command                │
│   Resource  git status                           │
│   Reason    Command not in allowed list          │
│                                                  │
│  Grant permission for this action?               │
│                                                  │
│    [y] Yes, once       [n] No                    │
│    [s] Yes, session    [a] Yes, always           │
╰──────────────────────────────────────────────────╯

---

License

MIT License - see LICENSE file for details Note that this project integrates third-party skills that may have their own licenses. See the skills directory for details.