Vikix gives you these ways to use AI, from the most capable to the most private:
What it is: Claude Code (or another agent), in a terminal, able to change the desktop for you
What it needs: A Claude account (Pro or Max), or an Anthropic API key; others need their own
Where your words go: Anthropic, or the agent’s company; nowhere with --local
What it is: A model that runs on this laptop, to chat with
What it needs: vikix ai setup, and a few GB of disk
Where your words go: Nowhere: it all stays here
llmWhat it is: One command for any model, fed from a pipe
What it needs: vikix ai llm, and a local model or a key
Where your words go: Here, or to the model’s company
What it is: Proofread, rewrite, translate, explain or ask about the text you selected, in any program
What it needs: vikix ai llm, and a local model (or Claude, if you choose)
Where your words go: Here, unless you choose Claude
What it is: Speak, and it types what you said, in any program
What it needs: vikix add dictation (a few minutes, once)
Where your words go: Nowhere: it all stays here
What it is: Talk to the AI or the agent, and it answers aloud
What it needs: vikix add voice (a minute, once)
Where your words go: As Super+i’s, or the agent’s; the listening and the voice stay here
What it is: A chat about your code, and your agent in a side window (Space A)
What it needs: vikix add neovim, and a local model, a key or an agent
Where your words go: As Super+i’s, or the agent’s
What it is: The same, with gptel (C-c g) and agent-shell (C-c a)
What it needs: vikix add emacs, and a local model, a key or an agent
Where your words go: As Super+i’s, or the agent’s
noteWhat it is: Questions answered from your own notes, an Obsidian vault say, in any terminal
What it needs: vikix add notes (it brings local AI)
Where your words go: Nowhere with a local model; to Anthropic, only the passages found, with Claude
~/dev/aiWhat it is: Small programs of your own that call Claude or a local model, and one that answers from your notes
What it needs: vikix add python, and a key or a local model
Where your words go: Here, or to Anthropic when you run the Claude ones
You can use any of them, all of them, or none. Nothing AI runs until you start it.
llm on the command linenote~/dev/aiAn agent is an AI that does things, not only talks about them. Claude Code reads files, runs commands and edits your settings, and it knows how Vikix is put together, so you can ask for a change in plain words.
Press Super+a. It asks: Agent here, or Agent at a new desk; then which agent: yours first (Claude Code, unless you chose another: Another agent, below), the others, and the ones that can run on a model on this laptop. Enter twice, or a in a terminal, opens a terminal with your agent in it. The second choice is for an agent on a project, with a copy of the repository to itself; it asks for the project, a topic, the task and which agent: Agents says when you want that.
The first time, it offers to install Claude Code (with Anthropic’s installer, into ~/.local/bin), then asks you to log in. Log in with your Claude account: the agent then uses your plan. If you’d rather pay per use with an API key, see API keys below.
Type what you want and press Return. /exit or Ctrl+D leaves.
Anything about this desktop, in your own words. For example:
It isn’t limited to the desktop: it can write and run code in ~/dev, explain an error, or tidy a folder.
~/.claude/skills/vikix: where every file is, which ones are yours to change, the keys, and the vikix commands. Its first page is short (the rules that always hold); the rest is a page a subject, which the agent reads when it needs it. Its main rule is the one in Where everything is: change your files, never Vikix’s.
vikix eval runs Lisp in the running window manager, so the agent can try a key or a colour on the live desktop, see that it works, and only then save it in ~/.stumpwm.d/user.lisp.
/permissions command shows what it may do without asking.
Before every session, Vikix saves a snapshot of your settings. The terminal says so in its first lines:
:: snapshot 99e03a6: before an agent session (claude) :: to see what the agent changed: vikix changes to take it back: vikix undo
So after a session:
vikix changes # what the agent changed in your files vikix undo # put them back as they were before it started vikix undo # again: take the undo back vikix history # every snapshot, newest first
In a terminal, vikix undo first lists the files it would change and asks. Answer no when the snapshot one back isn’t the one you meant (an agent started from an editor takes one too), and pick one from vikix history with vikix undo ID. This covers your settings (the files in ~/vikix/config/yours.list), not everything in your home folder. For your work, keep backups: README: Backups.
Claude Code isn’t the only one. Five others work the same way, with the same snapshot first and the same guide:
Signs in with: Any model company you have an account with
Can run on this laptop: Yes
Modes (vikix agent --mode): Its own settings (asks before a command or an edit, as Vikix sets it)
Signs in with: Your ChatGPT account
Can run on this laptop: Yes
Modes (vikix agent --mode): supervised, autonomous, unrestricted: its sandbox narrowed to the desk, who answers a step out of it
agy)Signs in with: Your Google account (free, AI Pro or AI Ultra), or a Gemini API key
Can run on this laptop: No
Modes (vikix agent --mode): Its own (--mode plan for a report)
Signs in with: A Gemini API key, or a Code Assist licence from work
Can run on this laptop: No
Modes (vikix agent --mode): Its own (--approval-mode)
Signs in with: An API key (vikix ai key set anthropic)
Can run on this laptop: Yes
Modes (vikix agent --mode): None
The word is Codex’s for now: --mode with another agent is refused, and each other agent’s mapping comes as it is tried. Claude Code’s own is --permission-mode, which vikix agent sets to plan for a report (vikix diagnose).
vikix agent --list # which are installed, and which Super+a starts vikix agent --use opencode # try one: it offers to install it first vikix agent --default opencode # make Super+a start it vikix agent --default claude # back to Claude Code vikix add codex # or install one as a feature (vikix remove codex takes it away)
Which one? Claude Code is the one Vikix is made with and tested with. OpenCode or Aider if you want to work offline. With a Google account, Antigravity CLI: in June 2026 Gemini CLI stopped serving personal accounts (the free tier, AI Pro and AI Ultra) and sent them there; Gemini CLI stays for a Gemini API key (vikix ai key set gemini, then VIKIX_AGENT_API_KEY=1 vikix agent --use gemini, since keys are kept from agents) or a Code Assist Standard or Enterprise licence.
Antigravity CLI is installed from the release Vikix has pinned and checked (its SHA-512 is in vikix agent), not with Google’s installer, which would write a PATH line into your .bashrc, .profile and .bash_profile; ~/.local/bin is on your PATH already. An agy that Google’s installer put there is found and left as it is. At its first start it signs you in in your browser and keeps the sign-in in the system keyring (/logout in it drops it); to use a Gemini API key instead, set "modelProvider": "gemini" in ~/.gemini/antigravity-cli/settings.json, and Vikix then lets that one key through. From then on agy updates itself in the background (AGY_CLI_DISABLE_AUTO_UPDATE=true stops that). It has no local models and doesn’t speak ACP. agy -c picks up the last conversation in this folder: vikix agent --use antigravity -c. It can work at a desk of its own (vikix agents worker DESK "..." --use antigravity); its conversation id is recorded on handoff automatically, and vikix agents resume DESK picks that conversation back up (agy --conversation ID). vikix mcp register adds the desktop’s MCP tools to it (agy mcp add vikix -- ...).
Always through Vikix: start them with vikix agent --use NAME (or Super+a), not by typing codex or opencode: that skips the snapshot, and the protections below.
From an editor: an editor that starts an agent itself should run vikix agent --exec NAME and the agent’s own options after it, or vikix agent --exec for yours. It’s the same start, with the same protections, but quiet: nothing of Vikix’s in the agent’s output, and no questions. Editors that speak ACP, the Agent Client Protocol (Neovim’s CodeCompanion, below; Emacs’s agent-shell; Zed), run vikix agent --acp NAME: Gemini CLI and OpenCode speak it themselves, and Claude Code and Codex need a small adapter, which vikix agent --install claude (or codex) puts next to them. It uses the agent you have, and your login. It needs Node 22 or newer, which vikix add neovim brings. Aider and Antigravity CLI don’t speak ACP. vikix agent --which says which agent is yours, and vikix ai use which model Super+i uses.
Offline, on a local model: vikix agent --use opencode --local (or codex, or aider; --model NAME picks one). It picks the best of your models for code. Be warned: on a laptop’s CPU each answer takes minutes (Aider on llama3.2:3b took over four minutes for one sentence), and a small model rarely carries out a change on its own. A bigger model (vikix ai models) does more, more slowly still.
What an agent doesn’t get, so that a trick hidden in a web page or a file it reads can’t use it:
git push of the day, it holds your unlocked key: an agent with it could push, as you, to anything you can. If you want the agent to push for you: VIKIX_AGENT_SSH=1 vikix agent; at a desk, the picker asks (the last question, no unless you say yes), or vikix agents worker DESK "..." --push.
vikix agents worker, or the MCP server’s office tool) would carry the marks to the new agent, which then takes itself for a child of that session and saves no transcript ("Transcript saving is off: inherited CLAUDE_CODE_CHILD_SESSION marker", and vikix agents resume finds nothing). vikix agent drops them: a desk’s agent is a session of its own.
This prevents accidents; it isn’t a wall. The agent runs as you, and can read your files. OpenCode is set to ask before it runs a command or edits a file, as Claude Code does, unless your own OpenCode settings say otherwise.
How they know Vikix: OpenCode reads the same skill as Claude Code. Codex, Gemini, Antigravity and Aider read ~/.local/share/vikix/AGENTS.md, the skill’s first page, which names the other pages where they can open them: Vikix links it as ~/.codex/AGENTS.md, writes a one-line ~/.gemini/GEMINI.md that imports it, writes a rule file of its own for Antigravity, ~/.gemini/antigravity-cli/rules/vikix.md, that includes it (Antigravity reads every rule there), and hands it to Aider (not to a small local model, for which it’s too long). If you have one of those files already, it’s yours and stays; Vikix says how to add the guide to it. That is the desktop’s rules; a project’s come from the file at its root, AGENTS.md where there is one, CLAUDE.md otherwise: Codex, which reads only AGENTS.md by itself, is given CLAUDE.md as the file to fall back on for the session, whole (see Modes: how free a Codex worker is).
The house rules (vikix agents touch, Agents at work) reach Claude Code, Antigravity CLI and Codex: Claude Code gets the hook for the session, Antigravity as a plugin of Vikix’s that stays (agy plugin list shows vikix; agy plugin disable vikix switches it off), Codex from a hooks file of Vikix’s you link once (vikix agents hooks codex --install), which vikix agent trusts for you in your own projects; OpenCode’s plugin holds the edit hook. Codex also gets a mode: vikix agent --use codex --mode supervised|autonomous|unrestricted, its sandbox narrowed to the folder in the first two and Vikix’s rules file and the hook on each step out of the sandbox letting a desk’s day (git on its branch, the tests, vikix, under a timeout or not) out without a prompt once Codex asks to; at a desk and in your home folder (Super+a’s Agent here) the house default, mode=autonomous in ~/.config/vikix/office, applies when nothing is typed; in a repository that isn’t a desk Codex runs as your own settings say. The modes are described in Agents at work.
Agents run side by side, each in a terminal of its own, and a row of windows all called "Alacritty" doesn’t say which is which. vikix agents (and Super+m → AI → Agents: who is running, and go to one) lists them: which agent, its folder with branch and uncommitted files, its workspace, how long, and what it is doing. vikix agents desk PROJECT TOPIC makes a desk, a git worktree of its own, vikix agents worker TOPIC "..." puts an agent to work at it on a workspace to itself, and the house rules say what happens when two agents reach for one file. All of it, with examples, is its own page: Agents at work.
Grok Bot is xAI’s agent desktop app: Bots that work on a cloud computer of their own, and may, with your approval, run commands on this one. Give it a research brief and keep its answer in Vikix for review. vikix grok keeps a local task queue: you choose a brief, paste the task’s prompt into Grok Bot, and approve its local commands to collect the brief and return a result. Keep its Execution on Local Computer setting (Settings → General → Bot) at Ask every time, or Never allow while you have no reason for it to touch this computer.
vikix add grok-bot # the libraries its program loads (packages/optional/grok-bot.list), then vikix grok install
xAI publishes Grok Bot for Linux as a .deb, an .rpm and an AppImage, and Void has the tools for none of them; there is no Flatpak. So Vikix asks xAI’s release list for the current .deb, downloads it, and unpacks its app folder with Python alone into ~/.local/share/vikix/grok-bot, with ~/.local/bin/grok-bot linked to the program, a launcher entry for the palette, and its icons: nothing of the package runs while it is put in, nothing needs root, and nothing outside your home changes (the package’s own install script would add an apt source and a setuid helper; Void’s kernel gives Electron the user namespaces it uses instead). At the first start it signs you in in your browser. Unpacked this way it can’t update itself, and its Check for Updates finds nothing: vikix grok install again brings the release of the day (it says so when you have it already; --force puts it in again). vikix grok status shows the version you have. vikix remove grok-bot (or vikix grok uninstall) takes the program away and leaves its sign-in and settings, under ~/.config, and the task queue.
Open it from Super+m → AI → Grok Bot: open (shown when ~/.local/bin/grok-bot is there), or from the palette. The neighbouring Grok Bot: list tasks opens the queue in a terminal.
On a plain Void, without Vikix, the same works by hand, since nothing in it is Vikix’s. The release list is JSON naming the current .deb (linux-arm64 for an ARM machine); a .deb is an ar archive with the files in data.tar.xz, and bsdtar, one small package, reads both. The program needs the libraries Chromium needs, which a desktop with a browser has already:
sudo xbps-install bsdtar gtk+3 nss libXScrnSaver libXtst at-spi2-core libsecret alsa-lib mesa libxkbcommon libdrm libnotify libuuid xdg-utils url=$(curl -fsSL https://api2.cursor.sh/updates/api/download/stable/linux-x64/sand | sed 's/.*"debUrl":"\([^"]*\)".*/\1/') curl -fsSL -o /tmp/grok-bot.deb "$url" mkdir -p ~/.local/share/grok-bot ~/.local/bin bsdtar -xOf /tmp/grok-bot.deb data.tar.xz | tar -xJ -C ~/.local/share/grok-bot --strip-components=3 './opt/Grok Bot' ln -sf ~/.local/share/grok-bot/grok-bot ~/.local/bin/grok-bot
Then grok-bot starts it (~/.local/bin on your PATH). To update, run the same again; to remove, delete the two things it made. Leave the package’s own install script be: it is for Debian (an apt source, a setuid chrome-sandbox for kernels without user namespaces, which Void’s has).
Start with a text file containing the task, the sources it may use, and what a useful answer should include. For example, brief.txt could ask for a comparison of two libraries using their public documentation. Then, in your terminal:
task=$(vikix grok new "Compare the libraries" --brief brief.txt --project vikix) vikix grok prompt "$task"
Copy the printed prompt into Grok Bot. Creating a task sends nothing; when Grok runs vikix grok claim ID on your local computer, the approved command gives it the chosen brief and marks the task running. The project name is a label for your records, not permission to read that project’s files. --brief - reads the brief from standard input instead of a file.
The prompt explains how to return the answer with vikix grok result ID --file -. The answer is JSON with exactly four fields:
{
"summary": "The findings, including anything needed to assess them.",
"sources": [],
"artifacts": [],
"questions": []
}
summary is text; the other fields are lists of strings. Sources and artifacts are HTTP or HTTPS links without embedded credentials. Put the findings in the summary so an answer does not depend on a file in Grok’s cloud computer. Links are optional; Vikix does not fetch or execute them. vikix grok instructions prints the full handoff instructions on their own.
When the answer arrives, the task enters review and Vikix sends a desktop notification. Review it in your terminal:
vikix grok list --state review vikix grok show "$task" vikix grok accept "$task"
If you opened a new terminal, replace "$task" with the ID from list. Accepting records that you reviewed the answer; it does not apply code, download files or start another agent. You can give the reviewed findings to a worker at a desk for follow-up work.
If Grok cannot finish, it records the reason with vikix grok fail ID 'reason'; show keeps the brief, reason and history readable. Create a new task to retry. To withdraw a task, use vikix grok cancel ID. Cancellation closes the local record; it does not stop work already running in Grok Bot. Sending the same result again is safe, but a different result cannot overwrite one already returned.
vikix grok status shows whether grok-bot is on your command path, the queue’s location and counts by state. It does not test your account or the connection to your computer. This bridge uses approved local commands, with no remote task API or Office worker. Its instructions set the scope of the handoff; they do not sandbox Grok’s other local commands.
For the curious: the queue is a private SQLite database at ~/.local/share/vikix/grok/tasks.db by default (XDG_DATA_HOME changes the data root; VIKIX_GROK_DIR chooses the queue directory directly). list --json and show ID --json provide structured records for your own tools. Claims are atomic, so two Bots cannot both claim the same queued task.
Programs find an API key in a variable such as ANTHROPIC_API_KEY. Don’t put it in ~/.bashrc: that file’s history keeps every version for ever. Vikix has a safe place instead:
vikix ai key set anthropic # paste the key; it isn't shown vikix ai key list # the names, and a short fingerprint, never the key vikix ai key remove anthropic
Other names work too: openai, gemini, openrouter, mistral, groq, github, and more (vikix ai help lists them).
exec bash; programs the desktop starts get it at the next login.
VIKIX_AGENT_API_KEY=1 vikix agent.
vikix ai key set sk-ant-...): it would stay in your shell’s history. set refuses it and tells you how to clear it.
vikix doctor looks for keys left in the wrong place, such as ~/.bashrc, and says how to move them.
The keys are kept in ~/.config/vikix/secrets/, which only you can read. The README has the details.
A local model runs on this laptop: no account, no cost, and nothing leaves the machine. It’s smaller and slower than Claude, but good for questions, writing and small bits of code, and it works offline.
vikix ai setup # once: installs Ollama, about 100 MB, no password needed vikix ai models # choose a model to download
vikix add local-ai does the same as vikix ai setup, and vikix remove local-ai the same as vikix ai uninstall: local AI is one of the features.
vikix ai models (or Super+m → Local AI: choose a model) looks at this laptop’s memory and says how each model will run here: fast, well, or slowly. Bigger ones it doesn’t offer for download, but every installed model stays visible with a ✓. Installed models outside the catalog show an unknown size and speed estimate. Good first choices:
llama3.2:3b (2 GB), for questions and writing
qwen2.5-coder:3b (1.9 GB), for code
On a laptop without a graphics card, a 3B model takes a few seconds to load, then about ten seconds to write a couple of sentences.
On a machine whose graphics chip shares the main memory (AMD’s Ryzen AI Max, with 128 GB), the chip runs the models instead of the CPU: many times faster, and big ones too. Ollama leaves such a chip out unless asked, so Vikix asks when the chip may take 32 GB or more; graphics= in ~/.config/vikix/ai makes that on or off (vikix ai restart applies it), and vikix ai status says whether the chip is used. The picker then offers the big models, rated by the parameters at work on each word rather than their size: gpt-oss:120b (65 GB) answers at 51 words a second there, since only 5 billion of its 117 work on each word (measured on a Ryzen AI Max+ 395, 2026-10-19: Vulkan 51, ROCm 35, since ROCm sees 61 of the chip’s 65 GB and leaves part of the model on the CPU; so Vulkan it stays, and vikix ai setup keeps only that library). Vikix sets a context of 32k words on the chip, since Ollama’s own choice on so much memory is the model’s longest, 4.6 GB more for gpt-oss:120b, and that once took the whole of the chip’s memory: the X server, refused its share, ended the session (three times that day). A request may still ask for more, and the 120B leaves the desktop only about 3 GB of the chip’s memory while the chip has the kernel’s half. A model that doesn’t fit the chip’s memory whole runs partly on the CPU, at the CPU’s speed.
The kernel lets such a chip take half of the memory at first (on a 128 GB machine, 60 GB shared on demand beside the 4 GB the firmware sets aside). vikix ai share says how much it may take; vikix ai share most lets it take all but 16 GB (a kernel setting in /etc/default/grub, written through sudo, then update-grub), which is what the biggest models need, and vikix ai share half puts the kernel’s half back. Either applies at the next boot, and vikix ai setup offers the first on such a machine, asking before it changes how the machine boots. The picker follows: after that boot it offers the models that fit the new share, nemotron-3-super:120b among them.
vikix ai chat # talk to it; /bye or Ctrl+D leaves
Or Super+m → Local AI: talk to a model.
While a model is loaded, the bar says ai. It holds a few GB of memory, and lets go of it after five minutes unused. To free it now: vikix ai stop, or Super+m → Local AI: unload the model.
vikix ai status # running? which model is loaded, and for how long vikix ai list # the models you have vikix ai remove llama3.2:3b vikix ai restart # start Ollama again (after changing graphics= in ~/.config/vikix/ai) vikix ai uninstall # take Ollama away (add --models to delete the models too)
The models are in ~/.ollama/models. They’re big, so backups leave them out; you can download them again.
The checkout includes translate-guides-to-epo.sh, a standalone Bash/Python 3 script that sends the Markdown files under docs/ to your local Ollama model. From the checkout, preview the files, then translate:
./translate-guides-to-epo.sh --dry-run ./translate-guides-to-epo.sh
Ollama must already be running and the model installed. The default model is translategemma:27b (or the exported OLLAMA_MODEL); the default server is http://127.0.0.1:11434. Nothing is downloaded automatically. The output goes to ~/vikix-guides-eo, outside the checkout, with the same relative filenames. Existing translations are skipped so an interrupted run can resume; use --overwrite to translate them again. --source, --output, --host and --timeout override those settings; --help lists the options. Keep the source and output directories separate. TranslateGemma requests include the source English (en) and target Esperanto (eo) in the prompt, following the model’s prompt format.
A failed request stops the script with an error and keeps the previous output for that file. Large documents are split into text chunks of at most 12000 characters at blank lines (or line boundaries in long paragraphs), with a 32k context and an HTTP timeout of 1800 seconds per request. Fenced code blocks are copied directly, without sending them to the model. A single prose line larger than the chunk limit needs splitting by hand. Each file is saved only after all its chunks succeed. Raw model replies with reasoning channels or a leading <think> block are reduced to the final answer; missing or empty final answers stop the run. If a previous translation contains those reasoning markers, a normal resumed run reports it instead of skipping it: use --overwrite to regenerate it. Review the result: model output can change commands, formatting or meaning despite the prompt. This produces Markdown copies; it does not install them. Vikix ships the Esperanto edition in docs/eo/: 40-config builds vikix-eo.info and the HTML pages under guide/eo/ from it, alongside English. The Help menu and Emacs’s Info directory offer both editions; the HTML guide links between them. To update the shipped translation, review the output before copying it to docs/eo/, repair links to translated headings, and run tests/run.sh info. Keep docs/eo/commands.md as the short introduction: its build appends the current generated English command reference automatically. Screenshots and diagrams are shared with English. docs/eo/TRANSLATION.txt records the source and the review status.
llm on the command line ¶llm sends text to a model and prints the answer, so it fits in a pipe with other commands. The same command works with a local model and with Claude.
vikix ai llm # once: install it (or vikix add llm) cat notes.md | llm "summarise this" git diff | llm "write the commit message" llm "what does chmod 750 mean?" llm -m llama3.2:3b "..." # a local model, by name llm -m claude-sonnet-5 "..." # Claude, with your API key
Its default model is a local one if you have one, otherwise Claude if you’ve set an Anthropic key. To choose: vikix ai llm --default MODEL.
Everything you ask is logged, Super+i’s and Super+F10’s questions too: vikix ai log shows the last ten questions and answers, newest first, vikix ai log 30 more, vikix ai log makefile those with a word (Codex’s answers aren’t there: it answers without llm). Underneath, llm logs -n 5 shows the last five, and llm logs off stops the logging.
note ¶note answers questions from a folder of Markdown, an Obsidian vault say, in any terminal. vikix add notes installs it (and local AI, which it needs), then:
note index ~/General --skip Admin,Readwise # the first time: about five minutes a thousand notes note ask "what did I write about runit?" # the answer, and the notes it came from note index # after changes, from anywhere: only what changed
note find "..." lists the nearest notes without an answer, and note status shows the folder, the index and who answers.
It works in two steps. note index cuts each note into passages at its headings and turns each into an embedding, a list of numbers standing for its meaning, with a small model on the laptop. note ask does the same with the question, takes the six nearest passages, and has a model answer from them alone, naming the notes. The list of notes printed under each answer lets you check it: a small local model sometimes answers from the wrong one.
Who answers follows Super+i (vikix ai use local or claude); note ask --claude or --local chooses for one question. Locally, nothing leaves the laptop. With Claude, the six passages found, never the whole folder, go to Anthropic, and the answers are much better. Folders you’d never send anywhere, leave out with --skip: they’re never even read. Hidden files and folders (.obsidian, the .#note.md Emacs leaves while a note is unsaved) never are either.
Your choices are in ~/.config/vikix/notes: folder=, skip=, and embed=, the embedding model. nomic-embed-text (after ollama pull nomic-embed-text) finds better passages than all-minilm but is slower; changing it reads every note again. The index is ~/.local/share/vikix/notes/index.db, in a folder only you can read; vikix notes uninstall --index deletes it.
~/dev/ai ¶To see how the rest works, or to build something of your own, ~/dev/ai has four small programs to read, run and change. Each has a README and make run:
claudeWhat it shows: One question to Claude: ask.py with Anthropic’s Python library, ask.sh with curl and jq, one HTTP request
What it needs: An Anthropic key (vikix ai key set anthropic)
localWhat it shows: The same question to a model on the laptop, through Ollama’s API
What it needs: vikix add local-ai and a model
embeddingsWhat it shows: Sentences turned into numbers, kept in SQLite (sqlite-vec), the nearest to a question found by meaning
What it needs: Ollama, and make setup (all-minilm, 46 MB)
ask-notesWhat it shows: A folder of Markdown notes, searched and answered from
What it needs: The same, and a model to answer (or a key)
ask-notes is note made small, to read and change; for everyday use, note is the one. It works on your own notes too:
cd ~/dev/ai/examples/ask-notes make setup # once make index NOTES=~/General SKIP=Admin,Readwise # about five minutes a thousand notes; later, only what changed make ask QUESTION="What did I write about runit?" # the local model answers, naming the notes make ask QUESTION="..." CLAUDE=1 # Claude answers: those six passages go to Anthropic
The index, notes.db, stays in that folder and holds passages from your notes: make clean deletes it. Hidden files and folders (.obsidian, the .#note.md Emacs leaves while a note is unsaved) are never read, and SKIP leaves out the ones you’d never send anywhere.
The small models are quick but miss things: all-minilm sometimes ranks the wrong note first, and a 3B model answers from whatever it’s given. Each answer lists the notes it was given, so you can check. EMBED_MODEL=nomic-embed-text (after ollama pull nomic-embed-text, then index again) finds better passages, and CLAUDE=1 answers better.
The Python ones name their libraries at their top, pinned (# /// script), and uv run fetches them the first time, so nothing is installed for the whole machine.
Select some text anywhere, in a web page, an email, a terminal, and press Super+i. A menu asks what to do with it:
Type a question about the text (or select nothing, and ask anything)
The text with its mistakes fixed, on the clipboard
The same thing said more clearly, on the clipboard
Into the language you pick, on the clipboard
What it means; for an error message, how to fix it
What goes on the clipboard is also shown in a notification; paste it where you want it. Proofread also lists what it changed: small models sometimes "correct" what was right. A short answer comes as a notification, a longer one in a terminal (q closes it). The text is what you last highlighted, even if it’s no longer highlighted on screen; only when there’s none does it use what you copied. The notification while it works shows the start of the text it took.
It needs llm (vikix ai llm) and a local model. A small one takes some seconds: about 10 for a sentence to proofread or explain.
To switch, pick Use Claude instead (or Use the local model instead) at the end of the Super+i menu, or type vikix ai use claude or vikix ai use local. A third choice, Codex, and a fourth, a cloud service such as OpenRouter, are below. The choice is kept in ~/.config/vikix/ai, which starts as:
use=local # free, offline, the text stays on this laptop model= # empty: llama3.2:3b, or your first local model translate_model= # Translate only; empty: model= translates too languages=English Esperanto French Spanish Arabic Hindi
Translate can have a model of its own, translate_model=, under the same use= as the rest: translate_model=translategemma:27b (vikix ai models gets it; a model made for translation, and poor at the other four) leaves Ask, Proofread, Rewrite and Explain on model=. vikix-ask which translate says which one Translate has.
For better answers, above all translations into Esperanto, which small models get wrong, use Claude. Then each use costs a little and the text you selected goes to Anthropic, so it needs your key first: vikix ai key set anthropic. Super+i never switches to Claude by itself, and its menu always names the model and where the text goes.
If you have Codex (vikix add codex) and are signed in (codex login), it can answer Super+i too: vikix ai use codex, or Use Codex instead at the end of the menu. It uses Codex’s own sign-in, your ChatGPT account, so it needs no key, and the text you selected goes to OpenAI. The model is the one Codex is set to (~/.codex/config.toml), or the one model= names. An answer takes some ten seconds.
For quicker answers, name a faster model and a lower effort (how hard it thinks) in ~/.config/vikix/ai. They hold for Super+i and Super+F10 only, so Codex in a terminal stays as you set it:
use=codex model=gpt-6-luna # Codex's /model lists them effort=low # low, medium or high; empty: Codex's own setting
That brings an answer down to five or six seconds, and not much lower: every answer carries Codex’s own instructions with it. model= is one line for all three choices, so empty it before vikix ai use claude or local; effort= is Codex’s alone.
Codex is an agent, not a chat model: by itself it runs commands, searches the web and reaches the apps connected to your ChatGPT account, such as mail and GitHub. The text you select can come from any page, and a page can hold a line written for an agent. So Super+i asks Codex with all of that switched off, read-only, in an empty folder, and keeps nothing of the session: such a line finds nothing to act with. If a later Codex no longer knows one of those switches, Super+i says so and gives no answer, until vikix update brings the new list.
Super+F10 follows, one question at a time: Codex doesn’t carry the conversation on. The editors’ chats and note know only local and Claude, and stay on the local model while Super+i is on Codex.
A fourth choice, vikix ai use cloud, is any service that speaks OpenAI’s API: OpenRouter unless you say another. One key, hundreds of models, paid per use; the text you select goes to that service and on to whoever hosts the model, so this is the choice for a model Anthropic doesn’t offer, or a cheaper one. Set up once:
vikix ai key set openrouter # the key from openrouter.ai/keys; becomes OPENROUTER_API_KEY vikix ai use cloud # Super+i, the voice key, the editors' chats and note follow
In ~/.config/vikix/ai, three lines are the cloud’s alone; model= and translate_model= stay the local model’s (or Claude’s), so switching to the cloud and back loses nothing:
use=cloud cloud_url= # empty: https://openrouter.ai/api/v1; any OpenAI-compatible address cloud_key= # empty: openrouter; another key's name from vikix ai key list (groq, mistral, deepseek, xai ...) cloud_model= # empty: openai/gpt-4o-mini; the service's own name (openrouter.ai/models), say anthropic/claude-sonnet-4.5
So Groq is cloud_url=https://api.groq.com/openai/v1, cloud_key=groq and one of its models in cloud_model=, after vikix ai key set groq. For a model of your own in the cloud, a card rented by the hour or a server that wakes when asked, and what each way costs and keeps: Your own model in the cloud. Only an https address is taken, or http on this machine itself (a proxy of your own). The menu at the end of Super+i offers Use the cloud service instead once the key is there, and says where the text goes.
Through llm, the service is the model vikix-cloud, an entry Vikix keeps in ~/.config/io.datasette.llm/extra-openai-models.yaml (yours there stay): llm -m vikix-cloud "..." in a terminal needs the key as OPENAI_API_KEY for that call, since llm reads an OpenAI-compatible model’s key from there: OPENAI_API_KEY=$OPENROUTER_API_KEY llm -m vikix-cloud "...". Super+i, the voice key and note hand it over that way themselves, for one call at a time: the key is never on a command line, and never copied into llm’s own key file.
Vikix’s Neovim has CodeCompanion, under Space A:
Space A cA chat beside your code, on the model Super+i uses: a local one, Claude, or the cloud service
Space A qAsk about the selection (or the file), or ask for a change to it
Space A aAdd the selection to the chat
Space A gA chat with your agent (the one Super+a starts), which can read and change your files
Space A tYour agent in a terminal inside Neovim
Space A pEverything else CodeCompanion does
The chat follows vikix ai use: local (a model on this laptop, vikix ai setup first) or claude (your key: vikix ai key set anthropic). A model set with model= in ~/.config/vikix/ai is used here too. On a laptop’s CPU, a local model’s first answer takes minutes, because it reads CodeCompanion’s instructions first; Claude answers in seconds. The chat’s top line says who answers, before you type: the model, and whether it’s on this laptop or sent to Anthropic (or which agent). In the chat, ga changes the model or the agent for that chat.
The agent in Space A g is started by vikix agent --acp, so it’s the same as Super+a’s: the guide, no API keys, and a snapshot first, so vikix changes shows what it did and vikix undo takes it back. It signs in with its own login, the one it uses in a terminal. Claude Code and Codex need their adapter, which vikix agent --install claude adds (running it again for an agent you have only adds what’s missing). Space A t runs vikix agent itself, so Aider works there too.
Nothing starts or connects until you press a key. When something’s missing (a key, Ollama, the agent or its adapter), the key says what to type, and does nothing else.
Emacs’s config has gptel for the chat and agent-shell for your agent, and Vikix sets both up:
C-c gA chat, on the model Super+i uses: a local one, or Claude. With a selection, the chat starts from it
C-c Ggptel’s menu: another model for this chat, and what to send. Claude and your local models come first; one of the config’s own (OpenAI, Perplexity) shows only when its key is there
C-c aA chat with your agent (the one Super+a starts), which can read and change your files. It goes back to this project’s chat when there is one; from a folder without one, it asks (New shell starts one here; the others go to a chat in another folder). C-u C-c a always starts a new one
C-c AYour agent in a terminal inside Emacs
The chat follows vikix ai use and model=, as Neovim’s does, and Emacs reads them again at each C-c g, so a change reaches an Emacs that’s already open. A model you pick in the menu stays until you change that file. The agent starts through vikix agent --acp, with the same rules as in Neovim, above; C-c A runs vikix agent itself, so Aider works there too. When something’s missing, the key says what to type. Neovim and Emacs compares the two.
MCP is how an AI agent is given tools of its own. vikix mcp register gives your agent a fixed set of them for this desktop, so it can look at it and make small changes without writing commands.
Why, when the agent can run commands anyway? Each command needs your yes. These tools are few, checked, and easy to take back, so you can allow them once: in Claude Code, answer "always allow" for a vikix tool (or allow mcp__vikix__*). Then the agent looks at the desktop and switches a theme or a window without asking each time, while every other command still asks.
vikix mcp register # for Claude Code and Antigravity CLI, then restart them; it prints the lines for Codex, Gemini CLI and OpenCode vikix mcp status # is it on, with which tools, the servers running (and their version), the last calls vikix mcp tools # what it offers vikix mcp unregister # take it away
The workspaces and their windows (a strip’s columns too, in order), the screens, the theme
Every key Vikix binds, and what it does
The desktop’s rules (each one’s number, on or off, where it’s written, how often it ran), and for a window you name, which rules ran for it and which match it but haven’t. Nothing is switched or run
What the desktop did lately and what made it: a key and its command, a rule and its window, the menu, an agent; each with where it is written. For "why did my window move?"
The agents at work on the desktop, the asking one among them: each one’s folder, branch, uncommitted files, workspace, how long, and what it is doing. So an agent can see another is at work in a folder before it changes files there
Reads or updates a desk’s handoff record: task, status, summary, next, checks with freshness, sessions
What vikix doctor, vikix history, vikix changes, vikix theme and vikix version say
Finds and reads the documents on this machine, the ones Super+F2 searches: these guides, man pages, your projects’ documents and PDFs, your notes, the entries of Zeal’s docsets; a link to the web is given as its address alone, never fetched. So the agent can answer from the man page, not from memory. Your own documents (own= in ~/.config/vikix/docs) stay closed to it, as they do to vikix docs ask run by an agent, unless an agents= line opens a folder
Finds and reads what your plugins kept (vikix records): flight searches, meetings, your Claude plan’s use. It can’t add or change a record
Every change made to your files through Esploro (vikix add esploro), newest first, in words, and whether it was undone. For "where did that file go?". Nothing is undone here: that stays yours, in Esploro’s Edit → Changes…
Shows a notification, marked as the agent’s
Records your settings before a change
Small changes, easily undone
The desktop’s commands the agent may run by name: switches and moves put back as easily as done (do not disturb, night light, gaps, title bars, focus left ...)
Runs one of those, as its key would. The desktop refuses any other command, and says why
Proposes a plan of changes to your files (copy, move, rename, new folders, the Trash, tags), which waits for you: checked whole first, then shown in Esploro with why, where only your Apply runs it, and undo takes it back. Without Esploro there is nowhere to show it, and the tool says so
Proposes a rule for the desktop, which waits for you: checked first to be only a rule (verbs and plain values, no Lisp of its own), then shown under Super+m → Rules, where you add it to your rules.lisp or drop it (Rules)
Two more are off unless you turn them on, because they can change a lot: vikix mcp register --allow-eval adds eval (Lisp in the window manager, through the door, below) and cuis_eval (Smalltalk in the Cuis image, through the image’s own walker, below) and --allow-undo adds undo (your settings back one snapshot). vikix mcp register again, without them, takes them away. They’re a convenience, not a lock: an agent that may run commands could run vikix eval itself, and that goes through the door too.
An agent’s Lisp is checked before it runs. Whatever road it takes, vikix eval at the agent’s own shell or the MCP server’s eval, the form is read without running anything (nothing of #.), then walked: every function it calls is looked up in one list, of what reads the desktop (the windows, the workspaces, a key) and what is put back as easily as done (a workspace switch, a move, a theme, the commands run_command may run). A form made only of those runs. One that runs a program, touches a file, defines or changes code, sets a global of the desktop’s, waits for input or ends the session is held instead: nothing of it runs, the agent is told why (and that it mustn’t try another way), and a notification says an agent sent Lisp the door held. Super+m → Door lists what waits: pick one to see it, run it as you, or drop it. The door also counts, beside the keys (vikix used): the names on its list a passing form calls, the name that held a form, and whether you then ran or dropped it, names only and never a form’s text. vikix door used reads the count out, and it is what says whether the list is right: a name never called can go, one held often and always run is wanted. The same from a terminal:
vikix door # what waits: when, which agent, why, the form vikix door run 1 # run it, as you vikix door drop 1 # forget it vikix door check '(form)' # would it pass? "ok", or why not vikix door allowed # every name a form may call
A function of your own user.lisp that an agent may call goes in ~/.config/vikix/door, one name a line. Your own vikix eval at a terminal is yours and isn’t checked; only a shell under an agent (Claude Code, Codex, OpenCode, Gemini, Aider, Antigravity) is an agent’s, and a script of Vikix’s run by the agent (vikix theme vikix-light) sends Vikix’s Lisp, not the agent’s. A form that reaches a shell, a file, eval or the system is also written in ~/.local/state/vikix/errors/, so vikix doctor and vikix debug keep the attempt. Ten forms wait at most; past that an agent is refused until you have looked.
The Cuis image has a door of its own (vikix eval --cuis; the feature cuis), and an agent’s Smalltalk is walked there the same way, in the image: every global it names and every message it sends is looked up in the walker’s lists (VikixWalker allowedGlobals and allowedSelectors in the image; your own names from the same ~/.config/vikix/door), what reaches a program, a file, a socket, the compiler or the system is refused, what defines code, sets a global or waits is held, and so is anything off the lists. A held expression waits in the image, ten at most: in a Workspace there, VikixServer held lists them, VikixServer runHeld: 1 runs one as you, VikixServer dropHeld: 1 forgets it; the agent is told why, and a notification says an agent sent Smalltalk the door held.
It works only for the agent that starts it: nothing listens on the network. Everything the agent asks of it is checked first (a workspace that exists, a theme you have). Secrets are taken out of what it hands back (changes shows your files’ differences). Every call, refused ones too, is written in ~/.local/state/vikix/mcp.log, yours alone: the tool, whether it worked, and its arguments. Its notifications start "Agent:". After vikix update it runs the new version by itself, without the agent reconnecting.
Press Super+F9 and speak. Press Super+F9 again, and a moment later what you said is typed into the window you were in: two or three seconds for a sentence, about ten seconds for a minute of speech. It’s also put on the clipboard, in case that window didn’t take it. If you move to another window while it’s written down, it isn’t typed there: it’s only put on the clipboard, and a notification says so. Super+Shift+F9 stops without typing anything. While it listens, the bar says mic, in red.
It’s a press, speak, press: StumpWM sees a key go down, not come up, so holding the key while you speak isn’t possible (a held key’s repeats count as one press).
It listens for five minutes at most. Then it stops, says so, and the next Super+F9 types what it heard. A space follows each dictation, so the next one doesn’t run into it.
To set it up, once (a few minutes, no password):
vikix add dictation # or: vikix dictate setup
That builds whisper.cpp for this computer, into ~/.local/opt/whisper.cpp, and downloads its model (150 MB) and a voice detector (1 MB) into ~/.local/share/vikix/whisper/, each checked against its published checksum. Everything runs on the laptop: your voice never leaves it, and the recording is deleted once it’s written down.
English, or many languages. The model it starts with, base.en, knows English only, and writes down a sentence in about a second. small knows many languages (French, Spanish, Arabic, Hindi and more; not Esperanto, which whisper doesn’t know) and takes a few seconds. large-v3-turbo is whisper’s best, the large model made several times faster, with the same languages: it hears accents and names that the others get wrong, takes 1.6 GB, and on a laptop with many cores still answers in a few seconds:
vikix dictate models # which is used vikix dictate models small # many languages (490 MB) vikix dictate models large-v3-turbo # the best, many languages (1.6 GB) vikix dictate models base.en # back to English
Silence and noise aren’t typed. The voice detector passes only speech to whisper, and whisper’s notes about sounds, such as "(music)", are left out: anything it writes in brackets goes, so a spoken aside in brackets would too. A very short clip (a second or so) can come out as a word or two nobody said.
What stays afterwards: the recording is deleted once it’s written down. The text stays where it was typed, on the clipboard (so in its history, Super+c), and in the "Typed" notification (Super+Shift+n shows earlier ones).
vikix dictate status says whether it’s set up, and with which model. vikix dictate file talk.wav prints what a recording you already have says, without typing it anywhere.
To take it away: vikix remove dictation (the models stay; vikix dictate uninstall --models removes them too).
Dictation types what you say. Voice sends it to the AI instead, and the answer comes back aloud.
The chat model answers: the one Super+i uses (local, Claude, or Codex, which takes each question on its own). You hear the answer and see it in a notification (a long one opens in a terminal)
It goes to the agent, Claude Code, in a terminal of its own. Claude’s replies are read aloud
Stop the talking
It remembers the conversation. Ask "What’s the capital of France?", then "And how many people live there?", and it knows you mean Paris. After five quiet minutes the next question starts afresh; Super+m → Voice: a new conversation does it at once. With the agent, every question after the first goes to the same terminal, so it carries on there too; close that terminal to start over.
It stops talking when you start. Pressing Super+F10 or Super+F11 to speak stops it at once, so the microphone doesn’t hear it.
To set it up, once (a minute, no password):
vikix add voice # brings dictation and llm, if they aren't here
That installs Piper, a voice that runs on this laptop, and downloads a voice for it (60 MB, checked against its published checksum).
Where your words go. The listening is dictation’s: on this laptop. A question to Super+F10 goes where Super+i’s text does (nowhere, with a local model; to Anthropic, with Claude; to OpenAI, with Codex: vikix ai use). A question to Super+F11 goes to the agent’s company, as with Super+a. The answer is spoken on this laptop.
Your choices are in ~/.config/vikix/voice:
vikix voice voices # which voice: lessac, amy (American), alan (British) vikix voice voices alan # switch (it downloads the voice)
Set speak=no there to only see the answers, or idle= to change the five minutes. vikix voice say "any text" reads anything aloud.
Only Claude Code’s replies are read aloud: with another agent (vikix agent --default), Super+F11 still sends your question, and the answer stays on the screen.
To take it away: vikix remove voice (the voices stay; vikix voice uninstall --voices removes them too).
It says what’s missing: an agent to install, a key, a local model
Run vikix agent in a terminal to see the message
Run claude once in a terminal and finish the login there
vikix doctor: it checks that vikix eval works
llm has no model, asks for a key, or can’t connectDo what it says: vikix ai llm, a model with Super+m → Local AI: choose a model, or vikix ai setup
Highlight the text (or copy it), then press Super+i again
vikix add dictation, once
vikix voice status; speak=no in ~/.config/vikix/voice turns the voice off; check the volume and the output in pavucontrol
vikix add voice, once
The microphone: pavucontrol, Input devices, check it isn’t muted and moves when you speak
It types where the focus is when you press the second Super+F9; the text is on the clipboard too
Wait for its answer: one at a time
vikix ai models gets it, or empty the line it names (model= or translate_model=) in ~/.config/vikix/ai
vikix ai key set anthropic, or back to local: vikix ai use local
The notification says why; a local model: vikix ai status
vikix add codex, then codex login; or back to local: vikix ai use local
~/.config/vikix/ai looks wrongFix that line (use=local, use=claude or use=codex; model= a name from llm models, or one of Codex’s; effort= a word such as low), or delete the file: the next Super+i writes it afresh
It takes the last highlight before the clipboard: highlight the text you mean
note says "no folder yet" or "no index yet"note index ~/Notes once (your folder; --skip A,B leaves folders out)
note says the index needs local AI, or can’t reach OllamaThe index is made on this laptop: vikix add local-ai, then vikix ai status
note ask answers from the wrong noteThe notes it was given are listed under the answer. note ask --claude answers better; embed=nomic-embed-text in ~/.config/vikix/notes finds better passages (after ollama pull nomic-embed-text; the next note index reads every note again)
vikix mcp register, then restart the agent; vikix mcp status says whether it’s on (see When something breaks)
vikix changes, then vikix undo