twicc-create-workspace

name	twicc-create-workspace
description	Create a new TwiCC workspace — a group of projects, optionally with a color, auto-add directory patterns, an initial project list, and a browser URL. Use when you or the user want to create a workspace.
argument-hint	<name> [--color X] [--add-project project]... [--add-pattern pattern]... [--browser-url X]

TwiCC Create Workspace

Create a new workspace (a named group of projects). The id is generated by slugifying the name; -2/-3 suffixes are appended on collision.

When to use

• You or the user want to create a new workspace.
• A script needs to scaffold workspaces before populating them.

How to invoke

Prefer the mcp__twicc__* tools when you have them. Inside a TwiCC session your tool list may include mcp__twicc__* tools — one per command below (the command with / and - turned into _, e.g. mcp__twicc__create_session, mcp__twicc__update_session_settings). When present, use them instead of the $TWICC CLI: same arguments, same JSON result, no shell, and your session identity travels with the call so self/parent resolve on their own. Fall back to the $TWICC CLI below when those tools aren't available (outside a session, or when scripting from a terminal).

TwiCC's executable varies by launch mode (uvx, dev, installed tool). ALWAYS USE THIS TO RESOLVE $TWICC AT THE START OF EACH BASH INVOCATION:

TWICC=${TWICC_BIN:-$(command -v twicc 2>/dev/null)}
[ -n "$TWICC" ] || { echo "TwiCC executable not found in this context" >&2; exit 1; }

Then run $TWICC <args> — never quote $TWICC (use $TWICC args, never "$TWICC" args): it may expand to multiple words, which quoting would break.

Usage

$TWICC create-workspace '<NAME>' [OPTIONS]

Arguments

• NAME — display name. Trimmed; non-empty; ≤ 20 characters; unique (case-insensitive) across all workspaces including archived ones.

Options

• --color VALUE — CSS hex color (#rgb, #rrggbb, or #rrggbbaa).
• --add-project PROJECT (repeatable) — Add a project. Either a directory path or a project ID (drop the leading dash on ids — the CLI re-adds it). The project must already exist in TwiCC. Duplicates are silently deduplicated.
• --add-pattern PATTERN (repeatable) — Add an auto-add pattern (* wildcard). Newly detected projects whose directory matches are added to the workspace automatically.
• --browser-url URL — Initial saved URL for the session Browser tab of this workspace's projects (http(s) only; a project's own saved URLs take precedence). Becomes the default (Home target); add more with update-workspace --add-browser-url.
• --timeout SECONDS — Seconds to wait for the server's response (default 30).

Errors

Local (exit 1)

• invalid_name — name empty after trim, or exceeds 20 characters.
• duplicate_name
• invalid_color
• invalid_pattern — an --add-pattern value is empty after trim.
• project_not_found — an --add-project value doesn't resolve to an existing project.
• invalid_value — non-http(s) --browser-url.

Server (exit 3)

Same codes, re-checked under the workspaces lock.

Output format

{"status":"created","workspace_id":"backend-2","request_uuid":"..."}
{"status":"validation_error","errors":[{"field":"NAME","code":"duplicate_name","message":"..."}]}
{"status":"rejected","errors":[{"field":"...","code":"...","message":"..."}],"request_uuid":"..."}
{"status":"failed","error":"...","request_uuid":"..."}
{"status":"timeout","received_seen":true,"message":"...","request_uuid":"..."}

Exit codes

• 0 — Workspace created
• 1 — Local validation error
• 2 — TwiCC server not running
• 3 — Server rejected
• 4 — Server error
• 5 — Timeout
• 64 — Bad CLI usage

Examples

$TWICC create-workspace 'Backend'
$TWICC create-workspace 'Frontend' --color '#4a90d9' \
    --add-project /home/twidi/dev/app-front \
    --add-project /home/twidi/dev/design-system \
    --add-project 'home-twidi-dev-shared'   # by id, dash dropped
$TWICC create-workspace 'Sparkup' --add-pattern '/home/twidi/dev/sparkup/*'
$TWICC create-workspace 'Scratch'
# → {"status":"created","workspace_id":"scratch","request_uuid":"..."}

Related commands

• $TWICC update-workspace <ID> — rename, recolor, add/remove projects or patterns, archive/unarchive. Skill: twicc-update-workspace.
• $TWICC delete-workspace <ID> — delete a workspace. Skill: twicc-delete-workspace.
• $TWICC workspaces / $TWICC workspace <ID> — list or inspect. Skill: twicc-workspaces / twicc-workspace.
• $TWICC projects — list projects to find ids (--add-project accepts paths directly). Skill: twicc-projects.

How to present results

1. On success, give the workspace name + id and a clickable link: [link text](/projects?workspace={workspace_id}).
2. On validation error, summarize the failing fields with their codes.