customize ixi

ixi Local can change itself. You point at something in the app and say what should be different. Your own coding agent then makes the change in a workspace, a separate copy of ixi's source with its own branch, its own running build and its own copy of your projects. You try the result in a preview, read the diff and run the checks. The ixi you're using stays exactly as it was.

In this guide you ask for one change, from a right-click to a working preview.

before you start

• A coding agent CLI, installed and signed in with your own account: Claude Code, Codex, Cursor Agent, OpenCode or Gemini CLI. ixi finds it on your shell's path. ixi never ships an agent or signs you in to one.
• Node.js 22 or newer. ixi doesn't include it. Workspaces run their setup and their build with it, and the ixi command runs on it. Without it, the Source card says Customize needs Node.js on your Mac, with how to install it, and Set up source stays greyed out.
• pnpm, or Node's corepack. Workspace setup installs ixi's packages with it.
• Room on disk for a copy of ixi's source in ~/ixi.

make a change

1. Open Customize. In the menu bar choose Customize → Customize ixi…. A second window opens, titled Customize ixi. Its sidebar has your Source and your Workspaces, and under ixi the Builds, GitHub, ixi Cloud and Terminal pixies panels.

2. Set up the source. In the Source card, press Set up source. ixi clones its own source from github.com/ixi-design/ixi, at exactly the version you're running, into ~/ixi/source, on a branch named my-ixi. You do this once. Every workspace starts from my-ixi.

3. Point at what should change. In the ixi window, right-click the thing you want changed and choose Change This with My Agent…. The same item is in the Customize menu. The Customize window shows Change this with your agent, with a screenshot of the window, the page (Route), the element you clicked, its text and any recent console errors.

4. Say what you want. Type it under What should change?, for example "make this button say Create and put it on the left". Keep the suggested Name or type your own, leave Run the setup script right away ticked, and press Create workspace. Your request and the screenshot are saved in the workspace's .context folder. Nothing is sent anywhere else.

5. Start your agent. In the workspace, press Start agent ▾ and pick your agent. It opens in a terminal tab with your request waiting for it: it reads .context/request.md and the screenshot, then makes the change. Answer its questions and permission prompts in that terminal, as you would anywhere else.

6. Try it. Once the setup tab has finished, press Run, then open Preview. The workspace's own build of ixi starts on its own ports, with its own copy of your projects, and shows up in the pane. Reload reloads the preview and DevTools opens the inspector.

7. Review it. Diff lists every file the workspace changed since it branched from my-ixi, with lines added and removed. Checks runs ixi's Typecheck, Tests and Lint in the workspace, with live output. Run all starts all three.

what just happened

A workspace is a git worktree of your source on its own branch, ws/<name>, with a block of ports of its own and a copy of your projects taken when you created it. The agent works in that folder and its build runs from it, so neither can touch your real projects or the ixi you have open. The change lives on its branch until you decide what to do with it.

the workspace bar

button	what it does
Run / Stop	start or stop this workspace's own build
Terminal	a shell in the workspace folder
Start agent ▾	your agent in a new terminal tab, with the waiting request if there is one
Terminal.app · VS Code · Cursor · Finder	open the workspace folder in that app
Setup	run the setup script again
Archive	remove the folder but keep the branch and its copy of your projects

An archived workspace shows Restore, which brings the folder back, and Delete…, which then asks you to confirm with Delete branch + data. Deleting removes the branch and the workspace's copy of your projects for good.

For a blank workspace with no request, press New workspace on the Customize home page or + beside Workspaces.

fix an error with your agent

When ixi breaks, you can hand the error straight to your agent:

• A page shows Something went wrong. Press Fix with agent on that page.
• The window stops working. ixi shows ixi stopped working with Reload, Fix with agent and Close. Choose Fix with agent.

Either way, the Customize window opens Fix with your agent with the error filled in. Add anything the agent should know under Anything else the agent should know?, then press Create workspace. Nothing happens until you do: Discard drops the request.

checks

status	means
passed	the check finished clean
failed	it failed. For tests, the row lists the new failures
known failures only	every failing test file is one that also fails on an untouched copy of ixi
not run	press Run to start it

A known-only result is amber, not red, so a workspace isn't marked broken for failures it didn't cause.

the ixi command

Every workspace terminal has an ixi command. To have it in every terminal, choose Customize → Install 'ixi' Command in PATH… and enter your Mac's password. ixi links /usr/local/bin/ixi to the command inside the app, so it follows app updates.

If you cancel the password prompt, ixi puts the link in ~/.local/bin instead and tells you. When that folder isn't on your PATH yet, the message gives the line to add to ~/.zshrc. An ixi that isn't ixi's is never replaced. Uninstall 'ixi' Command from PATH… removes the link again.

command	does
ixi ws list	your workspaces, with state, branch, ports and folder
ixi ws new <name>	create a workspace
ixi ws open <name>	show it in the Customize window
ixi ws path <name>	print its folder, for cd "$(ixi ws path fix-dock)"

Add --json to list or new for output a script can read. The command talks to the running app, so ixi has to be open. Until the command is installed, the Customize home page says it works In a workspace terminal.

workspace scripts

A workspace runs the scripts in its own .ixi/workspace.toml, under [scripts]:

• setup runs once, after the workspace is created. In ixi it installs the packages.
• run runs when you press Run. In ixi it builds and starts the workspace's copy of the app.
• archive runs before the folder is removed.

Each one runs in a terminal tab you can watch. Because the file lives in the workspace, a branch can change its own scripts. If the file doesn't parse, the workspace says so and uses the default scripts.

limits & good to know

• Names: up to 40 characters: lowercase letters, digits and single hyphens. A few words such as main, source and my-ixi are taken.
• Up to 100 workspaces can hold ports at once. Each takes a block of 10; archiving a workspace frees its block.
• The copy of your projects is taken once, when the workspace is created. Work you do in its preview stays in the workspace.
• Your API keys come with the copy. A new workspace gets the keys you saved in ixi, locked with a key of its own, so nothing in the workspace can open your real ones. Keys you add or change later don't reach a workspace you already have: enter them in the workspace, or create a new one.
• Your agent sees the workspace's ixi only. Each workspace has an MCP config for each agent: .mcp.json (Claude Code), .codex/config.toml (Codex), opencode.json (OpenCode), .gemini/settings.json (Gemini CLI) and .cursor/mcp.json (Cursor Agent). Each one connects the agent to that workspace's own build, never to your real one. Git ignores them, and a file your branch already tracks is left alone. Codex reads its file once you trust the folder; Claude Code and Cursor ask before they use it.
• No agent found? The Customize home page lists the names it looked for. Terminals work without one.
• "Can't reach github.com/ixi-design/ixi"? ixi's repository isn't public yet, so there's nothing to clone. Set IXI_SOURCE_REMOTE to a copy of ixi you can reach.

take it further

• builds and safe mode: run ixi itself as built from a workspace, and get back to the official ixi when a build fails.
• github: push a workspace's branch to your fork and propose it to ixi.
• ixi local: what the app keeps on your Mac.
• keys, connectors and models: connect the providers your workspace builds will use too.
• MCP server: what an agent can do with ixi through MCP.