Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/zeus-deus/vexis-agent

The Agent That Knows You
https://github.com/zeus-deus/vexis-agent

ai-agents claude-code hyprland linux omarchy opencode vexis wayland

Last synced: 5 days ago
JSON representation

The Agent That Knows You

Awesome Lists containing this project

README 

          
# vexis-agent



Telegram-bridged agent for Linux desktops. Sends Telegram (or chat

UI) messages through an agent CLI (claude-code by default; opencode

optional) and pipes the brain's tool calls out to your machine —

screenshots, window control, voice notes, browser automation. Vexis

is the transport layer; the brain is whatever CLI you point it at.



Single-user by design. Hyprland/Wayland-targeted. Tailscale-friendly.



> **Linux only.** macOS and Windows aren't supported (the installer

> will refuse to run). Tested on Arch, Debian/Ubuntu, Fedora,

> openSUSE. Desktop-control features (screenshots, window control)

> need a Wayland session; the Telegram side works on any Linux box,

> including headless servers.



## Install



### One-liner (curl-bash)



Auto-runs the setup wizard at the end so you finish configured.



```bash

curl --proto '=https' --tlsv1.2 -fsSL \

  https://raw.githubusercontent.com/Zeus-Deus/vexis-agent/main/install.sh | bash

```



The `--proto '=https' --tlsv1.2` flags pin the transport to modern

TLS over HTTPS — defense-in-depth against a compromised redirect or

ancient TLS downgrade. Drop them at your own risk; they're free.



The installer:



- Refuses to run as root (single-user by design).

- Installs `pipx` if missing, via your distro's package manager.

- Resolves the newest semver release tag and installs from it (falls

  back to the `main` branch when the repo has no tags yet).

- Surfaces missing soft dependencies (brain CLI, Hyprland/Wayland

  tools, Tailscale) with distro-specific install hints.

- Auto-runs `vexis-agent setup` unless `--skip-setup` is passed.



Flags (when piping into bash, pass them after `bash -s --`):



- `--dry-run` — print what would happen, don't install.

- `--skip-setup` — install only; don't launch the wizard.



Every flag has a matching env var, which is the ergonomic path when

you're piping curl into bash (no `bash -s --` gymnastics):



- `VEXIS_VERSION=v0.2.0` — pin to a specific tag or commit. Default

  empty = newest semver tag, falling back to `main`.

- `VEXIS_REPO=git+...` — override the source URL (forks, mirrors).

- `VEXIS_SKIP_SETUP=1` — same effect as `--skip-setup`.

- `VEXIS_DRY_RUN=1` — same effect as `--dry-run`.

- `NO_COLOR=1` — disable ANSI escapes.



### Manual install



If you'd rather skip the auto-setup wizard:



```bash

pipx install git+https://github.com/Zeus-Deus/vexis-agent.git

vexis-agent setup

```



`vexis-agent setup` walks six sections: writes `~/.vexis/config.yaml`

and `~/.vexis/.env` (mode 0600) from shipped templates, prompts for

your Telegram bot token + numeric user ID, verifies the configured

brain CLI is on PATH, sets up `~/vexis-workspace/` (with the

`AGENTS.md → CLAUDE.md` symlink for opencode users), wires any MCP

servers it finds (e.g. `omarchy-kb`), checks Tailscale, and offers

to install the systemd user unit.



### Brain prerequisites



Pick one (you can switch later via `~/.vexis/config.yaml`):



- **claude-code** (default) — 

- **opencode** — 30+ providers including Anthropic OAuth,

  ChatGPT Plus, GitHub Copilot, plus API keys:

  ```bash

  curl -fsSL https://opencode.ai/install | bash

  ```



Authenticate:



- claude-code: `claude /login` (Pro/Max subscription) or set

  `ANTHROPIC_API_KEY` in your shell.

- opencode: `opencode providers login`.



Tip: run `vexis-agent doctor` after install for a 10-check readiness

pass that surfaces every prerequisite (Python, config, secrets,

brain CLI, workspace, dispatch wrappers, Tailscale, systemctl,

linger, service unit).



### Operating system + tooling



Vexis is **Hyprland/Wayland-targeted**. The daemon hard-requires

these binaries on PATH at startup; install them via your distro:



| Tool | Arch | Debian/Ubuntu | Fedora |

|------|------|---------------|--------|

| `hyprctl` | ships with Hyprland | ships with Hyprland | ships with Hyprland |

| `wtype` | `pacman -S wtype` | `apt install wtype` | `dnf install wtype` |

