Skip to content

Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.

Add project script actions with run shortcuts and persistence

Julius Marminge3537d4770275
diff --git a/KEYBINDINGS.md b/KEYBINDINGS.md
index a44f1f5f4..001cebba1 100644
--- a/KEYBINDINGS.md
+++ b/KEYBINDINGS.md
@@ -53,6 +53,7 @@ Invalid rules are ignored. Invalid config files are ignored. Warnings are logged
- `chat.new`: create a new chat thread preserving the active thread's branch/worktree state
- `chat.newLocal`: create a new local chat thread for the active project (no worktree context)
- `editor.openFavorite`: open current project/worktree in the last-used editor
+- `script.{id}.run`: run a project script by id (for example `script.test.run`)
### Key Syntax
diff --git a/apps/server/src/projectRegistry.test.ts b/apps/server/src/projectRegistry.test.ts
new file mode 100644
index 000000000..199e69d00
--- /dev/null
+++ b/apps/server/src/projectRegistry.test.ts
@@ -0,0 +1,113 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import { ProjectRegistry } from "./projectRegistry";
+
+const tempDirs: string[] = [];
+
+function makeTempDir(prefix: string): string {
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+ tempDirs.push(dir);
+ return dir;
+}
+
+afterEach(() => {
+ for (const dir of tempDirs.splice(0, tempDirs.length)) {
+ fs.rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+describe("ProjectRegistry scripts", () => {
+ it("stores and reloads project scripts", () => {
+ const stateDir = makeTempDir("t3code-project-registry-state-");
+ const projectDir = makeTempDir("t3code-project-registry-project-");
+ const registry = new ProjectRegistry(stateDir);
+
+ const created = registry.add({ cwd: projectDir }).project;
+ const updated = registry.updateScripts({
+ id: created.id,
+ scripts: [
+ {
+ id: "run",
+ name: "Run",
+ command: "bun run dev",
+ icon: "play",
+ runOnWorktreeCreate: false,
+ },
+ {
+ id: "setup",
+ name: "Setup",
+ command: "bun install",
+ icon: "configure",
+ runOnWorktreeCreate: true,
+ },
+ ],
+ });
+
+ expect(updated.project.scripts).toHaveLength(2);
+ expect(updated.project.scripts[1]?.id).toBe("setup");
+ expect(updated.project.scripts[1]?.runOnWorktreeCreate).toBe(true);
+
+ const reloaded = new ProjectRegistry(stateDir);
+ const listed = reloaded.list();
+ expect(listed).toHaveLength(1);
+ expect(listed[0]?.scripts).toHaveLength(2);
+ expect(listed[0]?.scripts[0]?.id).toBe("run");
+ expect(listed[0]?.scripts[1]?.id).toBe("setup");
+ });
+
+ it("deduplicates script ids and allows only one setup script", () => {
+ const stateDir = makeTempDir("t3code-project-registry-state-");
+ const projectDir = makeTempDir("t3code-project-registry-project-");
+ const registry = new ProjectRegistry(stateDir);
+ const created = registry.add({ cwd: projectDir }).project;
+
+ const updated = registry.updateScripts({
+ id: created.id,
+ scripts: [
+ {
+ id: "setup",
+ name: "Setup",
+ command: "echo setup",
+ icon: "configure",
+ runOnWorktreeCreate: true,
+ },
+ {
+ id: "setup",
+ name: "Setup Duplicate",
+ command: "echo duplicate",
+ icon: "configure",
+ runOnWorktreeCreate: true,
+ },
+ {
+ id: "another",
+ name: "Another Setup",
+ command: "echo another",
+ icon: "play",
+ runOnWorktreeCreate: true,
+ },
+ ],
+ });
+
+ expect(updated.project.scripts).toHaveLength(2);
+ expect(updated.project.scripts[0]?.id).toBe("setup");
+ expect(updated.project.scripts[0]?.runOnWorktreeCreate).toBe(true);
+ expect(updated.project.scripts[1]?.id).toBe("another");
+ expect(updated.project.scripts[1]?.runOnWorktreeCreate).toBe(false);
+ });
+
+ it("throws when updating scripts for an unknown project id", () => {
+ const stateDir = makeTempDir("t3code-project-registry-state-");
+ const registry = new ProjectRegistry(stateDir);
+
+ expect(() =>
+ registry.updateScripts({
+ id: "missing-project",
+ scripts: [],
+ }),
+ ).toThrowError("Project not found");
+ });
+});
diff --git a/apps/server/src/projectRegistry.ts b/apps/server/src/projectRegistry.ts
index 5b29fbfed..b6b56cbe3 100644
--- a/apps/server/src/projectRegistry.ts
+++ b/apps/server/src/projectRegistry.ts
@@ -8,11 +8,30 @@ import {
type ProjectListResult,
type ProjectRecord,
type ProjectRemoveInput,
+ type ProjectScript,
+ type ProjectUpdateScriptsInput,
+ type ProjectUpdateScriptsResult,
projectAddInputSchema,
projectRecordSchema,
projectRemoveInputSchema,
+ projectScriptsSchema,
+ projectUpdateScriptsInputSchema,
} from "@t3tools/contracts";
+function cloneScripts(scripts: readonly ProjectScript[]): ProjectScript[] {
+ const cloned: ProjectScript[] = [];
+ for (const script of scripts) {
+ cloned.push({
+ id: script.id,
+ name: script.name,
+ command: script.command,
+ icon: script.icon,
+ runOnWorktreeCreate: script.runOnWorktreeCreate,
+ });
+ }
+ return cloned;
+}
+
function normalizeCwd(rawCwd: string): string {
const resolved = path.resolve(rawCwd.trim());
const normalized = path.normalize(resolved);
@@ -48,7 +67,10 @@ export class ProjectRegistry {
}
list(): ProjectListResult {
- return this.projects.map((project) => ({ ...project }));
+ return this.projects.map((project) => ({
+ ...project,
+ scripts: cloneScripts(project.scripts),
+ }));
}
add(raw: ProjectAddInput): ProjectAddResult {
@@ -60,7 +82,13 @@ export class ProjectRegistry {
const existing = this.projects.find((project) => normalizeCwd(project.cwd) === normalizedCwd);
if (existing) {
- return { project: { ...existing }, created: false };
+ return {
+ project: {
+ ...existing,
+ scripts: cloneScripts(existing.scripts),
+ },
+ created: false,
+ };
}
const now = new Date().toISOString();
@@ -68,13 +96,20 @@ export class ProjectRegistry {
id: randomUUID(),
cwd: normalizedCwd,
name: inferProjectName(normalizedCwd),
+ scripts: [],
createdAt: now,
updatedAt: now,
};
this.projects = [project, ...this.projects];
this.persist();
- return { project: { ...project }, created: true };
+ return {
+ project: {
+ ...project,
+ scripts: cloneScripts(project.scripts),
+ },
+ created: true,
+ };
}
remove(raw: ProjectRemoveInput): void {
@@ -88,6 +123,31 @@ export class ProjectRegistry {
this.persist();
}
+ updateScripts(raw: ProjectUpdateScriptsInput): ProjectUpdateScriptsResult {
+ const input = projectUpdateScriptsInputSchema.parse(raw);
+ const index = this.projects.findIndex((project) => project.id === input.id);
+ if (index < 0) {
+ throw new Error(`Project not found: ${input.id}`);
+ }
+
+ const nextScripts = dedupeScriptsById(projectScriptsSchema.parse(input.scripts));
+ const nextUpdatedAt = new Date().toISOString();
+ const nextProject: ProjectRecord = {
+ ...this.projects[index]!,
+ scripts: nextScripts,
+ updatedAt: nextUpdatedAt,
+ };
+
+ const nextProjects = [...this.projects];
+ nextProjects[index] = nextProject;
+ this.projects = nextProjects;
+ this.persist();
+
+ return {
+ project: { ...nextProject, scripts: cloneScripts(nextProject.scripts) },
+ };
+ }
+
private loadFromDisk(): ProjectRecord[] {
const loaded = this.readPersistedProjects();
const deduped = new Map<string, ProjectRecord>();
@@ -107,6 +167,7 @@ export class ProjectRegistry {
cwd: normalizedCwd,
name:
project.name.trim().length > 0 ? project.name.trim() : inferProjectName(normalizedCwd),
+ scripts: dedupeScriptsById(project.scripts),
};
deduped.set(normalizedCwd, normalizedProject);
normalizedProjects.push(normalizedProject);
@@ -121,6 +182,7 @@ export class ProjectRegistry {
source.id !== project.id ||
source.cwd !== project.cwd ||
source.name !== project.name ||
+ JSON.stringify(source.scripts) !== JSON.stringify(project.scripts) ||
source.createdAt !== project.createdAt ||
source.updatedAt !== project.updatedAt
);
@@ -170,3 +232,35 @@ export class ProjectRegistry {
fs.renameSync(tempFile, this.filePath);
}
}
+
+function dedupeScriptsById(scripts: readonly ProjectScript[]): ProjectScript[] {
+ const seenIds = new Set<string>();
+ const deduped: ProjectScript[] = [];
+ for (const script of scripts) {
+ if (seenIds.has(script.id)) continue;
+ seenIds.add(script.id);
+ deduped.push({
+ id: script.id,
+ name: script.name,
+ command: script.command,
+ icon: script.icon,
+ runOnWorktreeCreate: script.runOnWorktreeCreate,
+ });
+ }
+
+ let setupAssigned = false;
+ const normalized: ProjectScript[] = [];
+ for (const script of deduped) {
+ if (!script.runOnWorktreeCreate) {
+ normalized.push(script);
+ continue;
+ }
+ if (!setupAssigned) {
+ setupAssigned = true;
+ normalized.push(script);
+ continue;
+ }
+ normalized.push({ ...script, runOnWorktreeCreate: false });
+ }
+ return normalized;
+}
diff --git a/apps/server/src/wsServer.test.ts b/apps/server/src/wsServer.test.ts
index 9c406357a..7ccc09069 100644
--- a/apps/server/src/wsServer.test.ts
+++ b/apps/server/src/wsServer.test.ts
@@ -756,6 +756,42 @@ describe("WebSocket Server", () => {
expect(projectId).toBeTruthy();
if (!projectId) return;
+ const updatedScripts = await sendRequest(ws, WS_METHODS.projectsUpdateScripts, {
+ id: projectId,
+ scripts: [
+ {
+ id: "setup",
+ name: "Setup",
+ command: "bun install",
+ icon: "configure",
+ runOnWorktreeCreate: true,
+ },
+ ],
+ });
+ expect(updatedScripts.error).toBeUndefined();
+ const scriptPayload = (
+ updatedScripts.result as {
+ project: {
+ scripts: Array<{
+ id: string;
+ name: string;
+ command: string;
+ icon: string;
+ runOnWorktreeCreate: boolean;
+ }>;
+ };
+ }
+ ).project.scripts;
+ expect(scriptPayload).toEqual([
+ {
+ id: "setup",
+ name: "Setup",
+ command: "bun install",
+ icon: "configure",
+ runOnWorktreeCreate: true,
+ },
+ ]);
+
const removed = await sendRequest(ws, WS_METHODS.projectsRemove, {
id: projectId,
});
diff --git a/apps/server/src/wsServer.ts b/apps/server/src/wsServer.ts
index 1ffc04ba8..bf5f26b5b 100644
--- a/apps/server/src/wsServer.ts
+++ b/apps/server/src/wsServer.ts
@@ -322,6 +322,8 @@ export function createServer(options: ServerOptions) {
case WS_METHODS.projectsSearchEntries:
return searchWorkspaceEntries(request.params as never);
+ case WS_METHODS.projectsUpdateScripts:
+ return projectRegistry.updateScripts(request.params as never);
case WS_METHODS.shellOpenInEditor: {
const params = request.params as {
diff --git a/apps/web/src/App.tsx b/apps/web/src/App.tsx
index fbb1177bf..85fc77c00 100644
--- a/apps/web/src/App.tsx
+++ b/apps/web/src/App.tsx
@@ -85,6 +85,7 @@ function AutoProjectBootstrap() {
cwd: payload.cwd,
model: DEFAULT_MODEL,
expanded: true,
+ scripts: [],
},
});
dispatch({
@@ -146,6 +147,7 @@ function DesktopProjectBootstrap() {
cwd: project.cwd,
model: DEFAULT_MODEL,
expanded: true,
+ scripts: project.scripts,
})),
});
bootstrappedRef.current = true;
diff --git a/apps/web/src/components/ChatView.tsx b/apps/web/src/components/ChatView.tsx
index 7be96df9c..5841877fd 100644
--- a/apps/web/src/components/ChatView.tsx
+++ b/apps/web/src/components/ChatView.tsx
@@ -1,9 +1,10 @@
import {
EDITORS,
type EditorId,
+ type NativeApi,
type ProjectEntry,
+ type ProjectScript,
ModelSlug,
- type NativeApi,
PROVIDER_SEND_TURN_MAX_INPUT_CHARS,
PROVIDER_SEND_TURN_MAX_ATTACHMENTS,
PROVIDER_SEND_TURN_MAX_IMAGE_BYTES,
@@ -66,10 +67,7 @@ import BranchToolbar from "./BranchToolbar";
import GitActionsControl from "./GitActionsControl";
import {
isOpenFavoriteEditorShortcut,
- isTerminalCloseShortcut,
- isTerminalNewShortcut,
- isTerminalSplitShortcut,
- isTerminalToggleShortcut,
+ resolveShortcutCommand,
shortcutLabelForCommand,
} from "../keybindings";
import ChatMarkdown from "./ChatMarkdown";
@@ -97,6 +95,13 @@ import { CursorIcon, Icon } from "./Icons";
import { cn, isMacPlatform, isWindowsPlatform } from "~/lib/utils";
import { Badge } from "./ui/badge";
import { Command, CommandInput, CommandItem, CommandList } from "./ui/command";
+import ProjectScriptsControl, { type NewProjectScriptInput } from "./ProjectScriptsControl";
+import {
+ injectEnvIntoShellCommand,
+ nextProjectScriptId,
+ projectScriptIdFromCommand,
+ setupProjectScript,
+} from "~/projectScripts";
function formatMessageMeta(createdAt: string, duration: string | null): string {
if (!duration) return formatTimestamp(createdAt);
@@ -117,6 +122,8 @@ const SEARCHABLE_MODEL_OPTIONS = MODEL_OPTIONS.map(({ slug, name }) => ({
searchSlug: slug.toLowerCase(),
searchName: name.toLowerCase(),
}));
+const SCRIPT_TERMINAL_COLS = 120;
+const SCRIPT_TERMINAL_ROWS = 30;
function workToneClass(tone: "thinking" | "tool" | "info" | "error"): string {
if (tone === "error") return "text-rose-300/50 dark:text-rose-300/50";
@@ -618,6 +625,125 @@ export default function ChatView() {
},
[activeThread?.terminalIds.length, activeThreadId, api, dispatch],
);
+ const runProjectScript = useCallback(
+ async (
+ script: ProjectScript,
+ options?: {
+ cwd?: string;
+ env?: Record<string, string>;
+ preferNewTerminal?: boolean;
+ },
+ ) => {
+ if (!api || !activeThreadId || !activeProject || !activeThread) return;
+ const targetCwd = options?.cwd ?? gitCwd ?? activeProject.cwd;
+ const baseTerminalId = activeThread.activeTerminalId;
+ const isBaseTerminalBusy = activeThread.runningTerminalIds.includes(baseTerminalId);
+ const shouldCreateNewTerminal = Boolean(options?.preferNewTerminal) || isBaseTerminalBusy;
+ const targetTerminalId = shouldCreateNewTerminal
+ ? `terminal-${crypto.randomUUID()}`
+ : baseTerminalId;
+
+ dispatch({
+ type: "SET_THREAD_TERMINAL_OPEN",
+ threadId: activeThreadId,
+ open: true,
+ });
+ if (shouldCreateNewTerminal) {
+ dispatch({
+ type: "NEW_THREAD_TERMINAL",
+ threadId: activeThreadId,
+ terminalId: targetTerminalId,
+ });
+ } else {
+ dispatch({
+ type: "SET_THREAD_ACTIVE_TERMINAL",
+ threadId: activeThreadId,
+ terminalId: targetTerminalId,
+ });
+ }
+ setTerminalFocusRequestId((value) => value + 1);
+
+ const scriptEnv =
+ options?.env ??
+ (script.runOnWorktreeCreate ? { T3CODE_PROJECT_ROOT: activeProject.cwd } : undefined);
+ const resolvedCommand = scriptEnv
+ ? injectEnvIntoShellCommand(script.command, scriptEnv)
+ : script.command;
+
+ try {
+ await api.terminal.open({
+ threadId: activeThreadId,
+ terminalId: targetTerminalId,
+ cwd: targetCwd,
+ cols: SCRIPT_TERMINAL_COLS,
+ rows: SCRIPT_TERMINAL_ROWS,
+ });
+ await api.terminal.write({
+ threadId: activeThreadId,
+ terminalId: targetTerminalId,
+ data: `${resolvedCommand}\n`,
+ });
+ } catch (error) {
+ dispatch({
+ type: "SET_ERROR",
+ threadId: activeThreadId,
+ error: error instanceof Error ? error.message : `Failed to run script "${script.name}".`,
+ });
+ }
+ },
+ [activeProject, activeThread, activeThreadId, api, dispatch, gitCwd],
+ );
+ const saveProjectScript = useCallback(
+ async (input: NewProjectScriptInput) => {
+ if (!activeProject) return;
+ const nextId = nextProjectScriptId(
+ input.name,
+ activeProject.scripts.map((script) => script.id),
+ );
+ const nextScript: ProjectScript = {
+ id: nextId,
+ name: input.name,
+ command: input.command,
+ icon: input.icon,
+ runOnWorktreeCreate: input.runOnWorktreeCreate,
+ };
+ const nextScripts = input.runOnWorktreeCreate
+ ? [
+ ...activeProject.scripts.map((script) =>
+ script.runOnWorktreeCreate ? { ...script, runOnWorktreeCreate: false } : script,
+ ),
+ nextScript,
+ ]
+ : [...activeProject.scripts, nextScript];
+
+ dispatch({
+ type: "SET_PROJECT_SCRIPTS",
+ projectId: activeProject.id,
+ scripts: nextScripts,
+ });
+
+ if (!isElectron || !api) return;
+ try {
+ const updated = await api.projects.updateScripts({
+ id: activeProject.id,
+ scripts: nextScripts,
+ });
+ dispatch({
+ type: "SET_PROJECT_SCRIPTS",
+ projectId: updated.project.id,
+ scripts: updated.project.scripts,
+ });
+ } catch (error) {
+ dispatch({
+ type: "SET_PROJECT_SCRIPTS",
+ projectId: activeProject.id,
+ scripts: activeProject.scripts,
+ });
+ throw error;
+ }
+ },
+ [activeProject, api, dispatch],
+ );
const handleRuntimeModeChange = async (mode: "approval-required" | "full-access") => {
if (mode === state.runtimeMode) return;
@@ -793,14 +919,17 @@ export default function ChatView() {
terminalOpen: Boolean(activeThread?.terminalOpen),
};
- if (isTerminalToggleShortcut(event, keybindings, { context: shortcutContext })) {
+ const command = resolveShortcutCommand(event, keybindings, { context: shortcutContext });
+ if (!command) return;
+
+ if (command === "terminal.toggle") {
event.preventDefault();
event.stopPropagation();
toggleTerminalVisibility();
return;
}
- if (isTerminalSplitShortcut(event, keybindings, { context: shortcutContext })) {
+ if (command === "terminal.split") {
event.preventDefault();
event.stopPropagation();
if (!activeThread?.terminalOpen) {
@@ -814,7 +943,7 @@ export default function ChatView() {
return;
}
- if (isTerminalCloseShortcut(event, keybindings, { context: shortcutContext })) {
+ if (command === "terminal.close") {
event.preventDefault();
event.stopPropagation();
if (!activeThread?.terminalOpen) return;
@@ -822,27 +951,39 @@ export default function ChatView() {
return;
}
- if (!isTerminalNewShortcut(event, keybindings, { context: shortcutContext })) return;
+ if (command === "terminal.new") {
+ event.preventDefault();
+ event.stopPropagation();
+ if (!activeThread?.terminalOpen) {
+ dispatch({
+ type: "SET_THREAD_TERMINAL_OPEN",
+ threadId: activeThreadId,
+ open: true,
+ });
+ }
+ createNewTerminal();
+ return;
+ }
+
+ const scriptId = projectScriptIdFromCommand(command);
+ if (!scriptId || !activeProject) return;
+ const script = activeProject.scripts.find((entry) => entry.id === scriptId);
+ if (!script) return;
event.preventDefault();
event.stopPropagation();
- if (!activeThread?.terminalOpen) {
- dispatch({
- type: "SET_THREAD_TERMINAL_OPEN",
- threadId: activeThreadId,
- open: true,
- });
- }
- createNewTerminal();
+ void runProjectScript(script);
};
window.addEventListener("keydown", handler);
return () => window.removeEventListener("keydown", handler);
}, [
+ activeProject,
activeThread?.terminalOpen,
activeThread?.activeTerminalId,
activeThreadId,
closeTerminal,
createNewTerminal,
dispatch,
+ runProjectScript,
splitTerminal,
keybindings,
toggleTerminalVisibility,
@@ -1047,6 +1188,13 @@ export default function ChatView() {
branch: result.worktree.branch,
worktreePath: result.worktree.path,
});
+ const setupScript = setupProjectScript(activeProject.scripts);
+ if (setupScript) {
+ void runProjectScript(setupScript, {
+ cwd: result.worktree.path,
+ env: { T3CODE_PROJECT_ROOT: activeProject.cwd },
+ });
+ }
} catch (err) {
dispatch({
type: "SET_ERROR",
@@ -1325,10 +1473,15 @@ export default function ChatView() {
<ChatHeader
activeThreadTitle={activeThread.title}
activeProjectName={activeProject?.name}
+ activeProjectScripts={activeProject?.scripts}
keybindings={keybindings}
api={api}
gitCwd={gitCwd}
diffOpen={state.diffOpen}
+ onRunProjectScript={(script) => {
+ void runProjectScript(script);
+ }}
+ onAddProjectScript={saveProjectScript}
onToggleDiff={onToggleDiff}
/>
</header>
@@ -1652,20 +1805,26 @@ export default function ChatView() {
interface ChatHeaderProps {
activeThreadTitle: string;
activeProjectName: string | undefined;
+ activeProjectScripts: ProjectScript[] | undefined;
keybindings: ResolvedKeybindingsConfig;
api: NativeApi | undefined;
gitCwd: string | null;
diffOpen: boolean;
+ onRunProjectScript: (script: ProjectScript) => void;
+ onAddProjectScript: (input: NewProjectScriptInput) => Promise<void>;
onToggleDiff: () => void;
}
const ChatHeader = memo(function ChatHeader({
activeThreadTitle,
activeProjectName,
+ activeProjectScripts,
keybindings,
api,
gitCwd,
diffOpen,
+ onRunProjectScript,
+ onAddProjectScript,
onToggleDiff,
}: ChatHeaderProps) {
return (
@@ -1677,6 +1836,14 @@ const ChatHeader = memo(function ChatHeader({
{activeProjectName && <Badge variant="outline">{activeProjectName}</Badge>}
</div>
<div className="shrink-0 flex items-center gap-3">
+ {activeProjectScripts && (
+ <ProjectScriptsControl
+ scripts={activeProjectScripts}
+ keybindings={keybindings}
+ onRunScript={onRunProjectScript}
+ onAddScript={onAddProjectScript}
+ />
+ )}
{activeProjectName && <OpenInPicker keybindings={keybindings} />}
{activeProjectName && <GitActionsControl api={api} gitCwd={gitCwd} />}
<Button
diff --git a/apps/web/src/components/ProjectScriptsControl.tsx b/apps/web/src/components/ProjectScriptsControl.tsx
new file mode 100644
index 000000000..bc2516a4d
--- /dev/null
+++ b/apps/web/src/components/ProjectScriptsControl.tsx
@@ -0,0 +1,259 @@
+import type {
+ ProjectScript,
+ ProjectScriptIcon,
+ ResolvedKeybindingsConfig,
+} from "@t3tools/contracts";
+import {
+ ChevronDownIcon,
+ FlaskConicalIcon,
+ HammerIcon,
+ ListChecksIcon,
+ PlayIcon,
+ PlusIcon,
+ WrenchIcon,
+} from "lucide-react";
+import { type FormEvent, useMemo, useState } from "react";
+
+import {
+ commandForProjectScript,
+ nextProjectScriptId,
+ primaryProjectScript,
+} from "~/projectScripts";
+import { shortcutLabelForCommand } from "~/keybindings";
+import { Button } from "./ui/button";
+import {
+ Dialog,
+ DialogDescription,
+ DialogFooter,
+ DialogHeader,
+ DialogPanel,
+ DialogPopup,
+ DialogTitle,
+} from "./ui/dialog";
+import { Group, GroupSeparator } from "./ui/group";
+import { Input } from "./ui/input";
+import { Label } from "./ui/label";
+import { Menu, MenuItem, MenuPopup, MenuShortcut, MenuTrigger } from "./ui/menu";
+import { Select, SelectItem, SelectPopup, SelectTrigger, SelectValue } from "./ui/select";
+import { Switch } from "./ui/switch";
+import { Textarea } from "./ui/textarea";
+
+const SCRIPT_ICONS: Array<{ id: ProjectScriptIcon; label: string }> = [
+ { id: "play", label: "Play" },
+ { id: "test", label: "Test" },
+ { id: "lint", label: "Lint" },
+ { id: "configure", label: "Configure" },
+ { id: "build", label: "Build" },
+];
+
+function ScriptIcon({
+ icon,
+ className = "size-3.5",
+}: {
+ icon: ProjectScriptIcon;
+ className?: string;
+}) {
+ if (icon === "test") return <FlaskConicalIcon className={className} />;
+ if (icon === "lint") return <ListChecksIcon className={className} />;
+ if (icon === "configure") return <WrenchIcon className={className} />;
+ if (icon === "build") return <HammerIcon className={className} />;
+ return <PlayIcon className={className} />;
+}
+
+export interface NewProjectScriptInput {
+ name: string;
+ command: string;
+ icon: ProjectScriptIcon;
+ runOnWorktreeCreate: boolean;
+}
+
+interface ProjectScriptsControlProps {
+ scripts: ProjectScript[];
+ keybindings: ResolvedKeybindingsConfig;
+ onRunScript: (script: ProjectScript) => void;
+ onAddScript: (input: NewProjectScriptInput) => Promise<void> | void;
+}
+
+export default function ProjectScriptsControl({
+ scripts,
+ keybindings,
+ onRunScript,
+ onAddScript,
+}: ProjectScriptsControlProps) {
+ const [dialogOpen, setDialogOpen] = useState(false);
+ const [name, setName] = useState("");
+ const [command, setCommand] = useState("");
+ const [icon, setIcon] = useState<ProjectScriptIcon>("play");
+ const [runOnWorktreeCreate, setRunOnWorktreeCreate] = useState(false);
+ const [validationError, setValidationError] = useState<string | null>(null);
+
+ const primaryScript = useMemo(() => primaryProjectScript(scripts), [scripts]);
+ const keybindingCommandPreview = useMemo(
+ () =>
+ commandForProjectScript(
+ nextProjectScriptId(
+ name.length > 0 ? name : "script",
+ scripts.map((script) => script.id),
+ ),
+ ),
+ [name, scripts],
+ );
+
+ const submitAddScript = async (event: FormEvent) => {
+ event.preventDefault();
+ const trimmedName = name.trim();
+ const trimmedCommand = command.trim();
+ if (trimmedName.length === 0) {
+ setValidationError("Name is required.");
+ return;
+ }
+ if (trimmedCommand.length === 0) {
+ setValidationError("Command is required.");
+ return;
+ }
+
+ setValidationError(null);
+ try {
+ await onAddScript({
+ name: trimmedName,
+ command: trimmedCommand,
+ icon,
+ runOnWorktreeCreate,
+ });
+ setDialogOpen(false);
+ setName("");
+ setCommand("");
+ setIcon("play");
+ setRunOnWorktreeCreate(false);
+ } catch (error) {
+ setValidationError(error instanceof Error ? error.message : "Failed to save action.");
+ }
+ };
+
+ const openDialog = () => {
+ setValidationError(null);
+ setDialogOpen(true);
+ };
+
+ return (
+ <>
+ {primaryScript ? (
+ <Group aria-label="Project scripts">
+ <Button
+ size="xs"
+ variant="outline"
+ onClick={() => onRunScript(primaryScript)}
+ title={`Run ${primaryScript.name}`}
+ >
+ <ScriptIcon icon={primaryScript.icon} />
+ <span>{primaryScript.name}</span>
+ </Button>
+ <GroupSeparator />
+ <Menu>
+ <MenuTrigger
+ render={<Button size="icon-xs" variant="outline" aria-label="Script actions" />}
+ >
+ <ChevronDownIcon className="size-4" />
+ </MenuTrigger>
+ <MenuPopup align="end">
+ {scripts.map((script) => {
+ const shortcutLabel = shortcutLabelForCommand(
+ keybindings,
+ commandForProjectScript(script.id),
+ );
+ return (
+ <MenuItem key={script.id} onClick={() => onRunScript(script)}>
+ <ScriptIcon icon={script.icon} className="size-4" />
+ {script.runOnWorktreeCreate ? `${script.name} (Setup)` : script.name}
+ {shortcutLabel && <MenuShortcut>{shortcutLabel}</MenuShortcut>}
+ </MenuItem>
+ );
+ })}
+ <MenuItem onClick={openDialog}>
+ <PlusIcon className="size-4" />
+ Add action
+ </MenuItem>
+ </MenuPopup>
+ </Menu>
+ </Group>
+ ) : (
+ <Button size="xs" variant="outline" onClick={openDialog}>
+ <PlusIcon className="size-3.5" />
+ Add action
+ </Button>
+ )}
+
+ <Dialog onOpenChange={setDialogOpen} open={dialogOpen}>
+ <DialogPopup>
+ <form onSubmit={submitAddScript}>
+ <DialogHeader>
+ <DialogTitle>Add Action</DialogTitle>
+ <DialogDescription>
+ Actions are project-scoped commands you can run from the top bar or keybindings.
+ </DialogDescription>
+ </DialogHeader>
+ <DialogPanel className="space-y-4">
+ <div className="space-y-1.5">
+ <Label htmlFor="script-name">Name</Label>
+ <Input
+ id="script-name"
+ placeholder="Test"
+ value={name}
+ onChange={(event) => setName(event.target.value)}
+ />
+ <p className="text-xs text-muted-foreground">
+ Keybinding command: <code>{keybindingCommandPreview}</code>
+ </p>
+ </div>
+ <div className="space-y-1.5">
+ <Label htmlFor="script-command">Command</Label>
+ <Textarea
+ id="script-command"
+ placeholder="bun test"
+ value={command}
+ onChange={(event) => setCommand(event.target.value)}
+ />
+ </div>
+ <div className="space-y-1.5">
+ <Label>Icon</Label>
+ <Select
+ items={SCRIPT_ICONS.map((entry) => ({ label: entry.label, value: entry.id }))}
+ value={icon}
+ onValueChange={(value) => {
+ if (!value) return;
+ setIcon(value as ProjectScriptIcon);
+ }}
+ >
+ <SelectTrigger>
+ <SelectValue />
+ </SelectTrigger>
+ <SelectPopup>
+ {SCRIPT_ICONS.map((entry) => (
+ <SelectItem key={entry.id} value={entry.id}>
+ {entry.label}
+ </SelectItem>
+ ))}
+ </SelectPopup>
+ </Select>
+ </div>
+ <label className="flex items-center justify-between gap-3 rounded-md border border-border/70 px-3 py-2 text-sm">
+ <span>Run automatically on worktree creation (Setup)</span>
+ <Switch
+ checked={runOnWorktreeCreate}
+ onCheckedChange={(checked) => setRunOnWorktreeCreate(Boolean(checked))}
+ />
+ </label>
+ {validationError && <p className="text-sm text-destructive">{validationError}</p>}
+ </DialogPanel>
+ <DialogFooter>
+ <Button type="button" variant="outline" onClick={() => setDialogOpen(false)}>
+ Cancel
+ </Button>
+ <Button type="submit">Save action</Button>
+ </DialogFooter>
+ </form>
+ </DialogPopup>
+ </Dialog>
+ </>
+ );
+}
diff --git a/apps/web/src/components/Sidebar.tsx b/apps/web/src/components/Sidebar.tsx
index 2c29a6da4..23110cde8 100644
--- a/apps/web/src/components/Sidebar.tsx
+++ b/apps/web/src/components/Sidebar.tsx
@@ -214,6 +214,7 @@ export default function Sidebar() {
cwd: result.project.cwd,
model: DEFAULT_MODEL,
expanded: true,
+ scripts: result.project.scripts,
};
const existingById = state.projects.find((p) => p.id === project.id);
const existingByCwd = state.projects.find((p) => p.cwd === project.cwd);
@@ -241,6 +242,7 @@ export default function Sidebar() {
cwd,
model: DEFAULT_MODEL,
expanded: true,
+ scripts: [],
};
dispatch({ type: "ADD_PROJECT", project });
handleNewThread(project.id);
diff --git a/apps/web/src/keybindings.test.ts b/apps/web/src/keybindings.test.ts
index 9c17ca40b..b486a305e 100644
--- a/apps/web/src/keybindings.test.ts
+++ b/apps/web/src/keybindings.test.ts
@@ -16,6 +16,7 @@ import {
isTerminalNewShortcut,
isTerminalSplitShortcut,
isTerminalToggleShortcut,
+ resolveShortcutCommand,
shortcutLabelForCommand,
terminalNavigationShortcutData,
type ShortcutEventLike,
@@ -339,6 +340,21 @@ describe("cross-command precedence", () => {
});
});
+describe("resolveShortcutCommand", () => {
+ it("returns dynamic script commands", () => {
+ const keybindings = compile([
+ { shortcut: modShortcut("r"), command: "script.setup.run" },
+ ]);
+
+ assert.strictEqual(
+ resolveShortcutCommand(event({ key: "r", ctrlKey: true }), keybindings, {
+ platform: "Linux",
+ }),
+ "script.setup.run",
+ );
+ });
+});
+
describe("formatShortcutLabel", () => {
it("formats labels for macOS", () => {
assert.strictEqual(
diff --git a/apps/web/src/keybindings.ts b/apps/web/src/keybindings.ts
index 859602e97..e32ab01ed 100644
--- a/apps/web/src/keybindings.ts
+++ b/apps/web/src/keybindings.ts
@@ -100,11 +100,11 @@ function matchesCommandShortcut(
return resolveShortcutCommand(event, keybindings, options) === command;
}
-function resolveShortcutCommand(
+export function resolveShortcutCommand(
event: ShortcutEventLike,
keybindings: ResolvedKeybindingsConfig,
options?: ShortcutMatchOptions,
-): KeybindingCommand | null {
+): string | null {
const platform = resolvePlatform(options);
const context = resolveContext(options);
diff --git a/apps/web/src/persistenceSchema.test.ts b/apps/web/src/persistenceSchema.test.ts
index 70f4e9e5f..ff19f2a9a 100644
--- a/apps/web/src/persistenceSchema.test.ts
+++ b/apps/web/src/persistenceSchema.test.ts
@@ -20,6 +20,7 @@ describe("hydratePersistedState", () => {
cwd: "/tmp/project",
model: "gpt-5.2-codex",
expanded: true,
+ scripts: [],
},
],
threads: [
@@ -69,6 +70,7 @@ describe("hydratePersistedState", () => {
cwd: "/tmp/project",
model: "gpt-5.3-codex",
expanded: false,
+ scripts: [],
},
],
threads: [
@@ -119,6 +121,7 @@ describe("hydratePersistedState", () => {
cwd: "/tmp/project",
model: "gpt-5.3-codex",
expanded: false,
+ scripts: [],
},
],
threads: [],
@@ -140,6 +143,7 @@ describe("hydratePersistedState", () => {
cwd: "/tmp/project",
model: "gpt-5.3-codex",
expanded: true,
+ scripts: [],
},
],
threads: [
@@ -187,6 +191,7 @@ describe("hydratePersistedState", () => {
cwd: "/tmp/project",
model: "gpt-5.3-codex",
expanded: true,
+ scripts: [],
},
],
threads: [
@@ -231,6 +236,7 @@ describe("hydratePersistedState", () => {
cwd: "/tmp/project",
model: "gpt-5.3-codex",
expanded: true,
+ scripts: [],
},
],
threads: [
@@ -313,6 +319,7 @@ describe("toPersistedState", () => {
cwd: "/tmp/project",
model: "gpt-5.3-codex",
expanded: true,
+ scripts: [],
},
],
threads: [thread],
diff --git a/apps/web/src/persistenceSchema.ts b/apps/web/src/persistenceSchema.ts
index 544816e73..9d6e3a90b 100644
--- a/apps/web/src/persistenceSchema.ts
+++ b/apps/web/src/persistenceSchema.ts
@@ -1,4 +1,5 @@
import { z } from "zod";
+import { projectScriptSchema } from "@t3tools/contracts";
import { DEFAULT_MODEL, resolveModelSlug } from "./model-logic";
import {
@@ -19,6 +20,7 @@ const persistedProjectSchema = z.object({
cwd: z.string().min(1),
model: z.string().min(1),
expanded: z.boolean(),
+ scripts: z.array(projectScriptSchema).default([]),
});
const persistedMessageSchema = z.object({
@@ -140,6 +142,7 @@ function hydrateProject(
return {
...project,
model: resolveModelSlug(maybeMigrateLegacyModel(project.model, isLegacyPayload)),
+ scripts: project.scripts,
};
}
diff --git a/apps/web/src/projectScripts.test.ts b/apps/web/src/projectScripts.test.ts
new file mode 100644
index 000000000..1ee4e5be2
--- /dev/null
+++ b/apps/web/src/projectScripts.test.ts
@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+
+import {
+ commandForProjectScript,
+ injectEnvIntoShellCommand,
+ nextProjectScriptId,
+ primaryProjectScript,
+ projectScriptIdFromCommand,
+ setupProjectScript,
+} from "./projectScripts";
+
+describe("projectScripts helpers", () => {
+ it("builds and parses script run commands", () => {
+ const command = commandForProjectScript("lint");
+ expect(command).toBe("script.lint.run");
+ expect(projectScriptIdFromCommand(command)).toBe("lint");
+ expect(projectScriptIdFromCommand("terminal.toggle")).toBeNull();
+ });
+
+ it("slugifies and dedupes project script ids", () => {
+ expect(nextProjectScriptId("Run Tests", [])).toBe("run-tests");
+ expect(nextProjectScriptId("Run Tests", ["run-tests"])).toBe("run-tests-2");
+ expect(nextProjectScriptId("!!!", [])).toBe("script");
+ });
+
+ it("injects environment variables for posix shells", () => {
+ const command = injectEnvIntoShellCommand("bun install", { T3CODE_PROJECT_ROOT: "/tmp/project" }, "MacIntel");
+ expect(command).toBe("env T3CODE_PROJECT_ROOT='/tmp/project' bun install");
+ });
+
+ it("injects environment variables for windows shells", () => {
+ const command = injectEnvIntoShellCommand("bun install", { T3CODE_PROJECT_ROOT: "C:\\\\repo path" }, "Win32");
+ expect(command).toBe('set "T3CODE_PROJECT_ROOT=C:\\\\repo path" && bun install');
+ });
+
+ it("resolves primary and setup scripts", () => {
+ const scripts = [
+ {
+ id: "setup",
+ name: "Setup",
+ command: "bun install",
+ icon: "configure" as const,
+ runOnWorktreeCreate: true,
+ },
+ {
+ id: "test",
+ name: "Test",
+ command: "bun test",
+ icon: "test" as const,
+ runOnWorktreeCreate: false,
+ },
+ ];
+
+ expect(primaryProjectScript(scripts)?.id).toBe("test");
+ expect(setupProjectScript(scripts)?.id).toBe("setup");
+ });
+});
diff --git a/apps/web/src/projectScripts.ts b/apps/web/src/projectScripts.ts
new file mode 100644
index 000000000..501f1b34a
--- /dev/null
+++ b/apps/web/src/projectScripts.ts
@@ -0,0 +1,92 @@
+import type { ProjectScript } from "@t3tools/contracts";
+
+import { isWindowsPlatform } from "./lib/utils";
+
+const SCRIPT_RUN_COMMAND_PATTERN = /^script\.([a-z0-9][a-z0-9-]*)\.run$/;
+const MAX_SCRIPT_ID_LENGTH = 64;
+const ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+function normalizeScriptId(value: string): string {
+ const cleaned = value
+ .trim()
+ .toLowerCase()
+ .replace(/[^a-z0-9]+/g, "-")
+ .replace(/^-+|-+$/g, "");
+ if (cleaned.length === 0) {
+ return "script";
+ }
+ if (cleaned.length <= MAX_SCRIPT_ID_LENGTH) {
+ return cleaned;
+ }
+ return cleaned.slice(0, MAX_SCRIPT_ID_LENGTH).replace(/-+$/g, "") || "script";
+}
+
+export function commandForProjectScript(scriptId: string): string {
+ return `script.${scriptId}.run`;
+}
+
+export function projectScriptIdFromCommand(command: string): string | null {
+ const match = SCRIPT_RUN_COMMAND_PATTERN.exec(command.trim());
+ return match?.[1] ?? null;
+}
+
+export function nextProjectScriptId(name: string, existingIds: Iterable<string>): string {
+ const taken = new Set(Array.from(existingIds));
+ const baseId = normalizeScriptId(name);
+ if (!taken.has(baseId)) return baseId;
+
+ let suffix = 2;
+ while (suffix < 10_000) {
+ const candidate = `${baseId}-${suffix}`;
+ const safeCandidate =
+ candidate.length <= MAX_SCRIPT_ID_LENGTH
+ ? candidate
+ : `${baseId.slice(0, Math.max(1, MAX_SCRIPT_ID_LENGTH - String(suffix).length - 1))}-${suffix}`;
+ if (!taken.has(safeCandidate)) {
+ return safeCandidate;
+ }
+ suffix += 1;
+ }
+
+ return `${baseId}-${Date.now()}`.slice(0, MAX_SCRIPT_ID_LENGTH);
+}
+
+function shellEscapePosix(value: string): string {
+ return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+function shellEscapeWindowsSetValue(value: string): string {
+ return value.replace(/"/g, '""');
+}
+
+export function injectEnvIntoShellCommand(
+ command: string,
+ env: Record<string, string>,
+ platform = typeof navigator === "undefined" ? "" : navigator.platform,
+): string {
+ const entries = Object.entries(env).filter(
+ ([key, value]) => ENV_KEY_PATTERN.test(key) && value.length > 0,
+ );
+ if (entries.length === 0) {
+ return command;
+ }
+
+ if (isWindowsPlatform(platform)) {
+ const prefixes = entries.map(
+ ([key, value]) => `set "${key}=${shellEscapeWindowsSetValue(value)}"`,
+ );
+ return `${prefixes.join(" && ")} && ${command}`;
+ }
+
+ const assignments = entries.map(([key, value]) => `${key}=${shellEscapePosix(value)}`).join(" ");
+ return `env ${assignments} ${command}`;
+}
+
+export function primaryProjectScript(scripts: ProjectScript[]): ProjectScript | null {
+ const regular = scripts.find((script) => !script.runOnWorktreeCreate);
+ return regular ?? scripts[0] ?? null;
+}
+
+export function setupProjectScript(scripts: ProjectScript[]): ProjectScript | null {
+ return scripts.find((script) => script.runOnWorktreeCreate) ?? null;
+}
diff --git a/apps/web/src/store.test.ts b/apps/web/src/store.test.ts
index b49de5d39..c6b9f4cb7 100644
--- a/apps/web/src/store.test.ts
+++ b/apps/web/src/store.test.ts
@@ -74,6 +74,7 @@ function makeState(thread: Thread): AppState {
cwd: "/tmp/project",
model: "gpt-5.3-codex",
expanded: true,
+ scripts: [],
},
],
threads: [thread],
@@ -507,6 +508,7 @@ describe("store reducer thread continuity", () => {
cwd: "/tmp/a",
model: "gpt-5.3-codex",
expanded: false,
+ scripts: [],
},
{
id: "project-old-b",
@@ -514,6 +516,7 @@ describe("store reducer thread continuity", () => {
cwd: "/tmp/b",
model: "gpt-5.3-codex",
expanded: true,
+ scripts: [],
},
],
threads: [
@@ -540,6 +543,7 @@ describe("store reducer thread continuity", () => {
cwd: "/tmp/a",
model: "gpt-5.3-codex",
expanded: true,
+ scripts: [],
},
],
});
@@ -554,6 +558,33 @@ describe("store reducer thread continuity", () => {
expect(next.activeThreadId).toBe("thread-a");
});
+ it("updates project scripts", () => {
+ const state = makeState(makeThread());
+ const next = reducer(state, {
+ type: "SET_PROJECT_SCRIPTS",
+ projectId: "project-1",
+ scripts: [
+ {
+ id: "test",
+ name: "Test",
+ command: "bun test",
+ icon: "test",
+ runOnWorktreeCreate: false,
+ },
+ ],
+ });
+
+ expect(next.projects[0]?.scripts).toEqual([
+ {
+ id: "test",
+ name: "Test",
+ command: "bun test",
+ icon: "test",
+ runOnWorktreeCreate: false,
+ },
+ ]);
+ });
+
it("deletes a project and all of its threads", () => {
const state: AppState = {
projects: [
@@ -563,6 +594,7 @@ describe("store reducer thread continuity", () => {
cwd: "/tmp/one",
model: "gpt-5.3-codex",
expanded: true,
+ scripts: [],
},
{
id: "project-2",
@@ -570,6 +602,7 @@ describe("store reducer thread continuity", () => {
cwd: "/tmp/two",
model: "gpt-5.3-codex",
expanded: true,
+ scripts: [],
},
],
threads: [
diff --git a/apps/web/src/store.ts b/apps/web/src/store.ts
index 6b38d7b00..8cc75e235 100644
--- a/apps/web/src/store.ts
+++ b/apps/web/src/store.ts
@@ -17,6 +17,7 @@ import {
DEFAULT_THREAD_TERMINAL_ID,
DEFAULT_RUNTIME_MODE,
MAX_THREAD_TERMINAL_COUNT,
+ type ProjectScript,
type Project,
type RuntimeMode,
type Thread,
@@ -27,6 +28,7 @@ import {
type Action =
| { type: "ADD_PROJECT"; project: Project }
+ | { type: "SET_PROJECT_SCRIPTS"; projectId: string; scripts: ProjectScript[] }
| { type: "SYNC_PROJECTS"; projects: Project[] }
| { type: "TOGGLE_PROJECT"; projectId: string }
| { type: "DELETE_PROJECT"; projectId: string }
@@ -163,6 +165,38 @@ function normalizeRunningTerminalIds(
.filter((id) => id.length > 0 && validTerminalIdSet.has(id));
}
+function normalizeProjectScripts(scripts: ProjectScript[]): ProjectScript[] {
+ const deduped: ProjectScript[] = [];
+ const seenIds = new Set<string>();
+ for (const script of scripts) {
+ const id = script.id.trim();
+ if (id.length === 0 || seenIds.has(id)) continue;
+ seenIds.add(id);
+ deduped.push({
+ ...script,
+ id,
+ name: script.name.trim(),
+ command: script.command.trim(),
+ });
+ }
+
+ let setupAssigned = false;
+ const normalized: ProjectScript[] = [];
+ for (const script of deduped) {
+ if (!script.runOnWorktreeCreate) {
+ normalized.push(script);
+ continue;
+ }
+ if (!setupAssigned) {
+ setupAssigned = true;
+ normalized.push(script);
+ continue;
+ }
+ normalized.push({ ...script, runOnWorktreeCreate: false });
+ }
+ return normalized;
+}
+
function normalizeTerminalGroupIds(terminalIds: string[]): string[] {
return [...new Set(terminalIds.map((id) => id.trim()).filter((id) => id.length > 0))];
}
@@ -426,20 +460,36 @@ export function reducer(state: AppState, action: Action): AppState {
{
...action.project,
model: resolveModelSlug(action.project.model),
+ scripts: normalizeProjectScripts(action.project.scripts),
},
],
};
+ case "SET_PROJECT_SCRIPTS":
+ return {
+ ...state,
+ projects: state.projects.map((project) =>
+ project.id === action.projectId
+ ? { ...project, scripts: normalizeProjectScripts(action.scripts) }
+ : project,
+ ),
+ };
+
case "SYNC_PROJECTS": {
const previousByCwd = new Map(
state.projects.map((project) => [project.cwd, project] as const),
);
const nextProjects = action.projects.map((project) => {
const previous = previousByCwd.get(project.cwd);
+ const scripts =
+ project.scripts.length > 0
+ ? normalizeProjectScripts(project.scripts)
+ : normalizeProjectScripts(previous?.scripts ?? []);
return {
...project,
model: resolveModelSlug(previous?.model ?? project.model),
expanded: previous?.expanded ?? project.expanded,
+ scripts,
};
});
const previousProjectById = new Map(
diff --git a/apps/web/src/types.ts b/apps/web/src/types.ts
index 3ff0149b9..5ffd70bfb 100644
--- a/apps/web/src/types.ts
+++ b/apps/web/src/types.ts
@@ -1,4 +1,8 @@
-import type { ProviderEvent, ProviderSession } from "@t3tools/contracts";
+import type {
+ ProjectScript as ContractProjectScript,
+ ProviderEvent,
+ ProviderSession,
+} from "@t3tools/contracts";
export type SessionPhase = "disconnected" | "connecting" | "ready" | "running";
export type RuntimeMode = "approval-required" | "full-access";
@@ -6,6 +10,7 @@ export const DEFAULT_RUNTIME_MODE: RuntimeMode = "full-access";
export const DEFAULT_THREAD_TERMINAL_HEIGHT = 280;
export const DEFAULT_THREAD_TERMINAL_ID = "default";
export const MAX_THREAD_TERMINAL_COUNT = 4;
+export type ProjectScript = ContractProjectScript;
export interface ThreadTerminalGroup {
id: string;
@@ -38,6 +43,7 @@ export interface Project {
cwd: string;
model: string;
expanded: boolean;
+ scripts: ProjectScript[];
}
export interface Thread {
diff --git a/apps/web/src/wsNativeApi.ts b/apps/web/src/wsNativeApi.ts
index 984ec3aa4..d5c232eee 100644
--- a/apps/web/src/wsNativeApi.ts
+++ b/apps/web/src/wsNativeApi.ts
@@ -99,6 +99,7 @@ export function createWsNativeApi(): NativeApi {
add: (input) => transport.request(WS_METHODS.projectsAdd, input),
remove: (input) => transport.request(WS_METHODS.projectsRemove, input),
searchEntries: (input) => transport.request(WS_METHODS.projectsSearchEntries, input),
+ updateScripts: (input) => transport.request(WS_METHODS.projectsUpdateScripts, input),
},
shell: {
openInEditor: (cwd, editor) =>
diff --git a/packages/contracts/src/ipc.ts b/packages/contracts/src/ipc.ts
index febfcd11f..42b377b87 100644
--- a/packages/contracts/src/ipc.ts
+++ b/packages/contracts/src/ipc.ts
@@ -32,6 +32,8 @@ import type {
ProjectSearchEntriesInput,
ProjectSearchEntriesResult,
ProjectRemoveInput,
+ ProjectUpdateScriptsInput,
+ ProjectUpdateScriptsResult,
} from "./project";
import type { ServerConfig } from "./server";
import type {
@@ -93,6 +95,7 @@ export interface NativeApi {
add: (input: ProjectAddInput) => Promise<ProjectAddResult>;
remove: (input: ProjectRemoveInput) => Promise<void>;
searchEntries: (input: ProjectSearchEntriesInput) => Promise<ProjectSearchEntriesResult>;
+ updateScripts: (input: ProjectUpdateScriptsInput) => Promise<ProjectUpdateScriptsResult>;
};
shell: {
openInEditor: (cwd: string, editor: EditorId) => Promise<void>;
diff --git a/packages/contracts/src/keybindings.test.ts b/packages/contracts/src/keybindings.test.ts
index 12726ea72..42a75a0e8 100644
--- a/packages/contracts/src/keybindings.test.ts
+++ b/packages/contracts/src/keybindings.test.ts
@@ -32,11 +32,19 @@ describe("keybindings contracts", () => {
assert.throws(() =>
keybindingRuleSchema.parse({
key: "mod+j",
- command: "invalid.command",
+ command: "script.Test.run",
}),
);
});
+ it("accepts dynamic script run commands", () => {
+ const parsed = keybindingRuleSchema.parse({
+ key: "mod+r",
+ command: "script.setup.run",
+ });
+ assert.strictEqual(parsed.command, "script.setup.run");
+ });
+
it("parses keybindings array payload", () => {
const parsed = keybindingsConfigSchema.parse([
{ key: "mod+j", command: "terminal.toggle" },
diff --git a/packages/contracts/src/keybindings.ts b/packages/contracts/src/keybindings.ts
index 96f89de12..0a2d558c0 100644
--- a/packages/contracts/src/keybindings.ts
+++ b/packages/contracts/src/keybindings.ts
@@ -1,6 +1,6 @@
import { z } from "zod";
-export const keybindingCommandSchema = z.enum([
+export const STATIC_KEYBINDING_COMMANDS = [
"terminal.toggle",
"terminal.split",
"terminal.new",
@@ -8,6 +8,16 @@ export const keybindingCommandSchema = z.enum([
"chat.new",
"chat.newLocal",
"editor.openFavorite",
+] as const;
+
+export const keybindingCommandSchema = z.union([
+ z.enum(STATIC_KEYBINDING_COMMANDS),
+ z
+ .string()
+ .trim()
+ .min(1)
+ .max(96)
+ .regex(/^script\.[a-z0-9][a-z0-9-]*\.run$/),
]);
const keybindingValueSchema = z.string().trim().min(1).max(64);
diff --git a/packages/contracts/src/project.test.ts b/packages/contracts/src/project.test.ts
index 2c315e6bd..693e4ff71 100644
--- a/packages/contracts/src/project.test.ts
+++ b/packages/contracts/src/project.test.ts
@@ -7,6 +7,8 @@ import {
projectSearchEntriesResultSchema,
projectListResultSchema,
projectRemoveInputSchema,
+ projectUpdateScriptsInputSchema,
+ projectUpdateScriptsResultSchema,
} from "./project";
describe("project contracts", () => {
@@ -16,6 +18,7 @@ describe("project contracts", () => {
id: "project-1",
cwd: "/tmp/project",
name: "project",
+ scripts: [],
createdAt: "2026-02-10T00:00:00.000Z",
updatedAt: "2026-02-10T00:00:00.000Z",
},
@@ -36,6 +39,7 @@ describe("project contracts", () => {
id: "project-1",
cwd: "/tmp/project",
name: "project",
+ scripts: [],
createdAt: "2026-02-10T00:00:00.000Z",
updatedAt: "2026-02-10T00:00:00.000Z",
},
@@ -82,4 +86,45 @@ describe("project contracts", () => {
expect(parsed.entries).toHaveLength(2);
expect(parsed.entries[0]?.kind).toBe("directory");
});
+
+ it("parses update scripts input", () => {
+ const parsed = projectUpdateScriptsInputSchema.parse({
+ id: "project-1",
+ scripts: [
+ {
+ id: "test",
+ name: "Test",
+ command: "bun test",
+ icon: "test",
+ runOnWorktreeCreate: false,
+ },
+ ],
+ });
+
+ expect(parsed.scripts).toHaveLength(1);
+ expect(parsed.scripts[0]?.id).toBe("test");
+ });
+
+ it("parses update scripts result", () => {
+ const parsed = projectUpdateScriptsResultSchema.parse({
+ project: {
+ id: "project-1",
+ cwd: "/tmp/project",
+ name: "project",
+ scripts: [
+ {
+ id: "setup",
+ name: "Setup",
+ command: "bun install",
+ icon: "configure",
+ runOnWorktreeCreate: true,
+ },
+ ],
+ createdAt: "2026-02-10T00:00:00.000Z",
+ updatedAt: "2026-02-10T00:00:00.000Z",
+ },
+ });
+
+ expect(parsed.project.scripts[0]?.id).toBe("setup");
+ });
});
diff --git a/packages/contracts/src/project.ts b/packages/contracts/src/project.ts
index 76b5e62c5..8ed18e5fd 100644
--- a/packages/contracts/src/project.ts
+++ b/packages/contracts/src/project.ts
@@ -1,9 +1,31 @@
import { z } from "zod";
+export const PROJECT_SCRIPT_ICON_VALUES = ["play", "test", "lint", "configure", "build"] as const;
+
+export const projectScriptIconSchema = z.enum(PROJECT_SCRIPT_ICON_VALUES);
+
+export const projectScriptSchema = z
+ .object({
+ id: z
+ .string()
+ .trim()
+ .min(1)
+ .max(64)
+ .regex(/^[a-z0-9][a-z0-9-]*$/),
+ name: z.string().trim().min(1).max(64),
+ command: z.string().trim().min(1).max(10_000),
+ icon: projectScriptIconSchema,
+ runOnWorktreeCreate: z.boolean().default(false),
+ })
+ .strict();
+
+export const projectScriptsSchema = z.array(projectScriptSchema).max(64);
+
export const projectRecordSchema = z.object({
id: z.string().min(1),
cwd: z.string().min(1),
name: z.string().min(1),
+ scripts: projectScriptsSchema.default([]),
createdAt: z.string().datetime(),
updatedAt: z.string().datetime(),
});
@@ -44,6 +66,17 @@ export const projectSearchEntriesResultSchema = z.object({
truncated: z.boolean(),
});
+export const projectUpdateScriptsInputSchema = z.object({
+ id: z.string().min(1),
+ scripts: projectScriptsSchema,
+});
+
+export const projectUpdateScriptsResultSchema = z.object({
+ project: projectRecordSchema,
+});
+
+export type ProjectScriptIcon = z.infer<typeof projectScriptIconSchema>;
+export type ProjectScript = z.infer<typeof projectScriptSchema>;
export type ProjectRecord = z.infer<typeof projectRecordSchema>;
export type ProjectListResult = z.infer<typeof projectListResultSchema>;
export type ProjectAddInput = z.input<typeof projectAddInputSchema>;
@@ -53,3 +86,5 @@ export type ProjectSearchEntriesInput = z.input<typeof projectSearchEntriesInput
export type ProjectEntryKind = z.infer<typeof projectEntryKindSchema>;
export type ProjectEntry = z.infer<typeof projectEntrySchema>;
export type ProjectSearchEntriesResult = z.infer<typeof projectSearchEntriesResultSchema>;
+export type ProjectUpdateScriptsInput = z.input<typeof projectUpdateScriptsInputSchema>;
+export type ProjectUpdateScriptsResult = z.infer<typeof projectUpdateScriptsResultSchema>;
diff --git a/packages/contracts/src/ws.ts b/packages/contracts/src/ws.ts
index 5f0ff8578..790a8f8ec 100644
--- a/packages/contracts/src/ws.ts
+++ b/packages/contracts/src/ws.ts
@@ -16,6 +16,7 @@ export const WS_METHODS = {
projectsAdd: "projects.add",
projectsRemove: "projects.remove",
projectsSearchEntries: "projects.searchEntries",
+ projectsUpdateScripts: "projects.updateScripts",
// Shell methods
shellOpenInEditor: "shell.openInEditor",