assistant

A minimalist, self-improving personal AI assistant written in Rust.

• Local-first — runs entirely on your machine via Ollama
• Agent Skills native — skills are portable SKILL.md directories following the agentskills.io open standard
• Self-improving — passively logs execution traces and proposes SKILL.md refinements for human review
• MCP server — exposes skills via the Model Context Protocol so Claude Code and other tools can discover and invoke them
• Multi-interface — single assistant binary runs orchestrator, workers, web UI, MCP, and chat interfaces via subcommands
• Ambient skills — active interfaces register their capabilities (e.g. slack-post) into the skill executor so the Persona can use them from any context

Domain model terms

• Persona — long-lived assistant context with its own memory and workspace scope.
• Subagent Process — ephemeral delegated task execution unit.
• A2A Profile — Persona-attached external protocol contract (discovery + auth + interfaces).

See docs/glossary.md for canonical wording rules.

Quick start

# 1. Install Ollama and pull the default model
ollama pull qwen2.5:7b

# 2. Build the unified binary
cargo build -p assistant-cli --release

# 3. Copy the default config
mkdir -p ~/.assistant
cp config.toml ~/.assistant/config.toml

# 4. Copy built-in skills next to the binary (or run from the repo root)
cp -r skills target/release/

# 5. Run
./target/release/assistant

The REPL starts immediately. Type a message or a /command:

assistant> What's the weather like in Paris?
assistant> /skills
assistant> /review
assistant> /install anthropics/skills/web-search
assistant> /quit

Running specific modes

The single binary supports several subcommands:

assistant orchestrator run                          # REPL + configured interfaces
assistant orchestrator run --no-repl                # background daemon mode
assistant orchestrator run --interfaces slack       # only selected interface(s)
assistant worker --interface any --id worker-1      # dedicated turn worker
assistant webui serve --listen 127.0.0.1:8080 ...  # web UI + A2A server
assistant signal link --device-name AssistantBot    # link Signal device
assistant mcp                                       # stdio MCP server

If Slack, Mattermost, Nextcloud, and/or Signal credentials are present in ~/.assistant/config.toml, interfaces start automatically when running assistant orchestrator run.

Model recommendations (2026)

All models below support Ollama native tool-calling. Use Q4_K_M quantization for 14 B+ models to stay within the stated VRAM budget.

Pull any model and set it in ~/.assistant/config.toml:

ollama pull qwen2.5:14b
# then set model = "qwen2.5:14b" in ~/.assistant/config.toml

Built-in tools

File I/O

Shell

Web

Memory

Skills & meta

Subagent Processes

Interfaces may register additional ambient tools at runtime (e.g. slack-post, slack-send-dm when Slack is configured).

Skill discovery order

At startup the assistant scans several locations (highest priority first):

1. Entries from [skills] extra_dirs — defaults include ~/.claude/skills and ./.claude/skills so Claude Code / NanoClaw skills are auto-loaded
2. ~/.assistant/skills/ — personal skills
3. <project>/.assistant/skills/ — project-scoped skills
4. <binary dir>/skills/ — built-in skills shipped with the binary

Installing new skills

# From a local directory
assistant> /install ~/my-skills/code-review

# From a GitHub repository (owner/repo[/sub/path])
assistant> /install anthropics/skills/code-review

Or via the MCP install_skill tool when connecting from Claude Code.

Self-improvement

Every skill execution produces an OpenTelemetry span that lands in SQLite's distributed_traces table. When you run:

assistant> Analyse the web-fetch skill and suggest improvements

The assistant invokes self-analyze, queries the recent traces, sends them along with the current SKILL.md to Ollama, and stores the proposed improvement in the database. Review and apply it:

assistant> /review

MCP server

Run the MCP server to expose skills to Claude Code, Cursor, or any other MCP client:

# From source
cargo run -p assistant-cli -- mcp

# From release binary
assistant mcp

Configure in Claude Code's settings.json:

{
  "mcpServers": {
    "assistant": {
      "command": "/path/to/assistant",
      "args": ["mcp"]
    }
  }
}