| `ydotool` | `pacman -S ydotool` | `apt install ydotool` | `dnf install ydotool` |

| `grim` | `pacman -S grim` | `apt install grim` | `dnf install grim` |

| `ffmpeg` | `pacman -S ffmpeg` | `apt install ffmpeg` | `dnf install ffmpeg` |

| `jq` | `pacman -S jq` | `apt install jq` | `dnf install jq` |

| `voxtype` | (separate install) | (separate install) | (separate install) |



`tailscale` is optional but strongly recommended — without it, the

dashboard is localhost-only and the live-stream tools have no

remote tunnel.



## Operating



```bash

vexis-agent run                       # foreground daemon

vexis-agent service install           # write the systemd user unit

systemctl --user enable --now vexis-agent.service

vexis-agent service status            # systemctl --user status …

vexis-agent service logs --follow     # journalctl -u … -f

vexis-agent service restart           # after edits to ~/.vexis/config.yaml

vexis-agent doctor                    # 10-check readiness pass



vexis-agent backup --out backup.zip   # pack ~/.vexis + ~/vexis-workspace

vexis-agent backup-restore backup.zip # restore on the destination

vexis-agent update                    # pipx-aware self-upgrade

```



`vexis-agent update` is bullet-proof against bad-luck disconnects:

ignores SIGHUP for the duration, mirrors output to

`~/.vexis/logs/update.log`, and writes a pre-update zip of `~/.vexis/`

to `~/.vexis/backups/pre-update-.zip` before any install work

runs. It never touches `~/.vexis/` or `~/vexis-workspace/`

(decision D7: code dir ≠ data dir) and never auto-restarts the

service — prints a hint instead.



If an update breaks something, restore the pre-update snapshot:



```bash

vexis-agent backup-restore ~/.vexis/backups/pre-update-.zip --overwrite

```



## Migrating to a new machine



Vexis ships first-class backup/restore for personal state — no

manual rsync required.



```bash

# On the source machine:

vexis-agent backup --out vexis-backup.zip

scp vexis-backup.zip you@new-server:



# On the new machine:

curl -fsSL https://…/install.sh | bash    # auto-runs setup wizard

vexis-agent backup-restore vexis-backup.zip

vexis-agent service install

systemctl --user enable --now vexis-agent.service

```



The backup zip contains everything personal: `~/.vexis/config.yaml`,

`~/.vexis/.env`, curator state, learning state, goals, dashboard

token, plus the gittable workspace markdown (CLAUDE.md, SOUL.md,

MEMORY.md, USER.md, RELATIONSHIPS.md, memories/, skills/). It

**excludes** regenerable junk: bytecode caches, browser profiles

(too large; cached chromium), node_modules, `.git` history, runtime

PID files, and SQLite WAL sidecars (which can produce torn restores).



Secrets (`.env`, dashboard token) restore at mode 0600.



### Running multiple installs (dev box + home server)



Telegram only allows **one polling client per bot at a time** — if

two installs share a bot token, only the last-connected one gets

messages. So if you want vexis on both your dev box and a home

server, the clean setup is:



1. Create two bots in @BotFather (e.g. `zeus_vexis_bot` for prod,

   `zeus_vexis_dev_bot` for dev). Set distinct names + icons so you

   can tell them apart on your phone.

2. Run `vexis-agent setup` on each machine with that machine's bot

   token. Same `TELEGRAM_ALLOWED_USER_ID` on both (it's still you).

3. To carry your agent's personality + memories + skills across,

   `vexis-agent backup --include-brain-sessions` on the source

   machine; `vexis-agent backup-restore ` on the destination

   AFTER you've run `vexis-agent setup` there. The default restore

   skips existing files, so the destination's `.env` (with its own

   bot token) is preserved while everything else carries over.



## Extending vexis



**New tools — declare an MCP server** in `~/.vexis/mcp-servers.yaml`

