| name | twicc-artifacts |
| description | List bookmarked artifacts (viewable files saved from a session's Artifacts tab), or bookmark/unbookmark one. Use when you or the user want to browse bookmarks, filter them by project/workspace/scope, or add, rename, re-scope, or remove one from the CLI. |
TwiCC Artifacts
List bookmarked artifacts, or bookmark / unbookmark one. A bookmark is a saved pointer to a viewable artifact file (HTML, image, PDF, Markdown, …) under a session's artifacts directory — a file TwiCC can display directly — with a name and a visibility scope (project / workspace / all). The only artifacts TwiCC tracks are bookmarked ones, so listing them = listing the bookmarks.
When to use
- You or the user want to list or browse bookmarked artifacts, optionally scoped to a project / workspace, or filtered to those bookmarked everywhere (
--scope all).
- You or the user want to bookmark an artifact a session produced, or rename / re-scope an existing bookmark.
- You or the user want to remove a bookmark.
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
List
$TWICC artifacts [OPTIONS]
Results are ordered by most recently updated. Read-only: works without the server running.
--project <PROJECT> — filter by project (path or id; drop the leading dash on ids). A normal project also returns its git worktrees' bookmarks; a worktree project returns only its own. Mutually exclusive with --workspace.--workspace ID — filter to bookmarks of projects in the given workspace, each member's git worktrees included. Mutually exclusive with --project.--scope <project|workspace|all> — filter by each bookmark's own visibility scope (independent of --project / --workspace). --scope all lists only the ones bookmarked everywhere.--limit N — max results (default: 20).--offset N — skip first N for pagination (default: 0).
Bookmark
$TWICC artifacts bookmark <SESSION_ID> <PATH> --name NAME [--scope SCOPE]
Creates the bookmark, or renames / re-scopes it if one already exists for that (session, path). Requires the live server.
SESSION_ID — the session that owns the artifact.PATH — artifact path relative to the session's artifacts directory (the relative_path the listing prints, e.g. demo/index.html), or an absolute path confined to that directory.--name NAME — bookmark name (required).--scope <project|workspace|all> — visibility scope. On create, defaults to project. Omit when updating to keep the current scope.--timeout N — seconds to wait for the server's status (default: 30).
Unbookmark
$TWICC artifacts unbookmark <SESSION_ID> <PATH>
Removes the bookmark for that (session, path). Symmetric with bookmark — the artifact file need not still exist. Requires the live server.
--timeout N — seconds to wait for the server's status (default: 30).
Errors
Local (exit 1)
Server (exit 3)
missing — a required field (session_id, path, or name) was empty.invalid_scopesession_not_foundpath_escapes — the path resolves outside the session's artifacts directory.file_not_found — bookmark only; the artifact file does not exist.not_bookmarked — unbookmark only; no bookmark exists for that (session, path).
Output format
Listing
[
{
"id": 3,
"name": "Layout playground",
"scope": "all",
"session_id": "54b42b89-290a-4324-bf86-f636a048d23d",
"project_id": "-home-twidi-dev-myproject",
"relative_path": "layout-playground/index.html",
"root": "/home/twidi/.twicc/artifacts/54b42b89-290a-4324-bf86-f636a048d23d",
"file_ext": "html",
"created_at": "2026-06-16T22:22:04.856926+00:00",
"updated_at": "2026-06-16T22:22:04.856938+00:00"
}
]
scope is the bookmark's own visibility scope; root is the session's artifacts directory; relative_path is the key you pass to bookmark / unbookmark.
Bookmark / unbookmark
{"status": "updated", "bookmark_id": 3, "session_id": "abc…", "project_id": "-home-…", "request_uuid": "…"}
{"status": "deleted", "bookmark_id": 3, "session_id": "abc…", "project_id": "-home-…", "request_uuid": "…"}
On rejection: {"status": "rejected", "errors": [{"field": "…", "code": "…", "message": "…"}], "request_uuid": "…"}.
Exit codes
0 — Success1 — Local validation error2 — TwiCC server not running3 — Server rejected4 — Server error5 — Timeout64 — Bad CLI usage
Examples
$TWICC artifacts
$TWICC artifacts --project .
$TWICC artifacts --workspace backend
$TWICC artifacts --scope all
$TWICC artifacts --limit 50 --offset 20
$TWICC artifacts bookmark 54b42b89-290a-4324-bf86-f636a048d23d demo/index.html --name "Demo"
$TWICC artifacts bookmark 54b42b89-290a-4324-bf86-f636a048d23d report.md --name "Report" --scope all
$TWICC artifacts unbookmark 54b42b89-290a-4324-bf86-f636a048d23d demo/index.html
Related commands
$TWICC sessions — list sessions (find the SESSION_ID that owns an artifact). Skill: twicc-sessions.$TWICC session <session_id> — full metadata for one session. Skill: twicc-session.
How to present results
- Show each bookmark's name, scope, and
relative_path; group by session or project when listing many.
- If there are more results, offer to paginate with
--offset.
- You are in TwiCC — link to a bookmarked artifact:
[link text](/project/{project_id}/artifacts/{id}).