Exposed tools

Exposed resources

Configuration

Copy config.toml to ~/.assistant/config.toml and edit:

[llm]
provider = "ollama"            # "ollama" (default), "anthropic", "openai", or "moonshot"
model = "qwen2.5:7b"          # any Ollama model with tool-calling support
base_url = "http://localhost:11434"
max_iterations = 80

For cloud providers, set the provider and API key:

[llm]
provider = "anthropic"
model    = "claude-sonnet-4-20250514"
api_key  = "sk-ant-..."       # or set ANTHROPIC_API_KEY env var

Embeddings

Ollama and OpenAI support embeddings natively. When using Anthropic (which lacks built-in embeddings), configure a dedicated embedding provider:

[llm.embeddings]
provider = "voyage"            # "ollama", "openai", or "voyage"
model    = "voyage-3-lite"     # optional, provider-specific default used
# api_key = "pa-..."          # or set VOYAGE_API_KEY env var

To use NATS JetStream instead of SQLite for the message bus (eliminates write-lock contention at high concurrency), set [bus] kind = "nats" and configure:

[bus]
kind = "nats"
nats_url = "nats://localhost:4222"   # or set NATS_URL env var
# username = "myuser"               # or NATS_USER
# password = "s3cret"               # or NATS_PASSWORD
# token = "t0k3n!"                  # or NATS_TOKEN
# credentials_file = "/path/to.creds"  # or NATS_CREDENTIALS_FILE

Workspace layout

assistant/
├── crates/
│   ├── core/                           # Shared types, ToolHandler trait, MessageBus
│   ├── llm/                            # LlmProvider trait, EmbeddingProvider, LlmClient
│   ├── provider-ollama/                # Ollama backend (native tool-call + embeddings)
│   ├── provider-anthropic/             # Anthropic backend (Claude models)
│   ├── provider-openai/                # OpenAI backend (GPT models + embeddings)
│   ├── provider-moonshot/              # Moonshot/Kimi backend (OpenAI-compatible)
│   ├── skills/                         # Skill parsing, validation, embedded builtins
│   ├── storage/                        # SQLite, SkillRegistry, trace store, memory store
│   ├── bus-nats/                       # NATS JetStream MessageBus (optional, feature-gated)
│   ├── runtime/                        # ReAct orchestrator, scheduler, Subagent Processes
│   ├── tool-executor/                  # Builtin tool registry + skill installer
│   ├── transcription/                  # Voice transcription providers (Whisper, Ollama, Deepgram)
│   ├── mcp-server/                     # MCP stdio server library (used by `assistant mcp`)
│   ├── mcp-client/                     # MCP client for connecting to external MCP servers
│   ├── interface-cli/                  # Unified binary: orchestrator, worker, webui, MCP
│   ├── interface-slack/                # Slack Socket Mode library + ambient tools
│   ├── interface-mattermost/           # Mattermost WebSocket library
│   ├── interface-nextcloud/            # Nextcloud Talk webhook bot
│   ├── interface-signal/               # Signal interface library
│   ├── web-ui/                         # Trace analysis web UI + A2A protocol server
│   ├── a2a-json-schema/                # A2A protocol JSON Schema types
│   ├── opentelemetry-exporter-sqlite/  # SQLite exporter for OpenTelemetry spans/logs
│   └── integration-tests/              # End-to-end smoke tests
├── docker/                             # Dockerfiles (all build the unified assistant binary)
├── migrations/                         # SQLite migration files
├── skills/                             # Built-in SKILL.md definitions
└── config.toml                         # Default configuration template

Development

make build          # cargo build --workspace
make test           # cargo test --workspace
make lint           # cargo clippy --workspace -D warnings
make format         # cargo fmt --all
make run            # cargo run -p assistant-cli  (REPL + background interfaces)
make run-mcp        # cargo run -p assistant-cli -- mcp
make run-slack      # cargo run -p assistant-cli -- orchestrator run --interfaces slack --no-repl
make run-mattermost # cargo run -p assistant-cli -- orchestrator run --interfaces mattermost --no-repl
make run-nextcloud  # cargo run -p assistant-cli -- orchestrator run --interfaces nextcloud --no-repl
make run-signal     # cargo run -p assistant-cli -- orchestrator run --interfaces signal --no-repl
# Trace analysis UI (auth token required)
ASSISTANT_WEB_TOKEN=changeme cargo run -p assistant-cli -- webui serve --listen 127.0.0.1:8080

