terminal pixies

In ixi Local a pixie normally thinks with a model on one of your keys. A terminal pixie hands its thinking to your own Claude Code instead. You chat in the pixie's dock as usual. Claude Code runs on this Mac, signed in with your Claude account, and works on the canvas through ixi's tools. No API key and no ixi credits are involved.

before you start

• Claude Code, installed and signed in with your own Claude account. ixi looks for claude on your shell's path, then in ~/.local/bin, ~/.claude/local, /opt/homebrew/bin and /usr/local/bin. ixi never installs it or signs you in.
• Claude Code is the only agent a pixie can run on. Other coding agents work in customize ixi workspaces.

switch a pixie to Claude Code

1. In the pixie's dock, press the sliders button in its chat header (Edit system prompt). The pixie's settings open.
2. Set Runtime to Claude Code on this Mac. Nothing starts yet. A note under the field says your messages now go to Claude Code, and the Claude Code settings appear under it. ixi's own Model setting further down doesn't apply.
3. Type a message to the pixie. The first time, ixi asks in its own dialog: "Let the pixie “…” run Claude Code on this Mac?", with the canvas, the program it will run and the folder it will run in. Press Run Claude Code.
4. Claude Code starts in the pixie's folder, reads the canvas, and replies in the chat.

A line under the dock header shows Claude Code and what it's doing:

shows	means
Starts when you message it	not running; your next message starts it
Ready	running, waiting for you
Working	on a turn
Stopped with an error	it exited; the line below says why
Open in the Terminal view on this Mac	you're driving it from the Terminal view

ixi asks once per pixie, and again if a different claude program turns up on your path. Cancel, and the pixie shows "Not started: running Claude Code for this pixie was not allowed on this Mac." ixi doesn't ask again until it restarts, or until you press Start in Terminal pixies.

No claude found? The pixie says "Claude Code (claude) was not found on this Mac. Install it, then message the pixie again."

claude code settings

With Runtime set to Claude Code on this Mac, a Claude Code box under the field holds this pixie's own settings. Leave a field empty for Claude Code's default.

field	what it sets
Model	the model Claude Code thinks with: an alias such as fable, opus or sonnet, or a model's full name
Fallback	the model to switch to when the first is overloaded; list up to four, separated by commas, to try in order
Max turns	how many turns Claude Code may take on one message, from 1 to 9999
Effort	low, medium, high, xhigh or max

Each field saves when you leave it, and the box says "Saved for this pixie on this Mac. Used from your next message." A value Claude Code wouldn't accept is refused there, with what's wrong. If Claude Code is already running, it restarts on the same conversation with the new settings before your next message.

approvals

Claude Code asks before it does anything that needs your permission. Where you answer depends on what it wants to do.

Running a command, changing a file or reaching the web (Claude Code's Bash, Write, Edit, MultiEdit, NotebookEdit, WebFetch and WebSearch tools, and any of its own tools ixi doesn't know to be read-only) is asked in a dialog of the ixi app, never in the chat: "Allow the pixie “…” to run this command?", or to write, edit or change a file, fetch a page or search the web. The dialog shows the command, the file's path, the page's address or the search, where it runs and the canvas, with Allow and Deny.

• Only Allow allows. Deny, Esc and Return all deny. So does no answer within 5 minutes, which closes the dialog.
• One dialog at a time. If two pixies ask at once, the second waits for the first.
• The chat shows it too. A card titled with the tool's name, such as "Allow Bash?", shows what's being asked and "Waiting for your answer in the dialog", then how it ended: "Allowed in the dialog", "Denied in the dialog" or "No answer in time — denied". The card has no buttons. Nothing in the app window can answer for you.

Everything else, such as ixi's own canvas tools or reading a file outside the pixie's folder, arrives as an approval card in the pixie's chat with two buttons: Allow and Deny.

• Only a click on Allow allows. A typed reply instead of a click counts as no. So does no answer within 5 minutes: the card closes with "No answer in time — the request was declined."
• Deny asks why first. Type what should change and press Send feedback, or press Decline without feedback. Your note goes back to Claude Code.
• The pixie can ask you too. When it wants a go-ahead on a plan or a result, it posts an ordinary approval card. The same rule holds: only a click approves.

