Tzara

Your agent for building physical AI systems with Telekinesis. Tzara is an AI-powered assistant built for developers working with the Telekinesis Agentic Skill Library. It helps you design, understand, and implement perception-to-action pipelines and can be used directly inside VS Code.

Setup

The agent is implemented in Python; the VS Code UI remains a small TypeScript extension. Platform-specific VSIX releases bundle the Python runtime. For development and release commands, see docs/python.md. For a guided source walkthrough, start with the codebase reading guide.

1. Requirements

• VS Code Extension: Install "Tzara" from the Marketplace.
• Telekinesis SDK: pip install telekinesis-ai
• Python 3.11+ (Optional - if you want to run generated code)

2. Configure API Keys

Tzara requires an Anthropic key for reasoning and a Telekinesis key for skill access.

Windows (PowerShell)

setx ANTHROPIC_API_KEY "<your_key>"
setx TELEKINESIS_API_KEY "<your_key>"

# Also set in the current shell session
$env:ANTHROPIC_API_KEY="<your_key>"
$env:TELEKINESIS_API_KEY="<your_key>"

# Verify
echo $env:ANTHROPIC_API_KEY
echo $env:TELEKINESIS_API_KEY

Note: setx updates future PowerShell sessions. If you open a new terminal, the keys will already be available.

macOS / Linux First, determine your shell type:

echo $SHELL

Then run the commands for your shell:

# bash
echo 'export ANTHROPIC_API_KEY="<your_key>"' >> ~/.bashrc && echo 'export TELEKINESIS_API_KEY="<your_key>"' >> ~/.bashrc && source ~/.bashrc

# zsh
echo 'export ANTHROPIC_API_KEY="<your_key>"' >> ~/.zshrc && echo 'export TELEKINESIS_API_KEY="<your_key>"' >> ~/.zshrc && source ~/.zshrc

# fish
echo 'set -gx ANTHROPIC_API_KEY "<your_key>"' >> ~/.config/fish/config.fish && echo 'set -gx TELEKINESIS_API_KEY "<your_key>"' >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish

Verify the keys are set:

echo $ANTHROPIC_API_KEY
echo $TELEKINESIS_API_KEY

3. Enable Code Quality Self-Correction (Optional)

When the planner generates a pipeline, Tzara can automatically run pyright (type checks) against the result and feed any errors back to the model so it can self-correct before returning the final code. Once pyright is clean, ruff runs with --fix to clean up unused imports/variables and other auto-fixable issues. The chat panel's status trail shows each iteration (pyright (iter 1), regenerating (fix 1), ruff --fix, …) so you can watch the loop run.

This is enabled by default. To activate the checks you need to:

1. Install pyright and/or ruff in the Python interpreter your project uses:

   pip install pyright ruff
   

2. Tell VS Code which interpreter to use. Open the command palette → Python: Select Interpreter and pick the environment where you installed them. Tzara reuses whatever the Python extension has selected, so it sees the same packages your code imports.