Observability

The runtime emits OpenTelemetry traces, logs, and metrics for every conversation turn, LLM call, and tool invocation. All three signals are persisted to a local SQLite database (powering the built-in web UI) and can optionally be exported to any OTLP-compatible collector.

# Send all signals to an OTLP collector (Jaeger, Tempo, Grafana, Honeycomb, …)
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 assistant

# Per-signal endpoints
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://tempo:4317 \
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://loki:4317 \
  assistant

# Auth headers for managed backends
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer token" assistant

The opentelemetry-otlp crate reads the standard OTEL_EXPORTER_OTLP_* env vars (endpoint, headers, timeout, compression) with per-signal overrides — see docs/opentelemetry.md for the full reference of emitted spans, metrics, and supported environment variables.

Pre-commit hooks

Git hooks live in .githooks/. After cloning, activate them once:

make install-hooks

The pre-commit hook runs cargo fmt --check, cargo clippy, and cargo machete before every commit. Install cargo-machete if you don't have it:

cargo install cargo-machete

Running as a user service (Linux)

The .deb and .rpm packages ship systemd user unit files so the Slack and Mattermost bots run in the background under your own account — with full access to your desktop session ($DISPLAY, $WAYLAND_DISPLAY, D-Bus) for future desktop integration.

Quick start

# 1. Install the package (sets up unit files in /usr/lib/systemd/user/)
sudo apt install ./assistant_*.deb    # or rpm -i assistant_*.rpm

# 2. Edit your config
cp /etc/assistant/config.toml.example ~/.assistant/config.toml
$EDITOR ~/.assistant/config.toml      # add Slack/Mattermost credentials

# 3. Enable and start whichever bots you need
systemctl --user enable --now assistant-slack
systemctl --user enable --now assistant-mattermost
systemctl --user enable --now assistant-nextcloud
systemctl --user enable --now assistant-web-ui

# 4. (Once) persist across reboots without staying logged in
loginctl enable-linger $USER

Upgrade path

sudo apt upgrade assistant
# Restart=on-failure in the unit file brings the service back up automatically
# after the binary is replaced.  No manual restart needed.

View logs

journalctl --user -u assistant-slack -f
journalctl --user -u assistant-mattermost -f
journalctl --user -u assistant-nextcloud -f
journalctl --user -u assistant-web-ui -f

Stop / disable

systemctl --user disable --now assistant-slack

Note: The interactive REPL (assistant with no subcommand) is not suited for running as a service — use assistant orchestrator run --interfaces <name> --no-repl.

Docker

The Docker image uses assistant as the primary entrypoint for all runtime modes, including Web UI serving via assistant webui serve:

# Interactive REPL (default)
docker run ghcr.io/cedricziel/assistant/assistant

# MCP server
docker run ghcr.io/cedricziel/assistant/assistant assistant mcp

# Slack bot
docker run ghcr.io/cedricziel/assistant/assistant assistant orchestrator run --interfaces slack --no-repl

# Mattermost bot
docker run ghcr.io/cedricziel/assistant/assistant assistant orchestrator run --interfaces mattermost --no-repl

# Web UI
docker run ghcr.io/cedricziel/assistant/assistant assistant webui serve --listen 0.0.0.0:8080 --auth-token changeme

Mount your config at runtime:

docker run -v ~/.assistant/config.toml:/etc/assistant/config.toml \
  ghcr.io/cedricziel/assistant/assistant

Signal interface

Signal is available through orchestrator mode:

assistant orchestrator run --interfaces signal --no-repl

See crates/interface-signal/README.md for setup and device linking details.

Further documentation

License

MIT