Watch the film
How it works
Quickstart
What's new
varyzai.com
You open Claude Code, Codex or any MCP agent and give it a task. Varyz briefs the agent on your preferences, learns from existing AI conversations, answers from what you already decided, and checks your definition of done before the agent reports back. Routine implementation choices stay with the agent. Necessary questions reach you together as short choices with quick answers. The goal is output you do not have to correct.
See it in 35 seconds
Two new chats in Claude Code get the same question at the same moment. Last session
you asked Claude to leave SEO until you pick a base URL. Without Varyz it sees the
code, but not the plan. With Varyz it knows what comes next.
Watch the film with sound.
Without Varyz, and with it
| Without Varyz | With Varyz |
|---|---|
| Every new chat starts from zero. You explain your stack, your standards and your plans again. | The agent is briefed before it starts: how you work, where this project is going and what you already decided. |
| The agent guesses at choices that are yours to make, and you correct it afterwards. | It answers from what you told it before and asks only what it does not know, as short choices you answer together. |
| "Done" means whatever the agent thinks it means. | It checks your definition of done (tests, lint, favicon, phone width, ...) before it reports back. |
| What you taught one agent stays in that one chat. | Claude Code, Codex and Cursor share the same preferences, on every project. |
How it works
- It learns from you. Setup reads the past AI chats you choose and shows you
what it noticed. You keep a rule, reword it or drop it. Silence never becomes a
preference. - It briefs your agent. When you give Claude Code, Codex or Cursor a task, the
agent gets your rules for that kind of work, this project's vision and the choices
it should ask you about instead of guessing. - It checks before "done". Before the agent reports back, Varyz holds it to your
definition of done, item by item, so the work needs no correction.
When you correct an agent, it offers to remember the correction, so the next agent
already knows. The full loop is in The workflow.
Why it is different
- Local first, and free. Your archive and its search models stay on your
computer. Local Varyz is open source, needs no account and nothing in it is
metered. - Private by default. Sensitive and unclassified excerpts are withheld from cloud
models and detected credentials are redacted. The More privacy mode reads your
chats with a local model instead. Varyz Cloud is optional and asks before anything
is shared. - Works with the agents you already use. One setup connects Claude Code, Codex and
Cursor, and any MCP client can use the same server. - Keeps working while you are away. Say "keep working while I'm away" and the
agent collects its questions for your return instead of stopping. - Hands off before usage runs out. When an agent nears its usage limit, Varyz
saves where it left off, so the next agent picks it up. - Share your taste. Turn rules into a pack anyone can use in a chat, or offer
them as a paid plan with Varyz Expertise.
New in 0.1.9
Removing Varyz on a Mac now works in one go while Claude Code, Codex or another AI
app is open, and a local model server left by an earlier run is stopped too. Every
release is in the changelog.
If Varyz saves you a correction, a star helps other people find it.
Quickstart
Local Varyz is free and needs no account. Download the installer for Windows or
macOS (Apple Silicon or Intel) from varyzai.com/download,
or from GitHub Releases with its
checksums. The Windows installer is not yet signed, so Windows may show a warning;
see the code signing policy. To install from
source instead, with uv and Git installed:```powershell
uv tool install git+https://github.com/egrm07/varyz
varyz setup
Setup opens in your browser: choose where Varyz learns, connect your AI tools,
then select the sources it may read. While the search models download, setup
starts learning from your past chats by itself and shows what it notices; Stop on the
page stops it and keeps what it read. Wait for setup to finish and restart your
connected agent. Cloud is optional and has a separate sharing approval.
Already installed? Open **Varyz Setup** from the Windows Start menu, or run
`varyz setup` to change your choices. Existing data is kept.
Agent-assisted and double-click installation are described below.
## Availability and capabilities
Shared Varyz has a separate guest consultation resource and connector. An owner
reviews selected preferences before publishing; recipients can consult them and
ask questions using their own verified account (a free Varyz Cloud email sign-in is
enough). People hear about invitations and questions by email and desktop
notification. The implementation is disabled by default; pilot/native acceptance status and setup are in
Shared Varyz.
Shared also builds portable rule packs from descriptions such as "my design rules".
Review which rules to include and whether each applies across projects or only its
source project, then copy or save a file to send in any chat. The recipient needs no
account; their current choices and own rules take priority over the pack. This uses
already synced preferences and the existing Shared feature gate.
Agents can now leave concise local work checkpoints and retrieve a recorded
session's completed work, checks and blockers with `record_progress` and
`session_history`. These are agent reports, kept separate from your preferences.
For past conversations, `varyz sessions mine varyz --apply` builds cited local
reports in resumable batches; preview by omitting `--apply`. Agents can use
`mine_sessions` directly. No API charges or transcript uploads.
The live Cloud redesign uses **one project chooser** for confirmed preferences,
eligible history and concise work reports. Review uploads and removals before
approving; future eligible context in those projects then syncs automatically.
General preferences are included; general conversations require choosing General
context. Existing CLI category controls remain supported. The dashboard loads
preferences only when a project opens, in pages of 20; see `docs/CLOUD.md`.
Returning computers open the dashboard after checking their saved account link;
setup also has a small **Skip to dashboard** link. **Choose projects** reopens the
chooser when you want to change sharing.
See session progress for the contract and owner controls.
The Windows native installer bundles Python and dependencies, opens
consent-based setup in your browser, and retains your data on uninstall. See
Native installer. The main public download entry point
is varyzai.com/download; release files and checksums
are hosted on GitHub Releases. The initial Windows release is unsigned;
Windows may show a security warning or block it under stricter security policies.
Apple Silicon and Intel macOS PKGs are signed, notarized, stapled and
Gatekeeper-verified. Their signed payloads passed offline installation, repeat
installation and preserved-data removal on native runners. Real-Mac browser setup
and Installer GUI tests remain pending. See macOS installer.
Plugin bundles and the optional paid cloud implementation are described in
Plugin and cloud. Full hosted ChatGPT and optional Claude Cloud
packages combine confirmed preferences with approved synced project history,
timelines and retained-version comparisons. Local Claude Code/Codex packages use
the full local engine. See plugin capabilities for differences.
Cloud has **no free trial**. Its backend is deployed. Hosted marketplace approval
and phone interoperability remain separate from the local release.
The Cloud account page's **Connect this computer** button reuses a running local
installation for browser sign-in. Setup instructions remain available when local
Varyz cannot be reached. Then choose your projects, review a count-only preview,
and **Approve and finish** to sync and check Cloud retrieval in the same flow.
Prepared release bundles, existing-account activation and the native-agent launch
checks are documented in Local setup and
Journey checks.
## Other installation methods
Varyz is not on a package index yet. Its source repository is
egrm07/varyz. Install from a copy of the repository
or directly from GitHub; final native installer publication has separate release checks.
There are three ways to install it, and the first two need no terminal:
- **Ask your agent.** Open Claude Code or Codex in a copy of this repository and say
"install Varyz for me". The agent follows
Installing Varyz for the owner:
it runs the installer, which opens setup as a page in your browser, and asks you to
restart it when the page says you are done.
- **Double-click.** Open `scripts/Install Varyz.command` on macOS or
`scripts/Install Varyz.cmd` on Windows. It installs uv, then Varyz from the folder it
sits in, and opens the same page. The launchers are not signed yet. If macOS refuses to
open the file, choose **Open Anyway** in System Settings > Privacy & Security. If
Windows shows "Windows protected your PC", choose **More info**, then **Run anyway**.
- **A terminal.** `sh scripts/install.sh` on macOS or Linux,
`powershell -ExecutionPolicy Bypass -File scripts\install.ps1` on Windows.
The installers install the repository they sit in. Copied anywhere else, they install
from GitHub. This needs git. By hand, that is:```bash
uv tool install git+https://github.com/egrm07/varyz
varyz setup
varyz setup opens as a page in your browser, where the agents and data sources are tick
boxes: AI conversations start ticked, git history and documents unticked. GitHub is
connected there too, with the GitHub CLI's login in one click or a pasted token; the token
goes to your system keychain only if you run setup with GitHub ticked. Leave the
installer's window open (or the agent running it) until the page says you are done. Setup asks in the terminal instead with
--terminal, with any of the flags below, or where no browser can open (over SSH).
setup is the whole first run, and Varyz is fully working when it ends. It shows each
step as it goes, with a progress bar and the time left for the long ones (indexing, downloads), asks before it connects anything, and can be run again at any time. A download can be paused (Pause download on the page, Ctrl+C in the terminal) and carries on from what has arrived. A
second run keeps everything already there.
| Step | What it does |
|---|---|
| 1/6 Archive | Creates ~/.varyz/config.toml and the local database, unless they already exist. |
| 2/6 Daemon | Starts the local service that answers agents' questions (on 127.0.0.1). If another Varyz archive already uses the port, setup gives this archive its own port. |
| 3/6 Agents | Connects Claude Code, Codex and Cursor where they are installed. |
| 4/6 Data sources | Finds your AI conversation histories, git repositories and the project folder you run it in (never your whole Documents folder). It lists the exact paths, asks about each one, then indexes the ones you approve on this machine. |
| 5/6 Autosync | Turns on the background sync, which keeps the sources current (see varyz autosync below). It waits until a data source is connected. |
| 6/6 AI mode | More privacy readies qwen3.5:4b through Ollama and reads conversations locally. Lighter on your device skips Ollama/Qwen and uses the connected AI for conversation learning only when allowed; simple local classifiers remain available. |
Before the six steps, setup checks total and available memory, free disk, CPU
cores and GPU headroom. It automatically selects Lighter on your device on
constrained machines, including 8 GB Macs. Machines with comfortable headroom get
both choices. The conservative local thresholds are 16 GB installed memory
(allowing hardware-reserved memory), 8 GB currently available, 12 GB free disk,
four logical cores, and Apple Silicon or an NVIDIA GPU that can fit the model
while retaining 30% headroom. Unknown capacity selects the lighter mode.
These are admission thresholds, not measured speed guarantees.
Cloud conversation reading has its own permission, separate from data-source
access and anonymous analytics. Only eligible AI conversation excerpts are sent
by that reader; local documents, repositories and older file-derived rules are
excluded. Conversations can contain project data pasted into chats. Sensitive
and unclassified excerpts are withheld; detected credentials are redacted.
Without permission or a connected AI, learning waits and local fallbacks work.
More privacy disables the automatic cloud reader and starts a bounded local
reader after setup and as new conversation messages arrive. Both modes retain
the working agent's existing, separately granted context permissions.
Terminal setup supports --ai-mode local or --ai-mode conversations.
--cloud-conversations explicitly permits the conversation reader; --yes
alone does not. The selected mode and permission survive setup reruns.
It ends with the Data sources table: every source, whether it is connected, how many
items it holds and when it last synced. After that comes GO (agents are briefed
from this archive) or NO-GO with the reason. When an agent was connected and your
past messages to AI agents are indexed, the page ends with one last step: restart the
agent and give it any task. On its first use of Varyz the agent tells you what happens
next and starts a background reader on a smaller model (on by default; say "not now" and
it asks when, and Varyz reads then), which reads those messages for each project's aim, your taste, how you
like work done and what you already decided. A rule it found with strong evidence (you
corrected an agent over it, or said it in two conversations or projects) goes into
effect at once as a trial rule, and agents are told you have not confirmed it yet; it
holds for good after 3 tasks over 7 days with no correction. You do not have to go
through the rest. When a task you give an agent bears on one of them, the agent asks you
about it once, in one line: keep it, stop it, or say it your way. That happens at most
twice a day, never twice in one conversation and never while you are away. To see what
was learned, ask your agent to open the review or run varyz rules review. It opens on
your portrait: three brief signatures, rarity cues, and the one thing you keep fixing
across projects. Full rules and your own quotes stay under "Why this?". Setup opens
the portrait automatically when its reading and merges finish.
Nothing there needs an answer. Reword a trait that is off, mark one "not me", or make
the habit a rule. The full list sits below it, with a sample of 10 trial rules to keep
or drop. New trial rules pause when you keep fewer
than 90% of that sample; varyz rules trials shows them, --off stops new ones and
--undo-since DATE withdraws them. In Claude Code that subagent is varyz-rule-miner, which connecting
installs: Sonnet, and only the two Varyz tools that hand it the messages and take what
it found. Nothing needs pasting.
After that first reading, what you say to an agent is read as you say it. Each prompt
nudges the daemon, which reads the AI chats' newest messages into the archive a couple
of seconds later. When a prompt holds an instruction or a preference (not a question),
the briefing asks the agent to start the same subagent on just the last day. It asks at
most every 5 minutes, but at once when you say a rule holds from now on ("from now on",
"always", "never", "every time"). Such a rule goes into effect on trial for your next
task. [workflows] live_reading = false turns this off; live_reading_min_minutes and
live_reading_hours set how often it asks and how far back it reads.
You do not have to rely on the agent to start that subagent. By default
(reader_runner = "auto") varyz starts the reader itself, headless, through Claude Code
(claude -p, Haiku) or Codex (codex exec, its newest luna model): whichever has more
of your plan left, with only the two reading tools and no saved transcript. Your
five-hour and weekly usage only decides which sign-in reads: low usage never stops or
delays a reading. If Claude or ChatGPT refuses because a limit is reached, the reader
stops, keeps what it submitted, and resumes on its own once the window resets.
varyz rules read --status shows where it is, and varyz rules read --stop stops it.
varyz rules mine through a Claude or ChatGPT sign-in has no usage limits either.
When varyz cannot run the reader itself, your agent starts it. Connecting adds a short
marked section to Claude Code's ~/.claude/CLAUDE.md and Codex's AGENTS.md that allows
the agent to start that subagent without asking. Everything else in those files stays as
you wrote it, the file is backed up the first time, and varyz uninstall takes the
section out again.
Reading is quiet. The daily and live readings run without a word in your chat. Only a
major one, the first or a backlog of 300 or more messages, is mentioned, once and in one
plain line: what varyz is learning, that it runs on your own plan, skips anything
sensitive and removes passwords and keys, and that varyz rules review shows what it
learned. It is mentioned again at most once a month.
Before anything runs, preview it with varyz setup --dry-run. --yes connects every
agent and source it finds without asking. --source git (repeatable) offers only the
sources you name, and --no-sources skips step 4. The first indexing downloads the local
models it uses: about 1.4 GB, once per archive. Only More privacy downloads the
classifier model once (about 3.4 GB) and, where Ollama is missing or too old,
Ollama itself (about 160 MB on a Mac; 1.57 GB on Windows). Lighter on your device
does not download or start Ollama/Qwen, including when Ollama is already installed.
After setup you rarely need a terminal. Ask your agent for what a command does ("update
Varyz", "review my rules", "connect GitHub", "is Varyz working?"), and it runs the
command for you. Connected agents are told which command fits each request, and which
steps only you can take, such as allowing folder access on a Mac. The commands, if you
would rather type them:```powershell
varyz task "build a landing page" # what an agent is told
varyz sources # which data sources are connected
varyz connect github # add GitHub (asks for a token)
varyz update apply # install the latest Varyz; agents stay open
Every command reads `--config`, then `$VARYZ_CONFIG`, then a `config.toml` in the current
folder, and otherwise the `~/.varyz/config.toml` that setup created, so after setup no
command needs `--config`. Restart your agents once, and the next task you give them
arrives briefed. `varyz hooks doctor` repeats the GO check, and `varyz hooks pause` turns
the briefing off.
The installer scripts in `scripts/` do the same thing: they run `uv tool install` (or
`varyz update apply`, over an installed Varyz) and then `varyz setup`. On Windows with an NVIDIA card, `install.ps1` also installs onnxruntime's
DirectML build, which checks `ask` answers on the card (a median 2.7 s per question
instead of 5.7 s). By hand:```powershell
"onnxruntime ; sys_platform != 'win32'" | Out-File -Encoding ascii ort-overrides.txt
uv tool install git+https://github.com/egrm07/varyz --with onnxruntime-directml --overrides ort-overrides.txt
Updating
Varyz checks for a new version once a day, on the first use of the day, and your agent
tells you once per new version. Nothing changes until you ask your agent to update
Varyz, or run varyz update apply. [update] mode = "off" stops the check.
Nothing needs closing or restarting. Say "update Varyz" to Claude Code or Codex and
keep working: Varyz's tools pause for a minute or two while the new version goes in,
then every open agent reconnects to it by itself. On Windows the install runs in the
background, so the command returns at once and the agent tells you when it is done.
A copy from the Windows installer gets the latest release, installed silently in the
background after its checksum is checked against the release's. A Mac installer copy
downloads and checks the release's installer and opens it, since it asks for your
password: close your agents, click Install, and open them again. A copy installed from
GitHub gets the latest commit. A copy installed from a folder gets that folder, pulled
first when it is a git clone. Before a database migration, the update backs up the
database. It checks that the new version starts, then refreshes the Varyz files of
every agent you connected: the routing skill, the hooks and the reader. There is no
varyz connect to run again. The first agent session on a new version also refreshes
the connected agents, so an update made some other way (for example
uv tool upgrade varyzai) needs nothing more. With [update] mode = "auto", a copy
from GitHub or a folder also updates itself. An installer copy is only ever announced.
The first update after this change needs one restart of agent sessions opened before
it: their connection to Varyz was started the old way. Varyz says so when that is the
case and changes nothing until they are closed.
News
While you use Varyz, it checks varyzai.com/news once an
hour, and your agent tells you about each new post once, in one line at the end of a
reply. The check is a plain request for the news feed and sends nothing about you or your
archive. Feed readers can follow varyzai.com/news.xml.
News is on by default:```bash
varyz news # on or off, the last check and the latest posts
varyz news off # stop checking and passing news on
varyz news on # start again
varyz news check # check now
### From a checkout
The checked-in lockfile is authoritative. `setup` copies `config.example.toml` to the
config it creates:```powershell
uv sync --frozen
uv run varyz setup --config config.toml
On a Mac
macOS lets a background program into Desktop, Documents, Downloads and iCloud Drive
only with the owner's permission. Autosync runs through a small app named Varyz, built
on your Mac when autosync is installed (~/.varyz/data/autosync/Varyz.app), so the
first time it reads one of those folders macOS asks "Varyz would like to access files in
your Documents folder". Allow opens that folder and nothing else; nothing leaves the Mac.
If you chose Don't Allow, switch it on under Varyz in System Settings > Privacy &
Security > Files and Folders, or skip it and run varyz sync yourself. Where the app
cannot be built, the only switch macOS offers is Full Disk Access for the program
varyz autosync doctor names, which opens more than those folders; keeping the archive
and sources outside them (for example in ~/varyz) needs neither. Setup checks this
once autosync is on and, only if macOS kept a folder from it, names the folder and its
source and opens the right settings. The alpha installs no language model beyond the
classifier: qwen3.5:4b through Ollama.
What connecting an agent does
Step 3 runs varyz connect for each agent it connects. That registers a named
caller with a bounded capability, writes the MCP server entry, and installs the routing
skill and the briefing hooks (SessionStart starts the daemon if it is down,
UserPromptSubmit briefs, Stop stays silent unless you turn its check on). Other hooks in the client's settings are kept
in place, and the previous file is saved as .varyz-backup. Codex asks you to trust new
hooks the first time they run. Turn hooks off with [agent] briefing_hooks = false; the
stop check (done_gate = true) is opt-in. varyz uninstall removes them.
varyz doctor checks operational state in about a second. The archive damage scan
takes minutes on a large archive, so it runs in the background at most once a day and
doctor shows its last result; varyz doctor --full waits for a fresh one.
varyz doctor --fix tries a stopped local
daemon and reconnects broken agent credentials/hooks, then checks again. It does
not override pauses, replace another archive's daemon or repair damaged archives.
Reconnected clients need a restart to load fresh credentials.
During AI sessions,
the installed hooks check at session start, on prompts and at turn end; MCP calls
also check the active session credential. Checks run at most once a minute per
session, show a short failure note in the working chat and suppress unchanged
failures. A failure also offers one background repair subagent per archive every
20 minutes through the managed AGENTS.md / CLAUDE.md instructions. The agent
runs the local fixer, investigates remaining reversible defects and reports a
verified result or required owner action. The main agent answers and continues
its work without waiting for repair, and leaves the repair subagent running
after its own turn ends. Each repair job works for at most 30 minutes, the same
failure is offered at most three times, and failures only the owner can fix
(a full Cloud, a settings file others can read) never start one. When the
client denies a command the repair needs, the agent stops and hands the owner
the one command to run instead (varyz doctor --fix --config PATH).
The repair agent renews its lease every five minutes through
varyz doctor --repair-job ID --repair-state running --config PATH, preventing
duplicate repair offers during long jobs. fixed requires a passing doctor
check; blocked records that owner action is needed. The client must support
background subagents surviving the parent's response; Varyz's instructions
cannot override a client that forcibly terminates them.
The handoff works without a valid MCP token and avoids recursive repairs in the
rule reader. Varyz automatically installs both mining and repair instructions
in the connected clients' AGENTS.md / CLAUDE.md, refreshes them at session
launch and MCP startup, and preserves your text outside its managed block.
A paused hook or a client that does not run hooks cannot deliver hook
notes; MCP notes require the agent to call Varyz. No model inference or archive
text is used for these checks.
varyz hooks doctor is the go/no-go preflight (daemon, database, rules, data
sources, launchers, the installed clients' hooks, errors) and varyz hooks pause /
resume is the kill switch.
Try it without an agent
These examples run from a checkout. With the installed tool, drop uv run and
--config config.toml. See what an agent would be told:```powershell
uv run varyz task "Build a landing page for the waitlist" --project lumen --config config.toml
uv run varyz task "Build a landing page for the waitlist" --finish --config config.toml
uv run varyz rules checklist website --config config.toml
Teach and review directly:```powershell
uv run varyz know "Which analytics?" "Cookie-free only." --config config.toml # general
uv run varyz know "Which accent colour?" "#6d5efc" --project lumen --config config.toml # one-off
uv run varyz questions --config config.toml
uv run varyz answer <id> "Use short-lived feature branches." --scope general --config config.toml
uv run varyz dismiss --project scratch --config config.toml
uv run varyz knowledge list --config config.toml
uv run varyz rules list --config config.toml
Unregistered callers are not trusted implicitly because they use local stdio. They receive
a low-trust identity and strict item/character limits. Registered callers can be revoked.
Local daemon availability
varyz daemon on-demand removes this archive's Windows login watchdog and allows
the first local agent or CLI request to start the daemon. It starts no process
immediately. The first request may take a few seconds; scheduled source sync is
configured separately. Doctor reports an idle on-demand daemon as standby, with
first-use startup still unverified until a real request succeeds.
On Windows, varyz daemon install --dry-run previews the login registration;
varyz daemon install starts a hidden supervisor now and at each login. It checks
the local daemon every five seconds, recovers refused connections, and retries a crashed
worker. Local CLI requests also start a stopped daemon on demand. The default
address is 127.0.0.1:1207; an archive's explicit port is preserved. Login recovery
does not enable autosync, change source consent, unpause reading, or add cloud sync.
The computer must be awake and signed in.
varyz daemon status shows startup and pause state. Health checks append timestamps
and outcomes to data/daemon/availability.jsonl; data/daemon/status.json holds the
latest result. varyz daemon pause writes data/daemon/PAUSED and stops the service;
varyz daemon resume removes it and checks immediately. varyz daemon stop is a
one-time stop: automatic recovery can start it again. varyz daemon uninstall
removes this archive's login entry, pauses recovery, and stops the service without
removing its archive. Add --config when managing a separate archive.
The workflow```text
you: "build a landing page for lumen"
│
▼ hook (UserPromptSubmit) ── start_task ──────────────────────────────┐
agent gets the briefing: │
· how you always work (general rules, every project) │
· this project's vision, rules and settled one-off choices │
· your general preferences that touch the task │
· definition of done for each kind of work (website: favicon, SEO, │
social cards, sitemap, legal pages, phone width, ...) │
…(正文过长,页面只展示前面部分,完整内容见仓库)
```
