{"id":49754257,"url":"https://github.com/zeus-deus/vexis-agent","last_synced_at":"2026-05-28T15:00:32.491Z","repository":{"id":356952925,"uuid":"1223732534","full_name":"Zeus-Deus/vexis-agent","owner":"Zeus-Deus","description":"The Agent That Knows You","archived":false,"fork":false,"pushed_at":"2026-05-27T20:17:16.000Z","size":16713,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-27T21:10:53.460Z","etag":null,"topics":["ai-agents","claude-code","hyprland","linux","omarchy","opencode","vexis","wayland"],"latest_commit_sha":null,"homepage":"https://vexis-agent.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Zeus-Deus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-28T15:47:58.000Z","updated_at":"2026-05-27T20:17:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Zeus-Deus/vexis-agent","commit_stats":null,"previous_names":["zeus-deus/vexis-agent"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/Zeus-Deus/vexis-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zeus-Deus%2Fvexis-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zeus-Deus%2Fvexis-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zeus-Deus%2Fvexis-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zeus-Deus%2Fvexis-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Zeus-Deus","download_url":"https://codeload.github.com/Zeus-Deus/vexis-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zeus-Deus%2Fvexis-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33613431,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-28T02:00:06.440Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","claude-code","hyprland","linux","omarchy","opencode","vexis","wayland"],"created_at":"2026-05-10T17:27:42.823Z","updated_at":"2026-05-28T15:00:32.482Z","avatar_url":"https://github.com/Zeus-Deus.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# vexis-agent\n\nTelegram-bridged agent for Linux desktops. Sends Telegram (or chat\nUI) messages through an agent CLI (claude-code by default; opencode\noptional) and pipes the brain's tool calls out to your machine —\nscreenshots, window control, voice notes, browser automation. Vexis\nis the transport layer; the brain is whatever CLI you point it at.\n\nSingle-user by design. Hyprland/Wayland-targeted. Tailscale-friendly.\n\n\u003e **Linux only.** macOS and Windows aren't supported (the installer\n\u003e will refuse to run). Tested on Arch, Debian/Ubuntu, Fedora,\n\u003e openSUSE. Desktop-control features (screenshots, window control)\n\u003e need a Wayland session; the Telegram side works on any Linux box,\n\u003e including headless servers.\n\n## Install\n\n### One-liner (curl-bash)\n\nAuto-runs the setup wizard at the end so you finish configured.\n\n```bash\ncurl --proto '=https' --tlsv1.2 -fsSL \\\n  https://raw.githubusercontent.com/Zeus-Deus/vexis-agent/main/install.sh | bash\n```\n\nThe `--proto '=https' --tlsv1.2` flags pin the transport to modern\nTLS over HTTPS — defense-in-depth against a compromised redirect or\nancient TLS downgrade. Drop them at your own risk; they're free.\n\nThe installer:\n\n- Refuses to run as root (single-user by design).\n- Installs `pipx` if missing, via your distro's package manager.\n- Resolves the newest semver release tag and installs from it (falls\n  back to the `main` branch when the repo has no tags yet).\n- Surfaces missing soft dependencies (brain CLI, Hyprland/Wayland\n  tools, Tailscale) with distro-specific install hints.\n- Auto-runs `vexis-agent setup` unless `--skip-setup` is passed.\n\nFlags (when piping into bash, pass them after `bash -s --`):\n\n- `--dry-run` — print what would happen, don't install.\n- `--skip-setup` — install only; don't launch the wizard.\n\nEvery flag has a matching env var, which is the ergonomic path when\nyou're piping curl into bash (no `bash -s --` gymnastics):\n\n- `VEXIS_VERSION=v0.2.0` — pin to a specific tag or commit. Default\n  empty = newest semver tag, falling back to `main`.\n- `VEXIS_REPO=git+...` — override the source URL (forks, mirrors).\n- `VEXIS_SKIP_SETUP=1` — same effect as `--skip-setup`.\n- `VEXIS_DRY_RUN=1` — same effect as `--dry-run`.\n- `NO_COLOR=1` — disable ANSI escapes.\n\n### Manual install\n\nIf you'd rather skip the auto-setup wizard:\n\n```bash\npipx install git+https://github.com/Zeus-Deus/vexis-agent.git\nvexis-agent setup\n```\n\n`vexis-agent setup` walks six sections: writes `~/.vexis/config.yaml`\nand `~/.vexis/.env` (mode 0600) from shipped templates, prompts for\nyour Telegram bot token + numeric user ID, verifies the configured\nbrain CLI is on PATH, sets up `~/vexis-workspace/` (with the\n`AGENTS.md → CLAUDE.md` symlink for opencode users), wires any MCP\nservers it finds (e.g. `omarchy-kb`), checks Tailscale, and offers\nto install the systemd user unit.\n\n### Brain prerequisites\n\nPick one (you can switch later via `~/.vexis/config.yaml`):\n\n- **claude-code** (default) — \u003chttps://docs.anthropic.com/claude/claude-code\u003e\n- **opencode** — 30+ providers including Anthropic OAuth,\n  ChatGPT Plus, GitHub Copilot, plus API keys:\n  ```bash\n  curl -fsSL https://opencode.ai/install | bash\n  ```\n\nAuthenticate:\n\n- claude-code: `claude /login` (Pro/Max subscription) or set\n  `ANTHROPIC_API_KEY` in your shell.\n- opencode: `opencode providers login`.\n\nTip: run `vexis-agent doctor` after install for a 10-check readiness\npass that surfaces every prerequisite (Python, config, secrets,\nbrain CLI, workspace, dispatch wrappers, Tailscale, systemctl,\nlinger, service unit).\n\n### Operating system + tooling\n\nVexis is **Hyprland/Wayland-targeted**. The daemon hard-requires\nthese binaries on PATH at startup; install them via your distro:\n\n| Tool | Arch | Debian/Ubuntu | Fedora |\n|------|------|---------------|--------|\n| `hyprctl` | ships with Hyprland | ships with Hyprland | ships with Hyprland |\n| `wtype` | `pacman -S wtype` | `apt install wtype` | `dnf install wtype` |\n| `ydotool` | `pacman -S ydotool` | `apt install ydotool` | `dnf install ydotool` |\n| `grim` | `pacman -S grim` | `apt install grim` | `dnf install grim` |\n| `ffmpeg` | `pacman -S ffmpeg` | `apt install ffmpeg` | `dnf install ffmpeg` |\n| `jq` | `pacman -S jq` | `apt install jq` | `dnf install jq` |\n| `voxtype` | (separate install) | (separate install) | (separate install) |\n\n`tailscale` is optional but strongly recommended — without it, the\ndashboard is localhost-only and the live-stream tools have no\nremote tunnel.\n\n## Operating\n\n```bash\nvexis-agent run                       # foreground daemon\nvexis-agent service install           # write the systemd user unit\nsystemctl --user enable --now vexis-agent.service\nvexis-agent service status            # systemctl --user status …\nvexis-agent service logs --follow     # journalctl -u … -f\nvexis-agent service restart           # after edits to ~/.vexis/config.yaml\nvexis-agent doctor                    # 10-check readiness pass\n\nvexis-agent backup --out backup.zip   # pack ~/.vexis + ~/vexis-workspace\nvexis-agent backup-restore backup.zip # restore on the destination\nvexis-agent update                    # pipx-aware self-upgrade\n```\n\n`vexis-agent update` is bullet-proof against bad-luck disconnects:\nignores SIGHUP for the duration, mirrors output to\n`~/.vexis/logs/update.log`, and writes a pre-update zip of `~/.vexis/`\nto `~/.vexis/backups/pre-update-\u003cutc\u003e.zip` before any install work\nruns. It never touches `~/.vexis/` or `~/vexis-workspace/`\n(decision D7: code dir ≠ data dir) and never auto-restarts the\nservice — prints a hint instead.\n\nIf an update breaks something, restore the pre-update snapshot:\n\n```bash\nvexis-agent backup-restore ~/.vexis/backups/pre-update-\u003cutc\u003e.zip --overwrite\n```\n\n## Migrating to a new machine\n\nVexis ships first-class backup/restore for personal state — no\nmanual rsync required.\n\n```bash\n# On the source machine:\nvexis-agent backup --out vexis-backup.zip\nscp vexis-backup.zip you@new-server:\n\n# On the new machine:\ncurl -fsSL https://…/install.sh | bash    # auto-runs setup wizard\nvexis-agent backup-restore vexis-backup.zip\nvexis-agent service install\nsystemctl --user enable --now vexis-agent.service\n```\n\nThe backup zip contains everything personal: `~/.vexis/config.yaml`,\n`~/.vexis/.env`, curator state, learning state, goals, dashboard\ntoken, plus the gittable workspace markdown (CLAUDE.md, SOUL.md,\nMEMORY.md, USER.md, RELATIONSHIPS.md, memories/, skills/). It\n**excludes** regenerable junk: bytecode caches, browser profiles\n(too large; cached chromium), node_modules, `.git` history, runtime\nPID files, and SQLite WAL sidecars (which can produce torn restores).\n\nSecrets (`.env`, dashboard token) restore at mode 0600.\n\n### Running multiple installs (dev box + home server)\n\nTelegram only allows **one polling client per bot at a time** — if\ntwo installs share a bot token, only the last-connected one gets\nmessages. So if you want vexis on both your dev box and a home\nserver, the clean setup is:\n\n1. Create two bots in @BotFather (e.g. `zeus_vexis_bot` for prod,\n   `zeus_vexis_dev_bot` for dev). Set distinct names + icons so you\n   can tell them apart on your phone.\n2. Run `vexis-agent setup` on each machine with that machine's bot\n   token. Same `TELEGRAM_ALLOWED_USER_ID` on both (it's still you).\n3. To carry your agent's personality + memories + skills across,\n   `vexis-agent backup --include-brain-sessions` on the source\n   machine; `vexis-agent backup-restore \u003czip\u003e` on the destination\n   AFTER you've run `vexis-agent setup` there. The default restore\n   skips existing files, so the destination's `.env` (with its own\n   bot token) is preserved while everything else carries over.\n\n## Extending vexis\n\n**New tools — declare an MCP server** in `~/.vexis/mcp-servers.yaml`\n(the universal config — one source of truth, regardless of which\nbrain you're on):\n\n```yaml\nservers:\n  - name: my-tool\n    command: my-tool\n    args: [\"--mcp\"]\n```\n\nRe-run `vexis-agent setup` (or `vexis-agent service restart`) and\nboth per-brain native files get refreshed: `\u003cworkspace\u003e/.mcp.json`\nfor claude-code and `\u003cworkspace\u003e/opencode.json` for opencode.\nSwitching `brain.kind` later is zero-friction — the new brain's\nnative config is already there. Entries whose binary isn't on\nPATH are skipped. Full schema: `vexis_agent/data/mcp-servers.example.yaml`.\n\n**New skills — `vexis-skill create`** or drop a SKILL.md by hand:\n\n```bash\n# via the helper (creates the directory, validates frontmatter)\nvexis-skill create my-skill --content-file ~/my-skill.md\n\n# or directly\nmkdir -p ~/vexis-workspace/skills/my-skill\n$EDITOR ~/vexis-workspace/skills/my-skill/SKILL.md\n```\n\nThe brain auto-discovers everything in `~/vexis-workspace/skills/`\non next session — no restart needed. `vexis-skill list/view/edit/\npatch/archive` round out the surface.\n\n**Omarchy users:** [omarchy-mcp](https://github.com/Zeus-Deus/omarchy-mcp)\nships an MCP server with semantic search over Omarchy / Arch /\nHyprland docs. Follow its README to spin it up, then point vexis at\nit via `~/.vexis/mcp-servers.yaml`.\n\n**Codemux users:** wire the `codemux` MCP into\n`~/.vexis/mcp-servers.yaml` and vexis activates a watcher that\npings you on Telegram when long-running Codemux work (claude-code,\nopencode, aider, whatever you launched in a workspace pane) goes\nidle. `vexis-watch register --name my-build --workspace\n\u003cworkspace-id\u003e --agent-kind claude-code` enrols a build; walk away;\nget a single Telegram message when the inner agent stops emitting\nbytes for ~30s. `/codemux` from the phone lists what's watched.\nSee `docs/codemux-watcher.md`. Without the `codemux` MCP wired,\nnothing changes — zero cost.\n\n## Choosing your brain\n\nThe default is `claude-code`. To use opencode instead, set in\n`~/.vexis/config.yaml`:\n\n```yaml\nbrain:\n  kind: opencode\n```\n\nRestart vexis after editing. See [`docs/brains.md`](docs/brains.md)\nfor the per-brain reference (auth modes, session storage, MCP\nconfig, tool naming) and [`docs/migration.md`](docs/migration.md)\nfor the full opt-in / opt-out flow.\n\nBefore declaring opencode ready for daily use on a fresh install,\nwalk through the [dogfood checklist](docs/dogfood-checklist.md) —\n12 manual flows covering cold-boot, multi-turn, tools, MCP,\n`/cancel`, `/goal`, `/schedule`, daemon restart, bad auth, bad\ninstall, plus two non-negotiable race-condition checks.\n\n## Development setup\n\nFor contributors (and the maintainer's own machine). Conda is one\noption; venv / uv / poetry all work — pick whatever you like.\n\n```bash\ngit clone https://github.com/Zeus-Deus/vexis-agent.git\ncd vexis-agent\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -e '.[dev]'\n```\n\nOr with conda (the maintainer's workflow):\n\n```bash\nconda create -n vexis-agent_env python=3.11\nconda activate vexis-agent_env\npip install -e '.[dev]'\n./scripts/dev-setup.sh   # AGENTS.md repo symlink + git pre-commit hook\n```\n\nRun the test suite:\n\n```bash\npytest\n```\n\n`scripts/dev-setup.sh` is the dev-side counterpart to `vexis-agent\nsetup` — it wires the repo's `AGENTS.md → CLAUDE.md` symlink (so\nopencode finds the same instruction file claude-code reads from\n`CLAUDE.md`) and installs the dashboard-rebuild git pre-commit hook.\nIdempotent.\n\n## Project structure\n\n- `vexis_agent/` — installable package; the wheel pipx ships.\n  - `cli.py` — Typer entry, source of `vexis-agent` console script.\n  - `main.py` — daemon entry.\n  - `core/` — main loop, brain ABC + adapters, learning curator,\n    goals, schedules, sessions, config.\n  - `transports/` — messaging adapters (default `telegram.py`).\n  - `tools/` — desktop-control, voxtype, livestream, browser, …\n  - `daemon/` — systemd unit rendering, update mechanics, backup,\n    doctor.\n  - `data/` — shipped runtime resources (CAPABILITIES.md, setup\n    templates, workspace CLAUDE.md template).\n- `web/` — dashboard frontend (Vite/React; built with `npm run build`).\n- `scripts/` — dev helpers (`dev-setup.sh`, `dev_setup.py`,\n  `eval_learning.py`, `bench_curator_tick.py`, …) plus the bash\n  dispatch wrappers (`vexis-bg`, `vexis-stream`, …) which double as\n  console scripts when the wheel is installed.\n- `tests/` — pytest suite, parametrised over all three brain\n  implementations for the cross-brain contract. ~2000 tests.\n- `docs/` — user-facing reference.\n\n## Status\n\nPackaging effort landed on the `packaging-effort` branch. Curl-bash\ninstall, interactive setup wizard, systemd lifecycle, doctor,\nbackup/restore, robust update with pre-snapshots, and MCP auto-\ndetection are all implemented and dogfooded on the maintainer's\ndev box. Single-user by design; no plans for PyPI / AUR / Docker\nyet.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzeus-deus%2Fvexis-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzeus-deus%2Fvexis-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzeus-deus%2Fvexis-agent/lists"}