tokenwise-studio

You describe a task in one chat. The orchestrator (Claude Opus) plans it and hands each piece to the worker that fits: Codex Sol for code, Claude Haiku for reading and search, Gemini, free hosted models, or a local model. Each writing worker has its own git worktree. Nothing touches your project until you apply the diff.

studio is the companion to tokenwise. tokenwise is the skill that decides which model and effort a piece of work needs. studio gives the orchestrator a way to hand that work to another agent and merge the result. Each works without the other.

Why

The cheapest model that does the job well is often not the one you are using. Terminal-Bench 4.0 scores make that visible (official board):

• A free model ties a paid one. DeepSeek V4.1 Flash, served free on NVIDIA, scores 40.0, the same as Claude Haiku 5.5 (40.0).

• A cheaper tier gives the same score. GPT-6.1 Sol and GPT-6 Astra both score 58.2, and Sol costs about one fifth as much.

• Keep the strongest model for the hard part. Claude Opus 5.5 scores 64.8. Let it plan and review, and send the mechanical edits to workers on other plans.

The benchmark numbers are a snapshot and are updated in the app's Model guide. They guide the choices; they do not guarantee results on your code.

Related MCP server: pi-mcp

What you get

More:

• Never stuck on a limit. Workers fall back along codex → gemini → claude → free → local. The orchestrator itself moves from Claude to Codex Sol near a limit.

• Native Mac app. One window per project, Dock icon, desktop notifications.

• Five kinds of worker. Codex, Claude, Gemini (via Antigravity), free NVIDIA models, and local Ollama.

• Tests and checks. A per-project test command runs in the worker's worktree, and a combined check runs after Apply.

• Images. Paste a screenshot into the chat, or have Codex generate images and review them like any file.

• Project rules. Put instructions in TOKENWISE.md; they cannot override the review rules.

• Open a pull request from the applied changes, only when you confirm it in the review drawer. The orchestrator can never open one.

• Conflict check before Apply, so two workers' edits to the same lines are caught early.

• Workspace side panel. Files and diffs, a preview, and a "This chat" tab listing the files touched in the current chat.

• Model shootout. On request, the same task goes to two or three models in parallel and you pick the best result. It uses more tokens, so it never runs unless you ask.

• Dictation. A microphone button in the composer (Mac app).

• Quota pacing and cooldowns. Providers that hit a limit are skipped until their reset time; free models are probed and fallbacks kept.

• Rojo-aware project map for Roblox projects.

• Welcome window. The Mac app restores your last projects, or shows a welcome window instead of a folder dialog.

The full feature list is in FEATURES.md.

Install

Requirements:

• Node 20+, git

