Working with Tzara in VS Code

Tzara runs as a VS Code extension. You describe a task in chat; Tzara researches the Skills it needs, writes or edits Python files in your workspace, and asks for your approval before changing existing files or running commands. This page covers the day-to-day workflow. To install the extension, see Install the Telekinesis Agent.

Requirements

• VS Code 1.80 or newer with the Tzara extension installed. The agent's runtime is bundled with the extension.
• A model provider. An API key for Anthropic, OpenAI, or Google Gemini — or a local Ollama server.
• A trusted workspace folder for Tzara to read and write files. Without one, Tzara can still answer questions, but it can't save code.
• A Python environment (recommended) with the Telekinesis SDK (pip install telekinesis-ai) to run the generated code. Install ruff and pyright in the same environment to enable Tzara's code checks. Tzara uses the interpreter selected through the VS Code Python extension (Python: Select Interpreter).

Opening Tzara

• Session Manager — click the Tzara icon in the Activity Bar. It lists New session followed by your saved conversations. Select one to open it in a chat editor on the right. Its toolbar has a history button and a gear that opens Tzara Settings.
• Editor toolbar — click the Tzara icon at the top right of an editor to open your latest chat.
• Command Palette — run Tzara: Open Chat.

Choosing Models

The chat composer has two model pickers:

Picker	Used for
Agent	The conversation itself: understanding your request, researching Skills, reading files, and deciding what to do next
Code	Writing, repairing, and reviewing generated code

Both list models from Anthropic, OpenAI, Gemini, and Ollama. Choose Custom model id… under a provider to enter any model name that provider supports — for Ollama, use the name of a model you have pulled locally. Select a model in both pickers before your first request; your choice is remembered.

Tzara reads API keys from the ANTHROPIC_API_KEY, OPENAI_API_KEY, and GOOGLE_API_KEY environment variables. You can instead run Tzara: Set API Key, pick the provider, and paste the key; it is stored in VS Code's secret storage and takes precedence over the environment variable. Ollama needs no key; set tzara.ollama.baseUrl if your server isn't at http://localhost:11434.

Sending a Request

Type in the composer and press Enter to send (Shift+Enter adds a new line). Above the composer you can attach context for this message:

• the paperclip attaches an image,
• + File, + Folder, and + Selection attach workspace text, a folder listing, or your current editor selection.

See Attachments for what each one sends. While Tzara works, the send button becomes a Stop button that cancels the current request.

What Happens During a Request

Tzara's tool activity for each response is grouped in a collapsible log. The header shows the current step; expand it to see each call, its timing, and any error details.

For a code request, Tzara typically:

1. Gathers context — reads relevant Skill contracts, your workspace files, and any Task Rules that apply.
2. Asks questions if something essential is missing. Question cards show suggested options and a Something else… choice for your own answer. Click Continue to answer, or Cancel to stop the request.
3. Writes a draft of the target file.
4. Checks and repairs the draft with Ruff and Pyright (when installed), then reviews it against your request.
5. Saves the file — after your approval if it replaces an existing file — and summarizes what changed.

If the draft can't be completed, Tzara reports the unresolved issues instead of saving it. The draft is kept next to the target as a .tzara-draft-*.py file so you can inspect it, or ask Tzara to continue from it in a later message. You can delete these drafts once you no longer need them.

Approvals and Reviewing Changes

Changed files

The Changed files panel above the composer collects every file Tzara creates or edits in the conversation. Expand a file to see each revision and its diff.

• Editing or overwriting an existing file waits for your decision: Allow once or Deny beside the diff. Approve pending and Reject pending decide all requests currently waiting.
• New files are created without a separate approval step and are listed in the panel.
• After approval, a change shows Approved · Awaiting save result, then Applied once it has been saved. Denied, failed, and interrupted changes stay visible.

Tzara refuses to overwrite a file that has unsaved changes in your editor, or one that changed on disk while it was working.

No undo

Applied changes cannot be rolled back from the panel. Use version control (for example, Git) to undo changes.

Terminal commands

When Tzara wants to run a command, it shows a Run terminal command card with the exact command and working directory. Click Run once to run it or Reject to refuse. The same card then shows the output and exit code. Each approval covers that one command only. Changes a command makes to files don't appear in the Changed files panel.

Automatic approval and tool policies

• Automatically approve actions in Tzara Settings (tzara.approvals.autoApprove) approves subsequent file changes, commands, and simulation runs in trusted workspaces. Tzara still asks questions about missing task details.

