io.github.hermitsh-ai/shrimp

Create a new task in SHrimp. You can nest tasks at any depth by specifying a parentID. Use insertBefore to control ordering among siblings. Args: - title (string, required): Task title. - notes (string, optional): Additional notes or details. - parentID (string, optional): UUID of parent task. Omit for a root-level task. - dueDate (string, optional): ISO 8601 date (e.g. "2026-04-15"). - category (string, optional): One of home, work, errands, health, people, money, travel, projects. - insertBefore (string, optional): UUID of sibling task to insert before. Returns: { ok: true, opID: string, version: number } Tips: - Use shrimp_batch for creating multiple tasks at once (up to 50 ops). - UUIDs must be hex-only (0-9, a-f). Non-hex characters will be rejected.

Archive a task and all its children. Archived tasks are hidden from the main view but not deleted. Use shrimp_restore_task to bring them back. Args: - taskID (string, required): UUID of the task to archive. Returns: { ok: true, opID: string, version: number }

Execute multiple task operations in a single request. Much more efficient than individual calls when making several changes at once. Max 50 ops per batch. All ops are validated upfront before any are applied — if one has an invalid UUID, the entire batch is rejected. Each op must have a "type" field. Required fields depend on the type: - create: title (required), notes, parentID, dueDate, category, insertBefore - update: taskID (required), title, notes, dueDate, category - complete: taskID (required) - archive: taskID (required) - restore: taskID (required) - move: taskID (required), parentID, insertBefore - delete: taskID (required) Args: - ops (array): Array of operation objects (max 50). Returns: { ok: true, opIDs: string[], version: number } Tips: - Use this to build entire project plans in one call. - Create ops are processed in order, so you can create a parent then nest children under it in the same batch. - All UUIDs must be hex-only (0-9, a-f).

Toggle a task's completion status. If incomplete, marks it done. If already done, marks it incomplete. Args: - taskID (string, required): UUID of the task. Returns: { ok: true, opID: string, version: number }

Permanently delete a task and all its children. This cannot be undone. Prefer shrimp_archive_task if you're unsure — archived tasks can always be restored. Args: - taskID (string, required): UUID of the task to delete. Returns: { ok: true, opID: string, version: number }

Send feedback to the SHrimp developer on behalf of the user. Works in both local and paired mode. Rate limit: 5 feedback messages per hour.

Read the current prompt sections that control the in-app AI behavior. SHrimp's AI system prompt is modular — split into 6 editable sections that shape how the AI processes user requests. Sections: - intro: Identity and role definition - rules: Behavioral rules and constraints - thoroughness: How thorough/detailed the AI should be - categories: Life categories for task organization (home, work, errands, health, people, money, travel, projects) - schema: The JSON response schema the AI must follow - terminal: Additional instructions for the terminal/chat interface Requires the SHrimp iOS app (paired mode). Not available in local mode.

Read the current AI provider and model configuration. Requires the SHrimp iOS app (paired mode). Not available in local mode.

Read the user's task tree from SHrimp. Returns all tasks as a nested hierarchy. Each task has: id, title, notes, dueDate, category, isCompleted, isArchived, and children[]. Filters (all optional): - category: one of home, work, errands, health, people, money, travel, projects - completed: "true" or "false" — filter by completion status - archived: "true" or "false" — default is active only (false) - subtree: a task ID — returns only that task and its descendants - flat: "true" — returns a flat array with parentID instead of nesting The response includes a version number. Cache this to detect changes efficiently. Returns: { version: number, updatedAt: string, tasks: TaskItem[] } TaskItem shape: { id: string, title: string, notes?: string, dueDate?: string, category?: string, isCompleted: boolean, isArchived: boolean, children: TaskItem[] }

Read the SHrimp terminal inbox. Requires the SHrimp iOS app (paired mode). Not available in local mode. Item sources: email, shareExtension, siri, github, clipboard, composer Item statuses: pending, processing, processed, failed

Move a task to a different position in the tree. Can reparent under a new task or reorder among siblings. Args: - taskID (string, required): UUID of the task to move. - parentID (string, optional): UUID of new parent. Omit or null to move to root level. - insertBefore (string, optional): UUID of sibling to insert before. Omit to append at end. Returns: { ok: true, opID: string, version: number } Tips: - Moving a task also moves all its children. - You cannot move a task under itself (circular reference).

Connect this agent to a SHrimp account using a 6-digit pairing code. The user must open the SHrimp app on their phone → Settings → Agents → Pair New Agent to generate a code. The code expires after 5 minutes. After pairing, this agent switches from local mode to cloud mode — tasks sync to the phone in real-time. Any tasks created in local mode remain in ~/.shrimp/tasks.json but are not automatically migrated. Args: - code (string): The 6-digit numeric code from the SHrimp app. - agentName (string): Display name for this agent in the app (default: "Claude"). Returns on success: { paired: true, email: string, agentName: string, scopes: string[], configPath: string } Returns on failure: { paired: false, error: string } Common errors: - "Invalid code" → code is not exactly 6 digits - "Pairing failed" → code expired or wrong. User must generate a new one.

Read the processing pipeline log from the user's phone. Requires the SHrimp iOS app (paired mode). Not available in local mode. Pipeline stages: push, fetch, attach, batch, ai, inbox, share, file, retry

Restore an archived task back to the active list. Args: - taskID (string, required): UUID of the task to restore. Returns: { ok: true, opID: string, version: number }

Search tasks by keyword. Matches against titles and notes (case-insensitive substring match). Returns matching tasks with their full breadcrumb path so you know where they sit in the tree. Args: - q (string): Search query. - limit (number): Max results, 1–50 (default: 20). Returns: { results: SearchResult[], total: number } SearchResult shape: { id: string, title: string, notes?: string, isCompleted: boolean, path: string[], matchField: "title" | "notes" }

Check the current SHrimp connection mode. Takes no arguments. Returns one of: { mode: "paired", email: string, agentName: string, scopes: string[] } or { mode: "local", tasksPath: string, hint: string } In local mode, tasks are stored on this machine in ~/.shrimp/tasks.json. All task tools work — just without phone sync. Call shrimp_pair to upgrade to cloud mode.

Update one or more prompt sections that control the in-app AI behavior. Partial updates are supported — only include the sections you want to change. Sections: intro, rules, thoroughness, categories, schema, terminal Requires the SHrimp iOS app (paired mode). Not available in local mode.

Change the AI provider and/or model used by SHrimp. Requires the SHrimp iOS app (paired mode). Not available in local mode.

Update an existing task's properties. Only include the fields you want to change — omitted fields are left unchanged. Args: - taskID (string, required): UUID of the task to update. - title (string, optional): New title. - notes (string, optional): New notes (replaces existing notes entirely). - dueDate (string, optional): New due date (ISO 8601). - category (string, optional): New category (home, work, errands, health, people, money, travel, projects). Returns: { ok: true, opID: string, version: number }