• At least one worker CLI, signed in: Codex CLI (codex login), Claude Code (claude auth login), Gemini via Google Antigravity (agy, included in Gemini.app on macOS; run it once to sign in with your Google account; models hydrogen (fast, default) and argon (frontier)) or Gemini CLI with GEMINI_API_KEY (Gemini CLI's own Google sign-in no longer works for individuals)

npm install -g github:OnurSamett/tokenwise-studio
tokenwise-studio setup

setup prints what it will change, then does two things:

• registers the MCP server with Claude Code at user scope (claude mcp add tokenwise-studio --scope user), if the claude CLI is installed and it is not registered yet;

• on macOS, creates the app ~/Applications/tokenwise studio.app: a normal Mac app with its own window and Dock icon (no browser tab). Opening it restores your last projects, or shows a welcome window to pick one; ⌘O opens another project (File > Open Recent lists earlier ones), each project gets its own window. Servers keep running when you quit the app, so they stay shared with terminal use.

Run tokenwise-studio setup --dry-run to see the plan without changing anything (--no-mcp and --no-app skip a part). Then start it from your project:

cd your-project && tokenwise-studio     # options: --port N, --no-open, --browser, --pick

From a clone (development):

git clone https://github.com/OnurSamett/tokenwise-studio.git
cd tokenwise-studio && npm install
node src/cli.js /path/to/project

How it works

1. You write a task. The orchestrator answers with a plan and calls the delegate tool for each piece, naming the agent, model and effort.

2. Each writing worker runs in its own git worktree on a branch cut from HEAD, so parallel workers cannot collide and your working tree stays untouched.

3. When a worker finishes, you get the diff. The orchestrator can read it and run job_test, but only you (or auto-apply mode, if you chose it) apply it.

4. Apply stages the files you ticked. Nothing is committed for you, and Undo apply restores exactly the files that Apply touched.

The orchestrator cannot edit files itself. Every change comes from a worker whose diff you can review.

Safety

• Reviewed changes only. Writing workers only touch their own worktree. You apply the diff, per file.

• Undo. Every Apply records a snapshot under refs/tokenwise/pre-apply/. Undo refuses, and lists the files, if they changed since.

• Permission modes, enforced inside the MCP tools: ask (default), auto-apply, plan-only.

• Local only. The UI binds to 127.0.0.1, with CSRF and Host checks. State lives in .tokenwise-studio/, which is git-excluded.

• Free hosted models are opt-in (TOKENWISE_ALLOW_FREE=1), because free tiers may use prompts for training. They run in a small tool loop that cannot run commands and is confined to the worktree.

• Guard rails. max and ultra effort are refused. Codex astra is blocked unless you enable it. Turn budgets stop new jobs at 100%.

• Backups and exports are plain local files. Chats can still contain secrets you pasted, so keep them private.

FAQ

Does it replace Claude Code or Codex? No. It drives the CLIs you already have, signed in with your own accounts. No API keys are needed for Claude or Codex.

Is anything uploaded? studio runs on your machine and, apart from the optional update check, makes no network calls of its own. Prompts go only to the providers whose CLIs or APIs you use.

Does it work without the tokenwise skill? Yes. The skill picks models and effort inside Claude Code, Codex CLI and Gemini CLI. studio adds the app, the worktrees and the review.

Linux or Windows? The web UI and the MCP server are Node and git, so they may run elsewhere, but the Mac app and notifications are macOS only, and only macOS is tested.

Which workers are best tested? Codex and Claude are tested end to end. Gemini is wired up but less tested.

Reference

Details for the features above. Each section opens on click.

By default the studio keeps itself current. Settings > Updates has three modes: Automatic (default), Notify only and Off.

• Automatic: at most once every 24 hours the studio checks for a newer version and, if there is one, installs it in the background (npm install -g, from the npm registry if the package is published there, otherwise from GitHub, the same rule as update). It never installs while a job, test run or chat turn is running (it retries later), and never over a git checkout. When it is done the sidebar shows "Updated to vX — restart to use it" with a Restart now button. Progress is logged in ~/.tokenwise-studio/update.log.

• Restart now stops the studio servers gracefully and the Mac app reloads its windows with the new version. If the app's Swift launcher changed in the new version, the app is rebuilt first (tokenwise-studio setup --no-mcp, no prompts).

• Notify only: a small "New version" note with the command to copy; nothing is installed for you.

• Off: no installs and no notice (turning off "Check for updates" does the same).

By hand:

tokenwise-studio update --check   # just report whether a newer version exists
tokenwise-studio update           # install it, rebuild the Mac app, stop running studio servers

update reinstalls the way you installed (npm or GitHub), runs tokenwise-studio setup so the Mac app matches, and stops running studio servers (busy ones are left alone) so open windows reload on the new version. Running from a git checkout? Use git pull instead. Release notes are in CHANGELOG.md.

Stale-server protection. A studio server started before an upgrade keeps running old code but serves the new page files, which used to leave a blank window. Now every server reports the version it started with; the Mac app only reuses a server whose version matches the app, otherwise it asks the old one to quit (POST /api/quit, local and CSRF-protected) and starts a fresh one. If a page still fails to load, a banner says "This studio server is outdated or failed to load. Quit the app and reopen it."

Just ask your orchestrator, e.g. in Claude Code on Opus:

Fix the failing tests. Delegate each independent fix to codex sol at medium effort as a write job, review the diffs, merge the good ones, then run the tests.

Paste an image, drop it onto the composer, or use the attach button. PNG, JPEG, WebP and GIF are supported (up to 6 per message, 10 MB each). Remove a thumbnail with × before sending. Images are stored locally under .tokenwise-studio/uploads/ and forwarded to Codex and Claude workers when delegated; other workers continue without images.

Each turn's Thinking section starts collapsed above its replies. Expand it to read the orchestrator's thinking steps; worker thinking is also collapsible in the job drawer. Usage and meta events stay hidden.

On macOS, tokenwise studio shows a desktop notification when a direct worker finishes or fails (not those started by a studio chat), and when an orchestrator turn finishes, needs you, or moves from Claude to Codex. Jobs ready for review are called out. Toggle them with the bell button in the studio sidebar, or set TOKENWISE_NOTIFY=0 to turn them off entirely. The setting is stored in ~/.tokenwise-studio/settings.json.

After tokenwise-studio setup, notifications come from the tokenwise studio app in ~/Applications (the first one asks for permission), and clicking one opens that project's studio. Without the Xcode command line tools (no Swift compiler) setup falls back to a plain launcher and notifications come via Script Editor.

Per project you choose how the orchestrator picks workers. Auto (default) lets it decide by its own guide. Manual fixes an agent, model and effort for each role (code, quick work, reviews, images); start from a preset (quality, balanced or cheap) and adjust. The choice is stored in .tokenwise-studio/team.json. The orchestrator follows it and only deviates when a plan is out of quota. You can also forbid the free workers or allow Codex astra there.

Click the gear button in the sidebar footer to open Settings (stored in ~/.tokenwise-studio/settings.json; environment variables still override and lock individual fields):

• Permission mode: ask (default; you review and apply worker diffs), auto-apply (the orchestrator reviews diffs and merges them itself), or plan-only (plans and read-only research only; write delegation is blocked).

• Orchestrator defaults & limits: preselected model/effort, what happens when Claude reaches its limit (switch automatically, ask me, or off), fast mode (--settings fastMode for Claude, service_tier="fast" for Codex), limit threshold % (50–100), worker fallback order, and opting in to free hosted models.

• Notifications & updates: desktop notification and update check toggles, and the Updates mode (see Updating).

• Turn budget: off by default, presets of 50k / 100k / 250k / 500k tokens per turn (accepts 10k–50M in settings.json), counting the orchestrator and the workers it starts (see Turn budget below).

• Tests: run tests before Apply, and the test command (see Tests below).

• Project instructions and Backup: see below.

• Export one chat: open the ... menu next to a task and choose Export as Markdown or Export as JSON. The file has your messages, the orchestrator's replies, each worker job (agent, model, effort, status) and the files it changed or applied. Thinking steps and image data are left out; attached images are listed by path.

• Command line: tokenwise-studio export [--chat <id>] [--out <dir>] [--repo <path>] writes Markdown and JSON for one chat, or for all chats when no id is given. The default folder is .tokenwise-studio/exports/ in the project.

• Back up all chats: the button in Settings copies the project's chats, jobs, the images they use (nothing over 10 MB) and Markdown/JSON exports as plain files to ~/.tokenwise-studio/backups/<project>/<timestamp>/ and shows the path. .env files are never copied, and nothing is uploaded. Chats can still contain secrets you pasted, so keep backups private. To sync between machines, point iCloud or Syncthing at that folder.

Put rules for a project in TOKENWISE.md at its root (fallback: .tokenwise-studio/instructions.md). It is a normal file you can commit. Every orchestrator turn (Claude or Codex) gets its first 8 KB, labelled as project instructions from the repo. They are treated as your configuration but cannot override studio's rules: the orchestrator never edits files itself, every change is reviewed before it is applied, and plan-only mode stays in force. If the file has a ## For workers section, up to 1,500 characters of it are added to every worker's task as "Project notes". Settings shows whether the file is loaded and has an Edit instructions button that saves TOKENWISE.md (creating it if missing).

Set Turn budget in Settings to cap the tokens one turn may use, orchestrator plus the jobs it starts in that turn (worker tokens are what their logs have reported so far). At 80% a notice appears in the chat. At 100% the delegate tool refuses new jobs with a clear message so the orchestrator wraps up, and a notice is shown; jobs already running keep going. The turn footer shows the turn's total tokens, and the share of the budget when one is set.

The Usage entry in the sidebar footer opens a per-project view: tokens (or API-equivalent cost) per day for the last 14 days as a bar chart, split into orchestrator turns and worker jobs, a table by agent and model, totals, and your current Claude and Codex plan-limit readings. The same data is at GET /api/usage?days=14. Subscription plans are not billed per token, so the cost is what the same tokens would cost through the API. Claude Code reports its own cost; other prices are rough estimates (marked ~ in the screen; the rates are in src/usage.js). Free and local models count as $0. Cached input is shown separately and is not part of the token total.

When a write worker produces png, jpg, webp or gif files (for example Codex image generation, routed by the orchestrator to the images role), they appear as thumbnails in the job card and the job drawer; click one for a full-size lightbox. In the review they are listed as binary files with a thumbnail and are applied like any other file (checkbox, staged, not committed). Copies are kept in .tokenwise-studio/artifacts/<job>/, so thumbnails stay after Apply or Discard. Images are served only from a job's worktree or that folder, by image extension, never through symlinks, up to 15 MB each (24 per job).

Studio detects a test command per project: an npm test script in package.json (the npm placeholder is ignored), else pytest -q (pytest.ini or pytest in pyproject.toml), go test ./... (go.mod), cargo test (Cargo.toml). Override it under Settings, Tests. For a finished write job, the review and the job drawer have a Run tests button: it runs the command in that job's worktree (argument array, no shell, 10 minute timeout, one run per job), streams the output, and shows pass or fail with the end of the output. Network is not restricted, and a worktree has only committed files (dependencies are not installed), so a project whose tests need node_modules may need a setup command in its test script. Turn on Run tests before Apply to run them automatically when a write job finishes; the result shows as a chip on the job card. The orchestrator can call job_test to check its workers' work (allowed in every permission mode, since it changes no project files).

Every Apply first records a snapshot of your index and working tree under refs/tokenwise/pre-apply/ (the last 30 are kept; your branch, HEAD and index are never touched by it). Undo apply (in the toast, the job card and the applied banner) restores only the files that Apply touched, to how they were before. It refuses, and lists the files, if any of them changed since the Apply, so your later edits are never lost. Committing also records a snapshot.

Turn on Check after Apply (Settings > Tests) or press Check combined changes to run the project's test command plus an optional lint command in your working tree after workers' changes are applied together. Argument arrays, no shell, 10 minute timeout.

The Studio errors button in the composer opens an importer: paste the Roblox Studio Output (up to 20 KB), see the errors with stack traces (warnings and prints are ignored, repeats are merged) mapped to source files through your Rojo *.project.json, pick some, and Ask to fix sends them to the orchestrator. Everything is parsed locally.

Settings has a Language choice: Auto (follows the system or browser language), English or Türkçe. It covers the interface and desktop notifications.

When an orchestrator chat's context grows past a threshold (default 120k tokens, 60k to 400k in Settings), the next turn first summarizes the earlier conversation with Claude Haiku (claude -p --model haiku, no tools; a local summary is used if that is unavailable) and starts a fresh session with that summary. The full history stays visible in the chat, with a collapsible "compacted" notice. Use Compact now in a task's ... menu to do it manually, or turn it off in Settings. The summary is built only from this chat's messages and its jobs.

The Team settings have a Web research role. Research jobs (delegate with role="research", read-only) get live web search on Claude and Codex (Gemini and Antigravity use their own web tools); other jobs never get web access they did not have before. Free and local workers do not support it. Replies show numbered citations and a Sources list; only http and https links are clickable.

Free NVIDIA models can be picked individually in the Team panel.

Jobs fall back automatically along codex → gemini → claude → free → local (override with TOKENWISE_FALLBACK):

• Before starting, a job skips any plan at or above TOKENWISE_LIMIT_THRESHOLD (default 90%) of its 5-hour or weekly limit, or a worker that isn't signed in.

• While running, a job that fails with a rate/usage-limit error is re-run on the next worker; the UI shows "↪ took over from Codex · hit a rate limit", and job_wait follows the move.

• The orchestrator itself moves from Claude to Codex (read-only, same delegation tools) when Claude is near its limit or hits it mid-turn; the UI shows "↪ Codex Sol took over". Gemini cannot orchestrate because Antigravity has no per-session MCP. Disable with TOKENWISE_ORCH_FALLBACK=0.

• local: an Ollama model driven by Codex CLI's --oss mode: free, unlimited, full agent (brew install ollama && ollama pull gpt-oss:20b).

• free: free-tier hosted APIs, tried in order: NVIDIA (NVIDIA_API_KEY from build.nvidia.com), OpenRouter :free, Groq, Mistral, or any OpenAI-compatible endpoint (TOKENWISE_FREE_BASE + TOKENWISE_FREE_KEY). A rate limit on one moves to the next. Free models run inside studio's own small tool loop (src/freeagent.js), so they read the repo and, in write jobs, edit files in their worktree; they cannot run commands, and paths are confined to the worktree with symlinks, .git and secret files blocked. Used only after you opt in with TOKENWISE_ALLOW_FREE=1, since free tiers may use prompts for training.

• Codex: sol at medium (families terra/sol resolve to the newest version automatically). astra is blocked unless TOKENWISE_CODEX_ASTRA=1.

• Claude: haiku at low. Gemini (Antigravity): hydrogen at medium; write jobs may run commands only inside Antigravity's terminal sandbox.

• max/ultra effort is refused.

• Write jobs branch from HEAD: uncommitted changes in your tree aren't visible to workers.

• The UI binds to 127.0.0.1 only. State lives in .tokenwise-studio/ (git-excluded automatically).

Contributing

Issues and pull requests are welcome. For a bigger change, open an issue first so we can agree on the approach. Run the tests with npm test before sending a PR. Real-world notes on which model and effort worked for which task are useful too.

License

MIT. See LICENSE.

Provider and model logos (in assets/providers/, from the MIT-licensed lobe-icons, unmodified) are trademarks of their respective owners and are used only to identify each provider or model. tokenwise studio is not affiliated with, endorsed by, or sponsored by OpenAI, Anthropic, Google, NVIDIA or any other provider shown.