• tzara.tools.policy (user settings) sets allow, ask, or deny rules per tool. deny beats ask, which beats allow. For example, to always ask before writing files:

  "tzara.tools.policy": [
    { "tool": "write_project_file", "action": "ask" }
  ]

  An allow rule for a file tool doesn't skip the file-change approval.

Approve with care

Approved commands and simulation runs execute with your user account's permissions; they are not sandboxed. Turn on automatic approval only in workspaces where that is acceptable, and never for code that can move a real robot.

Sessions

Every conversation is saved locally and appears in the Session Manager.

• + New chat in the chat (or Tzara: New Chat) starts a separate conversation in its own tab. Other conversations, including ones still running, are not affected.
• History (or Tzara: Chat History) reopens a saved conversation.
• To delete a session, hover over it in the Session Manager and click the trash icon, or run Tzara: Delete Session. Deleting removes the conversation but keeps files Tzara generated. It cannot be undone.

Closing a chat tab cancels its running request; the conversation itself is kept. Reopened conversations show earlier approval and command cards for reference, but they can't be used to approve anything again.

Conversations are stored as plain files in VS Code's extension storage on your machine. They may contain source code, images, and other sensitive content.

Tzara Settings

Open with the gear in the Session Manager or Tzara: Settings.

Field	What it does
User Context	Standing context sent with every request. See User Context.
Max output tokens	Maximum length of each model response (default 16000).
Run pyright on generated pipelines	Turns Pyright checking on or off. The text field sets the Python interpreter used for Pyright and Ruff; leave it empty to use VS Code's selected interpreter.
Automatically approve actions	Approves file changes, commands, and simulation runs without asking, in trusted workspaces.
Personal Skill Library Folder Path	Folder of your own .py helper modules. See Personal Skill Library.
Task Rules Folder Path	Folder of taskRule.md rules. See Task Rules.
Output workspace	Select output folder… sets the folder where Tzara reads and writes files, without switching VS Code windows. Use VS Code workspace goes back to the open folder. Manage workspace trust opens VS Code's trust settings.
Enable scene inspection and simulation, Isaac Sim bridge URL, Simulation Python executable, Isaac Sim scene (USD)	Isaac Sim validation. See Validate in Isaac Sim.

Output workspace and simulation changes apply to your next request.

VS Code Settings

These settings are available under Settings › Extensions › Tzara.

Setting	Default	Description
tzara.approvals.autoApprove	false	Approve file changes, commands, and simulation runs automatically in trusted workspaces.
tzara.tools.policy	[]	Allow/ask/deny rules per tool (user settings only).
tzara.pyrightCheck.enabled	true	Run Pyright on generated code and repair the errors it reports.
tzara.pyrightCheck.pythonPath	""	Interpreter for Pyright and Ruff. Empty uses VS Code's selected interpreter.
tzara.pipeline.repairsEnabled	true	Automatically repair drafts after failed checks or review. Turn off for one-pass generation.
tzara.pipeline.timeoutSeconds	1800	Time limit for one code generation, including research, drafting, repairs, and review (60–3600).
tzara.ollama.baseUrl	http://localhost:11434	Ollama server used when an Ollama model is selected.
tzara.debug.traceEnabled	false	Write a detailed debug trace for each request (see below).
tzara.simulation.*		Isaac Sim settings. See Validate in Isaac Sim.

Commands

Command	What it does
Tzara: Open Chat	Opens your latest conversation in an editor on the right.
Tzara: Open Chat in Editor	Same as Tzara: Open Chat.
Tzara: New Chat	Starts a new conversation.
Tzara: Chat History	Picks a saved conversation to open.
Tzara: Delete Session	Deletes a saved conversation.
Tzara: Settings	Opens Tzara Settings.
Tzara: Set API Key	Stores an Anthropic, OpenAI, or Gemini API key in VS Code's secret storage.
Tzara: Open Debug Log	Opens a saved debug trace.

Debug Traces

To see exactly what Tzara did on a request — the prompts it sent, the tools it called and what they returned, and the generated drafts — enable tzara.debug.traceEnabled, send the request, then run Tzara: Open Debug Log and pick the newest trace. The setting applies to new requests.

Traces are stored locally and are never uploaded. Known API keys are redacted, but traces can contain your source code and other private data: review a trace before sharing it, and turn the setting off when you're done.