If neither tool is installed in that interpreter, Tzara silently skips the checks (you'll see a pyright skipped (pyright-not-found) or ruff not installed in env pill in the trail) and returns the planner's initial output unmodified.

What gets reported

• Pyright runs in basic mode against a copy of the generated pipeline. Real type errors (e.g. wrong argument types, unknown attributes) drive correction. Missing-import diagnostics (where the library exists at runtime but pyright has no stubs for it) are ignored so Tzara doesn't loop on environment quirks.
• Ruff runs with --fix after pyright is clean, applying its default ruleset to clean up unused imports, unused variables, and other auto-fixable lint issues.

Settings

Quick Start: From Prompt to Production

Tzara understands the modular structure of Telekinesis.

Ask it to "Use the Zivid and detect all the screws on the table" and it generates production-ready orchestration like this:

from loguru import logger

from telekinesis import vitreous, medulla

# Step 1: Capture and segment the dominant plane
captured_point_cloud = medulla.zivid.capture_point_cloud()

segmented_point_cloud, plane_model = vitreous.segment_point_cloud_using_plane(
    point_cloud=captured_point_cloud,
    distance_threshold=1.5,
)
logger.success(f"Segmented {len(segmented_point_cloud.positions)} points using plane")

# Step 2: Keep points on the negative side of the plane (e.g. objects above the table)
positive_side_cloud = vitreous.filter_point_cloud_using_plane_splitting(
    point_cloud=segmented_point_cloud,
    plane_coefficients=plane_model,
    keep_positive_side=False,
)
logger.success("Filtered points using plane splitting")

# Step 3: Filter points near the plane
near_plane_cloud = vitreous.filter_point_cloud_using_plane_proximity(
    point_cloud=captured_point_cloud,
    plane_coefficients=plane_model,
    distance_threshold=1.0,
)
logger.success("Filtered points using plane proximity")

# Step 4: Subtract near-plane points
subtracted_cloud = vitreous.subtract_point_clouds(
    point_cloud1=positive_side_cloud,
    point_cloud2=near_plane_cloud,
    distance_threshold=1.0,
)
logger.success("Subtracted point clouds")

# Step 5: Cluster using DBSCAN
clustered_clouds = vitreous.cluster_point_cloud_using_dbscan(
    point_cloud=subtracted_cloud,
    max_distance=3.5,
    min_points=600,
)
logger.success(
    f"Clustered point cloud with {len(subtracted_cloud.positions)} points "
    f"using DBSCAN into {len(clustered_clouds.to_list())} clusters"
)

# Step 6: Compute oriented bounding boxes
bboxes = []
for idx, cluster_cloud in enumerate(clustered_clouds.to_list()):
    bbox = vitreous.calculate_oriented_bounding_box(
        point_cloud=cluster_cloud,
        minimize_bbox_volume=True,
        use_robust_fitting=True,
    )
    bboxes.append(bbox)

Features

• End-to-End Orchestration: Generate complete perception-to-action loops (e.g., "Build a vision-guided pick-and-place pipeline for a conveyor system").
• Skill Discovery: Identifies the right skills for your problem and shows how to use and combine them in practice.
• Spatial Reasoning: Analyze images/point clouds to suggest the best perception strategy.
• Self-Correcting Pipelines: Generate a persistent draft once, apply Ruff fixes, check with Pyright, and repair diagnostics with exact patches before completion review. See setup step 3.
• Zero-Config Debugging: Analyzes logs, signals, and execution traces end-to-end to isolate the exact source of errors across hardware and software.

💡 Example Workflows

Why Tzara?

Building Physical AI is difficult because it requires bridging the gap between high-level intent and low-level geometry. Tzara eliminates the "glue code" phase, letting you iterate on robotic behavior in minutes instead of days.

Telekinesis provides the building blocks for Physical AI. Tzara is the fastest way to turn those blocks into working systems. Design, iterate, and deploy in a single continuous loop.

Documentation | Discord | Website

Pipeline drafts and checks

The planner writes .tzara-draft-<id>.py beside the intended target so imports and nearby configuration remain in the same directory context. Its .py.json sidecar records the target's original hash, draft revision/hash, check status and repair feedback. Drafts remain available after cancellation, failure and publication for inspection or manual recovery; a new request does not automatically resume an old draft. These files can be removed when no request is using them.

Checks use the selected project interpreter and workspace working directory. Ruff fixes the draft before Pyright runs. Missing checkers, launch failures and timeouts are reported as unavailable and are not retried within the same request. Install Ruff/Pyright in that interpreter to enable them; an unavailable check is not a pass. Traces record commands, working directories, file hashes, duration and output.

Implementation defects are repaired locally with exact, nonoverlapping patches; only missing evidence or user decisions return to the main agent. The loop stops at six proposals, repeated identical findings, a no-change repair, or the configured type-check iteration limit, and returns the retained draft and unresolved issues. The target is published only after completion review. Existing targets still need host approval, now with a diff preview, and concurrent target edits reject publication.

Planner retries replace the current objective and context rather than appending earlier versions; original user requests and clarification answers remain available for completion review. The draft sidecar stores the current task specification. SDK prompts include the selected plan contracts and their supporting types, not every previously read symbol. Repairs receive a function outline, up to 16,000 characters of exact source excerpts, diagnostics and affected-stage contracts. The writer can call read_draft, search_sdk, read_sdk_symbol, and read_sdk_file directly, bounded to 12 retrieval rounds and 32 calls per writer invocation. Final review receives the complete draft, full plan, user requirements and additional evidence retrieved by the writer. Focused repair context does not weaken that review.

Debug traces

Enable tzara.debug.traceEnabled in VS Code settings, start a new request, then run Tzara: Open Debug Log. Each request produces a JSONL trace that is flushed as events arrive. Traces include model prompts and responses, generated drafts, tool arguments (including grep patterns, paths and limits), raw and validated tool results, and check commands, stdout, stderr, results and timeout details. tool_operation_request / tool_operation_result contain structured tool data; tool_request / tool_result correlate the agent's calls through call_id. Nested operations use span_id and parent_id; sequence numbers preserve event order.

There is no per-request trace size cutoff. Tool search/read limits still apply: the trace records exactly what the tool returned, including its truncation flags, not extra matches that the tool never returned. Known credentials are redacted; image payloads and reasoning blocks are omitted. Traces can contain private code. Tracing applies to new requests and cannot reconstruct earlier unrecorded runs.