(the universal config — one source of truth, regardless of which

brain you're on):



```yaml

servers:

  - name: my-tool

    command: my-tool

    args: ["--mcp"]

```



Re-run `vexis-agent setup` (or `vexis-agent service restart`) and

both per-brain native files get refreshed: `/.mcp.json`

for claude-code and `/opencode.json` for opencode.

Switching `brain.kind` later is zero-friction — the new brain's

native config is already there. Entries whose binary isn't on

PATH are skipped. Full schema: `vexis_agent/data/mcp-servers.example.yaml`.



**New skills — `vexis-skill create`** or drop a SKILL.md by hand:



```bash

# via the helper (creates the directory, validates frontmatter)

vexis-skill create my-skill --content-file ~/my-skill.md



# or directly

mkdir -p ~/vexis-workspace/skills/my-skill

$EDITOR ~/vexis-workspace/skills/my-skill/SKILL.md

```



The brain auto-discovers everything in `~/vexis-workspace/skills/`

on next session — no restart needed. `vexis-skill list/view/edit/

patch/archive` round out the surface.



**Omarchy users:** [omarchy-mcp](https://github.com/Zeus-Deus/omarchy-mcp)

ships an MCP server with semantic search over Omarchy / Arch /

Hyprland docs. Follow its README to spin it up, then point vexis at

it via `~/.vexis/mcp-servers.yaml`.



**Codemux users:** wire the `codemux` MCP into

`~/.vexis/mcp-servers.yaml` and vexis activates a watcher that

pings you on Telegram when long-running Codemux work (claude-code,

opencode, aider, whatever you launched in a workspace pane) goes

idle. `vexis-watch register --name my-build --workspace

 --agent-kind claude-code` enrols a build; walk away;

get a single Telegram message when the inner agent stops emitting

bytes for ~30s. `/codemux` from the phone lists what's watched.

See `docs/codemux-watcher.md`. Without the `codemux` MCP wired,

nothing changes — zero cost.



## Choosing your brain



The default is `claude-code`. To use opencode instead, set in

`~/.vexis/config.yaml`:



```yaml

brain:

  kind: opencode

```



Restart vexis after editing. See [`docs/brains.md`](docs/brains.md)

for the per-brain reference (auth modes, session storage, MCP

config, tool naming) and [`docs/migration.md`](docs/migration.md)

for the full opt-in / opt-out flow.



Before declaring opencode ready for daily use on a fresh install,

walk through the [dogfood checklist](docs/dogfood-checklist.md) —

12 manual flows covering cold-boot, multi-turn, tools, MCP,

`/cancel`, `/goal`, `/schedule`, daemon restart, bad auth, bad

install, plus two non-negotiable race-condition checks.



## Development setup



For contributors (and the maintainer's own machine). Conda is one

option; venv / uv / poetry all work — pick whatever you like.



```bash

git clone https://github.com/Zeus-Deus/vexis-agent.git

cd vexis-agent

python3 -m venv .venv

source .venv/bin/activate

pip install -e '.[dev]'

```



Or with conda (the maintainer's workflow):



```bash

conda create -n vexis-agent_env python=3.11

conda activate vexis-agent_env

pip install -e '.[dev]'

./scripts/dev-setup.sh   # AGENTS.md repo symlink + git pre-commit hook

```



Run the test suite:



```bash

pytest

```



`scripts/dev-setup.sh` is the dev-side counterpart to `vexis-agent

setup` — it wires the repo's `AGENTS.md → CLAUDE.md` symlink (so

opencode finds the same instruction file claude-code reads from

`CLAUDE.md`) and installs the dashboard-rebuild git pre-commit hook.

Idempotent.



## Project structure



- `vexis_agent/` — installable package; the wheel pipx ships.

  - `cli.py` — Typer entry, source of `vexis-agent` console script.

  - `main.py` — daemon entry.

  - `core/` — main loop, brain ABC + adapters, learning curator,

    goals, schedules, sessions, config.

  - `transports/` — messaging adapters (default `telegram.py`).

  - `tools/` — desktop-control, voxtype, livestream, browser, …

  - `daemon/` — systemd unit rendering, update mechanics, backup,

    doctor.

  - `data/` — shipped runtime resources (CAPABILITIES.md, setup

    templates, workspace CLAUDE.md template).

- `web/` — dashboard frontend (Vite/React; built with `npm run build`).

- `scripts/` — dev helpers (`dev-setup.sh`, `dev_setup.py`,

  `eval_learning.py`, `bench_curator_tick.py`, …) plus the bash

  dispatch wrappers (`vexis-bg`, `vexis-stream`, …) which double as

  console scripts when the wheel is installed.

- `tests/` — pytest suite, parametrised over all three brain

  implementations for the cross-brain contract. ~2000 tests.

- `docs/` — user-facing reference.



## Status



Packaging effort landed on the `packaging-effort` branch. Curl-bash

install, interactive setup wizard, systemd lifecycle, doctor,

backup/restore, robust update with pre-snapshots, and MCP auto-

detection are all implemented and dogfooded on the maintainer's

dev box. Single-user by design; no plans for PyPI / AUR / Docker

yet.