what it can do

Through ixi's tools, a terminal pixie works on this canvas and the canvases inside it. Any other canvas answers "not found". There it can:

• read the canvas, and add, change, wire and delete nodes;
• run models and nodes;
• build and edit sandboxes, 3D models, compositions, cuts and designs;
• read and fill tables, and read PDFs;
• start a process run and check on it;
• look at a node's picture;
• raise its attention badge with a note in the canvas inbox, see what it's still waiting on you for there, and take its note down once it no longer applies.

It also works as a pixie, the way ixi's own pixie does:

• publish a run's results. In a process run, it delivers its results to the process node's tray. The process's approval rule applies as usual: when you review first, it asks you on an approval card that shows the results, and only your click on Approve publishes them.
• hand work to another pixie. It lists the other pixies on its canvas, and the ones inside its processes, sandboxes, 3D models and compositions, and can hand one a request. That pixie does the work in its own chat and reports back. This takes minutes.
• remember. It keeps memory on its pixie node, across chats and sessions, like any pixie.
• load its skills, the step-by-step instructions for the kinds of job its role knows.

It also has Claude Code's own tools, such as the shell and files, behind approvals.

A terminal pixie can't make canvases outside this one, look up where something is used across canvases, start a pipeline or open a support ticket.

It answers only messages you type in its chat. A kickoff, a message from another pixie, an email or a pipeline broadcast gets this reply instead: "This pixie runs in your terminal agent (ixi Desktop), which only answers messages you type in its chat."

the pixie's folder

Each terminal pixie has its own folder, ~/ixi/pixies/<canvas id>/<pixie id>/, where Claude Code runs:

file	holds
CLAUDE.md (and the same text as AGENTS.md)	the pixie's brief: its role and working mode, the canvas, and which ixi tools stand in for its usual ones
START.md	the first message of a new session
.mcp.json	the connection to ixi's tools for this pixie only (ixi-pixie), and to the ixi app for approvals (ixi-desktop)

The session carries on: the next start resumes the same Claude Code conversation. Only ixi's tools are connected in it; MCP servers you set up for your own Claude Code aren't loaded.

the terminal view

Terminal pixies, under ixi in the Customize window's sidebar, lists every pixie switched to Claude Code, with its canvas and its state: Stopped, Starting, Waiting for you, Working, Needs attention or In the terminal.

button	what it does
Start	start Claude Code for this pixie now, asking first if you cancelled before
Open terminal	Claude Code's own interface, on the same conversation, in the panel
Hand back to chat	close the terminal; the chat takes over again
Stop	end Claude Code for this pixie

While the terminal is open, the pixie's chat shows "In the Terminal view on this Mac — chat messages wait until it is closed." In the terminal, Claude Code asks its own permission questions, as it does anywhere else. When you hand back, the conversation shows up in the chat: each prompt you sent there as your message, and Claude Code's replies after it. Only prompts you sent arrive, not keystrokes, slash commands or their output. Open terminal waits for a turn to end: while the pixie is working it says "wait for its turn to end, or stop it".

stop it

• Stop in Terminal pixies ends it now. The next message you type starts it again.
• After 30 minutes with nothing to do, ixi stops it: "Stopped after a while idle — message the pixie to start it again."
• Quitting ixi stops every terminal pixie.
• To go back to ixi's own pixie, set Runtime back to ixi (built in). Claude Code loses its access to the canvas at once, and your messages go to ixi's pixie again. The Claude Code process keeps running until it idles out; press Stop to end it straight away.

limits & good to know

• Claude Code only, for now.
• ixi never skips Claude Code's permission prompts. It refuses to start Claude Code with any option that would.
• It stays on this Mac. A pixie's runtime setting and its Claude Code session never travel with a project to ixi Cloud. There, it's an ixi pixie again.
• Claude Code's own rules apply. Rules in your Claude Code settings that name ixi-pixie tools apply to this pixie. Rules for an MCP server named ixi, such as ixi Cloud's, don't.
• Your Claude account pays. Turns count against your Claude plan or API account, not against anything in ixi.

related

• keys, connectors and models: the models ixi's own pixies think with.
• chat: the dock, question cards and approval cards.
• customize ixi: change ixi itself with Claude Code or another agent.