Pause

Pause

Stop mid-session and leave yourself a one-click way back IN to this exact session. The whole point is a single copy-paste command, stored in a task, that resumes the current Claude Code session with full context.

This is deliberately tiny. Detect the session, build the resume command, put it in a task. The only extra moving part is a one-time setup that records which task manager to use.

Step 1: Detect the current session

Run the detection script by its ABSOLUTE path. Do NOT cd into the skill directory first; the script is pwd-independent and cd-ing would drift the working directory.

"${CLAUDE_PLUGIN_ROOT}/skills/pause/detect-session.sh"

It prints KEY=value lines. Parse them:

• SESSION_ID . the id of the session we are in (from $CLAUDE_CODE_SESSION_ID; falls back to the newest transcript for the project).
• PROJECT_DIR . where the session was launched, read from the transcript's cwd. The resume command must cd here first, and config resolution (Step 2) uses it.
• PROJECT_DIR_SOURCE . transcript (the dir was read from the real transcript, safe) or fallback-pwd (the transcript was missing or had no cwd, so the dir is a GUESS from the caller's pwd). Hard gate: if this is fallback-pwd, do not silently create the task. The resume command may cd to the wrong directory, which makes the resume fail later. Tell the user the project dir could not be confirmed and ask before proceeding. An exact id (DETECTION=env) with a fallback-pwd dir is still unsafe, so gate on this, not on DETECTION.
• TRANSCRIPT / TRANSCRIPT_BYTES . the session transcript and its size. If TRANSCRIPT is ` or TRANSCRIPT_BYTES is tiny, treat it like fallback-pwd`: confirm with the user first.
• MATCH_COUNT . how many transcripts share this id across project dirs. If it is greater than 1 the id is ambiguous (the newest was picked); mention it and confirm the project dir looks right.
• DETECTION . env(CLAUDE_CODE_SESSION_ID) (exact) or fallback(newest-jsonl) (heuristic). On the fallback path, double-check the id looks right before proceeding.
• RESUME_CMD . the finished command to store, already in the form cd "" && claude --resume "" (paths quoted so a dir with spaces survives).

Use RESUME_CMD verbatim. Do not reconstruct it by hand.

Step 2: Resolve the task-manager config (and run first-run setup if needed)

Resolve which backend to use, passing the project dir from Step 1:

"${CLAUDE_PLUGIN_ROOT}/skills/pause/resolve-config.sh" ""

It prints KEY=value lines. Precedence is: per-repo /.pause.json (the REPO_CONFIG path) wins over the global ~/.config/pause/config.json (the GLOBAL_CONFIG path). The script exits non-zero when a config is present but broken.

• If NEEDS_SETUP=0 and a BACKEND is printed: use it and proceed to Step 3.
• If the script exited non-zero with a CONFIG_ERROR=... line: the config file at CONFIG_PATH exists but is unparseable or missing its backend key. Do NOT guess a backend. Tell the user what is wrong (quote CONFIG_ERROR) and offer to either fix the file or re-run the one-time setup (which overwrites it). Only overwrite on their say-so.
• If NEEDS_SETUP=1: no task manager is configured yet. The skill ships with NO built-in support; configuring one is the one-time setup. Run it now:

1. Ask, open-ended, what task manager the user uses. This is not a fixed menu: take whatever they name (Sunsama, Todoist, TickTick, Things, Notion, Apple Reminders, anything). Because it is free-form, ask in prose (the ## ❓ QUESTION ❓ format), not a fixed-option AskUserQuestion.
2. Configure an integration for that manager. Find the best PROGRAMMATIC path and use the first that is available:

a. A registered MCP server for it: search your tools for mcp____* (a create_task-style tool). Preferred: native and structured. b. An official API (needs a token: look in 1Password via the op CLI first, else ask the user). c. A CLI for it. d. macOS app automation (osascript AppleScript) for local apps like Things or Apple Reminders. e. Last resort: a local markdown file (append a checklist item).

1. Do any required auth NOW. For an MCP that is registered but unauthenticated (only its authenticate / complete_authentication tools are exposed), call its authenticate tool and hand the user the returned URL: account-bound OAuth is the one step that needs them, and the create tool appears once authorized. For an API, fetch the token from 1Password or ask.
2. VERIFY it can actually create a task. The point of setup is to prove the integration works, not just record a name. Use the real resume task (Steps 3 to 4) as the verification, or a throwaway you then delete.
3. Write the config to GLOBAL_CONFIG (create the dir if missing) recording what you configured: at minimum {"task_manager":"","backend":""} plus any params the create step needs (schedule, list/board id, file path). Tell the user where it saved and that a /.pause.json overrides it per repo.
4. Re-run resolve-config.sh "" and proceed.

If you cannot configure ANY working integration for the named manager (no MCP, no API access, not a local app), say so plainly and offer the markdown-file fallback so /pause still works, or stop so the user can set up access first. Do NOT silently substitute a different manager.

Do this setup only when NEEDS_SETUP=1. On every later run the global (or per-repo) config answers it silently.

Step 3: Compose the task

• Headline (title): a short, human description of what THIS session is doing, derived from the actual work in progress. Example: Building /pause skill in mutwo-skills. Under ~60 chars. No Resume: prefix: the headline describes the work; the command lives in the notes.
• Notes: two parts, in order:

1. A 1 to 2 sentence plain-language summary of what this session is building or doing. Example: "Building an ability to pause a Claude session which logs it in a task manager and provides a command to unpause and return to Claude where we left off."
2. A Copy and run: line, then the resume command in a fenced code block (Sunsama and most managers render a code block as a copyable monospaced box). Use RESUME_CMD, with the HTML-notes && to ; adjustment from Step 4 when the backend stores HTML. The code fence is safe: the & double-encoding is caused by the &&, not the fence, so a code block plus the ; form renders clean.

No em-dash characters (U+2014) anywhere in the title or notes. Use periods, commas, colons, semicolons, parentheses, or hyphens.

Step 3.5: Preview and get approval BEFORE sending

Creating a task is an outward-facing write, so always show the user a preview FIRST and get explicit approval before pushing anything to their task manager.

The preview shows three things:

1. the headline,
2. the notes (the summary plus the Copy and run: command), and
3. the task manager's notable optional fields, each with the value that will be used, so the user can change them before sending.

Those optional fields are BACKEND-SPECIFIC: every task manager has extras you would not expect, and the user should control them rather than have them silently auto-assigned. Discover them from the backend's create capability (for an MCP, read its create tool's input schema) and surface the ones a user would care about. For Sunsama, surface at least:

• Channel (Sunsama's channel / tag). Left unset, Sunsama auto-predicts a channel, which is often wrong, so always show the value that will be used and let the user choose. List the user's existing channels when you can (so they pick a real one rather than typing blind).
• Start date (the day the task is scheduled to; default today, or tomorrow per sunsama.schedule).

Show the preview via AskUserQuestion (header "Send to "), putting headline + notes + the optional fields (with their values) in the recommended option's preview field as one unmissable block. Options: Send it (recommended; carries the preview) and Edit first (capture what to change, including any optional field, then re-compose and re-preview). Only on an explicit "Send it" do you proceed to Step 4. On "Edit first", do not send: revise and preview again.

When the user sets a field that has a sensible per-user default (for example a preferred Sunsama channel), persist it into the config so later runs prefill it; they can still change it per run.

Step 4: Create the task in the configured integration

Create the task through whatever integration Step 2 configured for this backend: the title from Step 3, and the notes holding the resume command. The resume command landing in the notes is the one hard requirement.

HTML-notes hazard (verify the resume command survives). Some task managers store notes as HTML and mangle shell metacharacters. Sunsama's MCP double-encodes &: a note containing && is stored as &&, which pastes as the broken &&. Quotes (") survive (stored as ", render as "). So for any HTML-notes backend, store the command with a ; separator instead of && (cd ""; claude --resume "" runs the same two steps), and confirm by re-fetching the task that the stored command is intact. Plain-text backends (a markdown file) keep && as-is.

backend: sunsama

If the Sunsama tools are not yet available (only mcp__Sunsama__authenticate / mcp__Sunsama__complete_authentication are exposed), authenticate first per Step 2.3. Then call mcp__Sunsama__create_task with:

• title (from Step 3),
• notes: the summary + Copy and run: + the resume command in a fenced code block, with && rewritten to ; (see the HTML-notes hazard above),
• day: the start date the user confirmed in the preview (default today / tomorrow per sunsama.schedule), in YYYY-MM-DD,
• channel: the channel the user chose in the preview. Pass it explicitly; do NOT omit it and let Sunsama auto-predict (that is what mis-tagged the task as "networking" during the build). If the user stored a default channel in config (sunsama.channel), prefill it.

After creating, re-fetch with mcp__Sunsama__get_task_by_id and confirm the stored command is not mangled.

backend: markdown (fallback)

Append a checklist item to the file at markdown.path (expand a leading ~). Create the file if missing. Plain text, so use RESUME_CMD verbatim (already quoted, && intact). Format:

- [ ] Resume:  . ``

Step 5: Confirm back to the user

Print, in chat:

• the RESUME_CMD (so the user sees exactly what was stored), and
• the created task's title and, if the backend returned one, its link / id.

One tight confirmation. Example:

> Paused. Sent to Sunsama: "Building /pause skill in mutwo-skills" (scheduled today). > Resume with: cd "/Users/mujtaba/dev"; claude --resume "37192553-aa0f-4d3d-b3d0-7a1ebae2674c"

Config

Two real config locations, resolved by resolve-config.sh (per-repo wins over global):

• Global user config (~/.config/pause/config.json): written by the first-run setup, works across every Claude session for this user.
• Per-repo override (/.pause.json): when present, takes precedence while working in that repo.

The config is WRITTEN by the first-run setup (Step 2) to record the integration it configured and verified. It is never hand-authored as a default; the committed config.example.json is only a schema reference. Shape:

{
  "task_manager": "Sunsama",
  "backend": "sunsama",
  "sunsama": { "schedule": "today" }
}

• task_manager: the human name the user gave (for display).
• backend: the integration id resolve-config.sh reads and Step 4 branches on.
• Per-backend params follow under their own key (e.g. sunsama.schedule = today or tomorrow; a markdown fallback would carry markdown.path).

Supporting a new task manager is not a code change to a fixed list: Step 2's setup discovers and configures whatever the user names (MCP, API, CLI, app automation). Add a ### backend: branch in Step 4 only when a manager needs create-call specifics beyond the generic path. Detection (Step 1) and confirmation (Step 5) are backend-agnostic.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mujtaba3B
• Source: mujtaba3B/mutwo-skills
• License: MIT

Install and usage instructions live in the source repository linked above.