This release is a pre-release and may not be stable for production use.
What is Assistant?
Assistant is an AI-powered shell that blends a full Xonsh terminal with a multi-agent LLM system. Talk to it in natural language, run shell commands, browse the web, read and edit files — all from the same prompt.
Under the hood it uses a multi-agent orchestrator: a main agent receives your input and can delegate tasks to specialised agents (system operations, web research, etc.). Every agent, model, and provider is declared in a single TOML configuration file.
Key Features
| Feature | Description |
|---|---|
| 🤖 Multi-Agent Architecture | Orchestrator + specialised agents (system, web researcher, memory, completer) |
| 🔌 Multi-Provider Support | Ollama, vLLM, LM Studio, OpenRouter, Google, NVIDIA, OpenAI — or any OpenAI-compatible API |
| 🛠️ Rich Tool Set | Shell execution, web search (SearXNG), read/edit/write files, read web pages |
| 🧙 Setup Wizard | Interactive wizard generates the TOML config on first launch |
| 🗂️ TOML Configuration | One file (~/.assistant/config.toml) to manage providers, models and agents |
| 💬 Natural Language Shell | Type plain English (or French, etc.) alongside regular commands — SyntaxError lines are auto-routed to NLP |
| 🧠 Context Management | Automatic conversation compaction with sliding window and summarisation |
| 🔍 Web Search | Integrated SearXNG web search with a dedicated research agent |
| 📁 File Operations | Agents can read, write and edit files directly |
| 🖥️ TUI Passthrough | Full-screen apps (vim, htop, less, etc.) run without hijacking |
| 🗣️ Voice (optional) | TTS via say and STT via listen |
| ⚡ Fast Startup | Ultra-fast path for simple commands (< 200ms), lazy NLP init, deferred imports |
| 🎙️ Streaming TTS | Karaoke-style TTS playback with sentence-by-sentence streaming during response generation |
Quick Start
1. Install
pip install assistant
Other installation methods
From source (latest development):
pip install -U git+https://gitlab.com/waser-technologies/technologies/assistant.git@v2
From a local clone:
git clone https://gitlab.com/waser-technologies/technologies/assistant.git
cd assistant
pip install -U .
Arch Linux (AUR):
pacman -S python-assistant
Read Use Assistant as Your Default Shell for more information.
2. Run the Configuration Wizard
On the first launch the wizard starts automatically. You can also re-run it at any time:
assistant config
The wizard asks you to choose:
- Provider — Ollama (local), vLLM (local), LM Studio, OpenRouter, Google, NVIDIA, or OpenAI (API).
- Endpoint — API base URL (e.g.
http://localhost:11434/v1). - API Key — leave the default for local providers, or enter your API key.
- Store in keyring — optionally store the API key securely in your system keyring.
- Model — model identifier (e.g.
qwen3.6:latest,gpt-4o). - Context length — how many tokens the model supports.
- Reasoning — enable/disable thinking traces.
- Web search — enable SearXNG and configure its URL.
The configuration is saved to ~/.assistant/config.toml.
3. Start Assistant
assistant
That's it: you're in. Type commands, ask questions, or mix both.
Requirements
- Python 3.9+
- An LLM backend — one of:
- (optional) SearXNG instance for web search
- (optional)
sayfor text-to-speech - (optional)
listenfor speech-to-text
Note: Unlike v1, there is no local model to download and host yourself. Assistant connects to whichever LLM endpoint you configure. The RAM/VRAM requirements depend entirely on your chosen model and provider.
Usage
CLI options
assistant --help
assistant --version
assistant config # (re)run the configuration wizard
assistant -c "what time is it" # single query, then exit
assistant -n # skip the interactive intro message (warmup)
assistant Hello Assistant # one-shot query
assistant # interactive mode
Interactive Mode
waser@host ~
❯ Hi Assistant.
Hello! How can I assist you today?
waser@host ~
❯ What is the current working directory?
ℹ Executing: echo $PWD
/home/waser
You are currently in your home directory.
waser@host ~
❯ How many moons does Saturn have?
ℹ Searching the Web for: How many moons does Saturn have?
Saturn has 146 confirmed moons as of 2024.
Mix Shell and Natural Language
You can run any valid shell command or Python expression, and when Assistant does not recognise a command it treats your input as a question:
❯ ls -la
❯ echo $USER
❯ Can you count the files in this directory?
ℹ Executing: ls -1 | wc -l
20
There are 20 entries in the current directory.
Natural language with syntax errors (e.g. single quotes like c'est quoi?) is
automatically routed to the NLP agent instead of raising a Python SyntaxError.
Multi-Agent Hand-offs
The Orchestrator can hand off tasks to specialised agents:
- System agent — runs shell commands, manages files, executes Python code in the shared xonsh session.
- Web researcher — searches the web via SearXNG, reads web pages, and produces reports with citations.
- Memory agent — stores and retrieves persistent information from the memory database.
- Completer agent — provides text completion suggestions for the CLI.
Hand-offs happen automatically based on the query context.
Exit the Session
Type any exit-like command and Assistant will understand:
❯ exit
❯ Q
❯ :q
❯ quit
❯ stop()
❯ terminate
❯ This conversation is over.
Configuration
The configuration lives in ~/.assistant/config.toml. Here is an example:
[provider.ollama]
endpoint = "http://localhost:11434/v1"
credential = "keyring:ollama"
[model.qwen]
id = "qwen3.6:latest"
name = "Qwen 3.6 (9B)"
provider = "ollama"
context_length = 256000
think = false
temperature = 0.1
[agent.orchestrator]
name = "Orchestrator"
model = "qwen"
description = "Main orchestrator; handles general conversations and delegates tasks."
instructions = "You are Assistant, a sentient artificial intelligence..."
tools = ["xonsh", "web_search"]
handoffs = ["system", "web", "memory"]
[agent.system]
name = "System"
model = "qwen"
description = "System shell agent for OS interaction."
tools = ["xonsh"]
handoffs = []
[agent.web]
name = "Web Researcher"
model = "qwen"
description = "Web research agent with search and page reading."
tools = ["web_search"]
handoffs = []
[agent.memory]
name = "Memory"
model = "qwen"
description = "Memory management agent for persistent storage."
tools = ["memory_search", "memory_add"]
handoffs = []
[web_search]
enabled = true
searxng_url = "http://localhost:8888"
[completion]
enabled = true
wait_timeout = 1
request_timeout = [10.0, 300.0]
[execution]
max_turns = 50
temperature = 0.1
max_command_output_length = 10000
command_timeout = 180
[memory]
enabled = false
max_entries = 100
[context]
compaction_threshold = 0.8
sliding_window_first = 2
sliding_window_last = 8
use_summarization = true
Adding a New Provider
Just add a new section under [provider]:
[provider.openai]
endpoint = "https://api.openai.com/v1"
credential = "keyring:openai"
[model.gpt4o]
id = "gpt-4o"
name = "GPT-4o"
provider = "openai"
context_length = 128000
Then reference model = "gpt4o" in any agent.
Credential Storage
Credentials are resolved in this order:
- Environment variable —
ASSISTANT_{PROVIDER}_API_KEY(e.g.,ASSISTANT_OPENAI_API_KEY) - System keyring — if credential starts with
keyring:, the value afterkeyring:is used as the keyring service name - OpenAI fallback — for OpenAI provider, also checks
OPENAI_API_KEYstandard env var - Plain text — last resort (not recommended)
To store credentials securely in your system keyring, use assistant config and select "Store in keyring" when prompted, or manually:
import keyring
keyring.set_password("assistant", "openai", "sk-...")
Available Tools
| Tool | Description |
|---|---|
xonsh |
Execute shell commands or Python code in the shared xonsh session |
web_search |
Search the web via SearXNG |
read_webpage |
Fetch and extract readable text from a URL |
read_file |
Read file contents with optional line range |
write_file |
Create or overwrite files |
edit_file |
Find-and-replace text in existing files |
memory_search |
Search persistent memory (when memory is enabled) |
memory_add |
Add entries to persistent memory (when memory is enabled) |
Using Voice
Text-To-Speech
Install say and make sure the service is running:
assistant say Hello World and welcome to everyone.
Assistant supports streaming TTS — sentences are spoken as they arrive during the LLM response, with a karaoke-style display showing which sentence is being pronounced. Press Ctrl+C to stop TTS playback at any time.
Speech-To-Text
Install listen and enable the listen services.
Keyboard Shortcuts
| Shortcut | Action |
|---|---|
| Ctrl+O | Toggle TTS on/off (enable or disable text-to-speech) |
| Ctrl+Q | Toggle STT on/off (enable or disable speech-to-text) |
| Ctrl+Space | Trigger one-shot speech recognition (listen for a sentence) |
| Ctrl+C | Stop TTS playback immediately |
Note: These shortcuts require a terminal that supports the Kitty keyboard protocol or xterm
modifyOtherKeysmode (enabled automatically by Assistant).
Voice Configuration
Voice settings are stored in the voice section of ~/.assistant/config.toml:
[voice]
tts_enabled = true
stt_enabled = true
tts_key = "Ctrl+O"
stt_key = "Ctrl+Q"
listen_key = "Ctrl+Space"
You can configure voice settings in three ways:
- Configuration wizard —
config→ "Voice Settings" - Direct CLI —
config voice <key> <value>(e.g.,config voice tts_enabled false) - Manual edit — edit
~/.assistant/config.tomldirectly
Toggle shortcuts (Ctrl+O, Ctrl+Q) update the config automatically when pressed, so the runtime state persists across sessions.
Use Assistant as Your Default Shell
Assistant is a full Xonsh shell, so it reads the same RC files (~/.config/xonsh/rc.xsh or ~/.xonshrc) which means your existing config carries over as-is.
Read more about Xonsh Installation Guide and its Run Control Files.
Install Assistant in a Stable, Isolated Environment
(so a system Python upgrade can't break your shell)
Example with uv
env_root=~/.venvs
env_path=${env_root}/assistant
python_path=${env_path}/bin/python
mkdir -p $env_root
uv venv $env_path --python 3.13
uv pip install --python ${python_path} assistant
From there to update Assistant, simply run:
uv pip install --python ${python_path} -U assistant
Create a Dedicated Terminal Profile
Since Assistant is a natural language shell and Xonsh is not ready to be fully POSIX compliant, it is highly recommended that you create a dedicated profile for Assistant beside Xonsh and your other shells, directly inside your terminal application, where you can set Assistant as your default shell, instead of registering it for the system.
The path to Assistant is defined as shown in this example.
assistant_bin=${env_path}/bin/assistant
You can also create a symbolic link to Assistant in ~/.local/bin (or any other location in $PATH) so that Assistant is easily accessible.
ln -s $assistant_bin ~/.local/bin
Or you could add ${env_path}/bin to your $PATH.
Register Assistant as a Shell for the System
sudo sh -c "echo ${assistant_bin} >> /etc/shells"
chsh -s $assistant_bin
Log out and back in, Assistant is now your default shell.
Performance Optimizations
Assistant includes several performance optimizations:
- Lazy NLP init: The LLM interface is deferred until first use, avoiding ~4s warmup on startup
- Deferred imports: Heavy ASR/TTS dependencies (numpy, scipy, pyaudio) are only loaded when voice features are actually used
Contributions
Want to improve the project? Check out CONTRIBUTING.md.
Credits
Thanks to all the projects that make this possible:
Metadata
Release files for assistant 2.2.1b1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| assistant-2.2.1b1.tar.gz | 294.0 kB | Without provenance | Details for assistant-2.2.1b1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| assistant-2.2.1b1-py3-none-any.whl | Python 3 | none | any | Details for assistant-2.2.1b1-py3-none-any.whl |
Total release size: 503.0 kB
Release files / assistant-2.2.1b1.tar.gz
| Download URL | assistant-2.2.1b1.tar.gz |
|---|---|
| Size | 294.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d119df25e9046f4ecaed05b902cef2b993fb773ec4d442c378e2d99eb4abd76e
|
|
BLAKE2b-256 checksum How to use checksums |
7fe72ed56108bed9dfd5693c2a10db1c450fd01ff6ef1b2b7ca4a01f59dfd463
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
Release files / assistant-2.2.1b1-py3-none-any.whl
| Download URL | assistant-2.2.1b1-py3-none-any.whl |
|---|---|
| Size | 209.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
63a9c825fa7779608c6dc185939ea2e5fcd6b922abc97c2f5e04b2a00270e281
|
|
BLAKE2b-256 checksum How to use checksums |
af919ea29d137fdc9772f971437882795c181792b46c54cdf5809d3565183833
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
Security for assistant 2.2.1b1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.