What's new in v0.3 (upgrading from v0.2.1)
v0.3 is the sum of the releases from v0.2.2 to v0.3.0. This page lists what each brought, links to its guide, and ends with the upgrade steps from v0.2.1. The CHANGELOG has every entry, release by release, including each release’s upgrade notes.
The headlines
Section titled “The headlines”One URL for every project: the hub
Section titled “One URL for every project: the hub”The first daemon started on a machine also serves the hub on
127.0.0.1:8089: one dashboard, one scoped API proxy and one merged event
feed for every project on the machine, with its own hub tokens
(itervox token create --hub). Notifications can be routed per project,
batched into digests, snoozed, and shown as desktop notifications.
→ The hub
Your phone
Section titled “Your phone”The hub serves the dashboard as a web app you can install on your phone. Pair it with a QR code, turn on push notifications, and answer agents, approve held commands, steer and pause from there — on your LAN, over Tailscale or through your own tunnel. → Your phone
Agent questions, guardrail approvals and failures can go to Slack through a Slack app you create yourself (Socket Mode, so nothing needs to reach your machine from outside). Reply, approve and steer from the thread. → Slack
Review an agent’s changes
Section titled “Review an agent’s changes”An issue’s Changes tab shows the agent’s diff. Click a line number (or shift-click for a range) to leave a comment for the running agent or on the pull request, review the pull request from the issue, and open a file in your editor. The Now panel at the top of the issue’s Details tab shows what the current run is doing. → Review changes, Now & Changes
One settings format
Section titled “One settings format”tracker, hooks, dependencies and automations joined agent,
polling, server, workspace and hub as layered JSONC settings:
~/.itervox/settings.jsonc (your defaults), .itervox/settings.jsonc
(the project’s, committed) and .itervox/settings.local.jsonc (yours, not
committed), all described by one published schema. WORKFLOW.md keeps the
prompt. Front-matter settings still work but are deprecated, and
itervox init --update moves them. A hand edit of any settings file now
reloads the daemon, like an edit of WORKFLOW.md.
→ Moving settings out of WORKFLOW.md,
Settings files
itervox watch replaces the terminal UI
Section titled “itervox watch replaces the terminal UI”The daemon always runs headless. itervox watch is a live terminal panel
over a running daemon: capacity, one lane per running issue, the event
feed, and every question or approval waiting for you with the exact
itervox reply … or itervox approve … command to answer it. It never
changes the terminal mode, so it works over SSH, in tmux and in a pipe
(--json). itervox logs -f, pause, resume, dispatch and workers
cover the rest. The Bubbletea terminal UI is gone, and --tui now fails.
→ Working from the terminal, CLI reference
Guardrails, on by default
Section titled “Guardrails, on by default”Agents Itervox starts may push only to their issue branch (no pushes to
main, master, develop or the base branch, no tags, no force pushes or
branch deletions), never merge their own pull request, and wait for your
approval before deploy and publish commands such as vercel --prod,
kubectl apply, terraform apply or npm publish.
→ Guardrails
The Mac app
Section titled “The Mac app”A menu-bar app lists every project’s daemon, starts and stops them, notifies
you when an agent needs input, and opens each dashboard without a terminal.
It reaches daemons on a VM or another machine over IAP or SSH tunnels, uses
the hub when one runs, and updates itself from a signed release. Every dashboard window has a
project rail to switch projects (⌘1…⌘9). Install it from the DMG, or with
Homebrew (brew install --cask vnovick/tap/itervox-app) once a signed
release has published the cask. The app carries its
own itervox daemon; brew install vnovick/tap/itervox stays the
command-line tool, so install one or the other.
→ Mac app
Also new
Section titled “Also new”Agents and runs
- Memory and lessons — private and project-shared memory entries, lessons proposed from your corrections and from failed-then-fixed runs, with a review queue. → Memory
- Playbooks, a decision log and steering phrases — a playbook per task type (bug fix, feature, refactor, …) in every matching run’s prompt. → Playbooks
- Rules — short instructions written once in layered JSONC files and added to every run, with a Rules editor. → Rules
- Sessions panel — tabs over running agent sessions with a composer, sessions you started by hand, and sessions in tmux. → Sessions panel
- Cross-review preset — Claude writes, Codex reviews (or the other way round), with read-only reviewers and their verdicts on the issue. → Cross-review preset
- Done needs evidence —
require_evidenceon a profile. → Configuration - Per-issue budgets and a cost report —
agent.budget.*anditervox report costs. → Per-issue budgets - Backend health and fallback — what happens when Claude or Codex hits its usage limit. → Backend health and fallback
- Stacked pull requests — start a dependent on its in-review blocker’s branch. → Stacked pull requests
- An MCP server —
itervox mcpgives Claude Code or Codex your board and memory. → MCP server
Trackers
- Local issues —
tracker.kind: localkeeps issues as Markdown files in your repository, with optional two-way sync to Linear or GitHub. → Local issues - Tracker store, incremental pulls and webhooks — the board is served
from a local copy of the tracker, every agent start re-checks its issue
first, and Linear or GitHub webhooks can push changes.
→ Tracker webhooks,
trackerreference - Tracker filter and Linear scope — groups of conditions with AND, OR and NOT; Linear project, assignee and labels combined. → Tracker filter, Linear setup
- GitHub —
/itervoxcomment commands, state-label checks initervox doctor(and--fix), an agent-ready issue template, and PR-event automation triggers. → GitHub Issues, Automations
Operating
- Pause all dispatch and an event feed → Pause dispatch & event feed
- Token scopes (viewer, operator, admin) and rotation without a restart → Security & access tokens
- Repo Analysis — skills inventory, usage and cost, prompt versions, readiness checks, eval results and failure hotspots on one page. → Repo Analysis
- Getting started faster —
itervox quickstart,itervox demoand starter templates foritervox init --template. → Getting Started, CLI reference - A Settings page from the config schema,
itervox config,itervox importanditervox export --symphony. → CLI reference
Upgrading from v0.2.1
Section titled “Upgrading from v0.2.1”Your WORKFLOW.md keeps loading as it is (itervox_schema_version: 2, no
schema bump). Most changes need nothing from you; the steps below cover the
ones that might.
-
Install the new version.
brew upgrade vnovick/tap/itervox, or download the release. The Mac app updates itself when the release is signed; otherwise install the new disk image over the old one. -
Remove
--tuifrom unit files, scripts and aliases.itervox --tuinow prints a pointer toitervox watchand exits with code 2, so a service that still passes it fails to start. Watch withitervox watchfrom another shell instead. -
Check the configuration. Run
itervox doctor. It prints adeprecated:line for every front-matter key that now belongs in a settings file, and aWARNING:for a key set in both places. -
Move the settings and pick up the new defaults. Preview, then run:
Terminal window itervox init --update --workflow WORKFLOW.md --dry-runitervox init --update --workflow WORKFLOW.mdIt writes
WORKFLOW.md.bakfirst, moves the layered sections to.itervox/settings.jsonc(comments kept, the merged configuration checked to be unchanged), writes theguardrails:block with its defaults, and adds the starter playbooks under.itervox/playbooks/(never over a file you have). Commit.itervox/settings.jsonc; keep.itervox/settings.local.jsoncand.itervox/.envout of git. → Moving settings out of WORKFLOW.md -
Review the guardrails against your prompts. A prompt that tells agents to rebase and force-push, or to push a second branch, now gets a refusal that says what to do instead. Set
guardrails.allow_force_push: true, orguardrails.enabled: false, to keep the old behaviour. Deploy and publish commands wait for your approval (itervox approve <issue>, the dashboard, your phone or Slack). Guarded agents no longer seeITERVOX_API_TOKEN. → Guardrails -
Decide about the hub. The first daemon on the machine now also listens on
127.0.0.1:8089(loopback only; every hub route but its health probe needs a hub token). To keep the old behaviour, start daemons with--no-hubor sethub.enabled: false, for example in~/.itervox/settings.jsonc. → The hub -
Know the other new defaults.
- Playbooks are on: a run whose issue matches a task type gets that
playbook in its prompt. Opt out with
agent.playbooks.enabled: false, by deleting the files, or with None on an issue. → Playbooks - The tracker store is on for Linear and GitHub: the first start
after the upgrade makes one full pull and writes
.itervox/tracker_store.json, and a change made in the tracker reaches the board withintracker.store.sync_interval_ms(1 minute by default) unless webhooks are on. Settracker.store.enabled: falseto poll directly. →trackerreference - Shared bare clones (
workspace.worktree: truewith aclone_url) are migrated torefs/remotes/origin/*the first time a worktree is created. Nothing is deleted or moved, and nothing needs doing;itervox doctorshows each clone’s refspec and last fetch.
- Playbooks are on: a run whose issue matches a task type gets that
playbook in its prompt. Opt out with
-
Restart and watch. Start the daemon, then
itervox watch(or open the dashboard) and check that work is dispatched as before.
Every upgrade note, with the release that introduced it, is in the CHANGELOG.