Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

assistant

Assistant

Your very own Assistant. Because you deserve it.

pipeline status Latest Release PyPi Status


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:

  1. Provider — Ollama (local), vLLM (local), LM Studio, OpenRouter, Google, NVIDIA, or OpenAI (API).
  2. Endpoint — API base URL (e.g. http://localhost:11434/v1).
  3. API Key — leave the default for local providers, or enter your API key.
  4. Store in keyring — optionally store the API key securely in your system keyring.
  5. Model — model identifier (e.g. qwen3.6:latest, gpt-4o).
  6. Context length — how many tokens the model supports.
  7. Reasoning — enable/disable thinking traces.
  8. 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:
    • Ollama running locally (recommended)
    • vLLM running locally
    • LM Studio running locally
    • Any OpenAI-compatible API (OpenAI, Together, Groq, OpenRouter, etc.)
  • (optional) SearXNG instance for web search
  • (optional) say for text-to-speech
  • (optional) listen for 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

Loading interactive demo preview... (Click to open in full)

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:

  1. Environment variable — ASSISTANT_{PROVIDER}_API_KEY (e.g., ASSISTANT_OPENAI_API_KEY)
  2. System keyring — if credential starts with keyring:, the value after keyring: is used as the keyring service name
  3. OpenAI fallback — for OpenAI provider, also checks OPENAI_API_KEY standard env var
  4. 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 modifyOtherKeys mode (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:

  1. Configuration wizard — config → "Voice Settings"
  2. Direct CLI — config voice <key> <value> (e.g., config voice tts_enabled false)
  3. Manual edit — edit ~/.assistant/config.toml directly

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:

  • Xonsh — the best snail in the jungle
  • Rich and Halo — beautiful terminal output
  • And many, many more.

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)

Source distribution for assistant 2.2.1b1
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)

Table of built distributions (wheels) for assistant 2.2.1b1
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page