diff --git a/.gitignore b/.gitignore
index 26cc2fb..1178202 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,6 +6,10 @@
 .claude/
 CLAUDE.md
 
+# Variáveis de ambiente locais (o setup do Superset copia da raiz)
+.env
+.env.*
+
 # Build
 target/
 node_modules/
diff --git a/.superset/config.json b/.superset/config.json
new file mode 100644
index 0000000..9a98d9f
--- /dev/null
+++ b/.superset/config.json
@@ -0,0 +1,5 @@
+{
+  "setup": ["./.superset/setup.sh"],
+  "teardown": ["./.superset/teardown.sh"],
+  "run": ["cargo run -p guara-cli -- ui --no-open"]
+}
diff --git a/.superset/setup.sh b/.superset/setup.sh
new file mode 100755
index 0000000..786aea0
--- /dev/null
+++ b/.superset/setup.sh
@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# Runs once when a Superset workspace (git worktree) is created. Safe to run again.
+set -euo pipefail
+
+# Local files that are not tracked by git but that a new worktree needs.
+# Nothing is overwritten if it already exists in the workspace.
+if [ -n "${SUPERSET_ROOT_PATH:-}" ] && [ -d "$SUPERSET_ROOT_PATH" ]; then
+  for f in "$SUPERSET_ROOT_PATH"/.env "$SUPERSET_ROOT_PATH"/.env.* "$SUPERSET_ROOT_PATH"/CLAUDE.md; do
+    [ -f "$f" ] || continue
+    dest="./$(basename "$f")"
+    [ -e "$dest" ] || cp "$f" "$dest"
+  done
+fi
+
+# Download the crates now so the first build and the first test run do not wait on the network.
+cargo fetch --locked
diff --git a/.superset/teardown.sh b/.superset/teardown.sh
new file mode 100755
index 0000000..1364466
--- /dev/null
+++ b/.superset/teardown.sh
@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# Runs when a Superset workspace is deleted.
+# Setup starts no background service. The only long-running process is the Run command
+# (`guara ui`), which this workspace builds into its own target/ directory, so stop any
+# copy that is still alive before the worktree is removed.
+set -uo pipefail
+
+pkill -f -- "$PWD/target/.*/guara ui" 2>/dev/null || true
+exit 0