Usage¶

Day-to-day operation of Pynchy — managing groups, scheduling tasks, and talking to your agents.

What You Can Do¶

• Channels — Message your assistant from WhatsApp, Slack, or Discord (plugin-provided — more can be added)
• Workspaces — Bind a chat to reusable profiles for prompts, tools, skills, repositories, and security policy
• Tool access and secrets — Grant provider access through tools and limit credentials to the process that needs them
• Admin channel — Your private channel (self-chat) for admin control; every other group is completely isolated
• Persistent memory — Agents search and update the mounted Obsidian vault across sessions and workspaces
• Scheduled tasks — Recurring jobs that run the selected agent core and can message you back
• Personalization repository — Keep settings, LiteLLM routes, skills, and automations in an independent private repository
• Channel-scoped secrets — Grant Discord channels exact Vaultwarden collections without exposing vault credentials to agents
• Agent cores — Choose which LLM powers your agents — Claude SDK, OpenAI SDK, Codex CLI, or plugin-provided cores
• Control plane — Inspect local or remote operational state through fail-closed listeners and bearer authentication
• Integrations — Connect your workspaces to Google, GitHub, mail, Slack, Linear, and other external services
• Web access — Search and fetch content through configured browser tools
• Container isolation — Agents sandboxed in Apple Container (macOS) or Docker (macOS/Linux)

Talking to Your Assistant¶

Talk to your assistant with the trigger word (default: @Pynchy):

@Pynchy send an overview of the sales pipeline every weekday morning at 9am (has access to my Obsidian vault folder)
@Pynchy review the git history for the past week each Friday and update the README if there's drift
@Pynchy every Monday at 8am, compile news on AI developments from Hacker News and TechCrunch and message me a briefing

From the Admin channel (your self-chat), you can manage groups and tasks:

@Pynchy list all scheduled tasks across groups
@Pynchy pause the Monday briefing task
@Pynchy join the Family Chat group

Messaging During Active Tasks¶

When the agent is busy (handling a user message or scheduled task), new messages behave differently depending on prefix:

btw ... adds context to in-flight work ("btw the file is in /tmp/data.csv"). The agent sees it as a follow-up message.

todo ... queues an item for later without derailing the current task ("todo also rename the config keys when you're done"). The agent views and manages the todo list via list_todos and complete_todo MCP tools.

A normal message (no prefix) interrupts the active task — the container stops and your new message starts fresh.

Pause and Resume Unfinished Work¶

Send exactly stop or pause to freeze the current agent turn immediately. Matching is case-insensitive and accepts the workspace trigger, such as @pynchy pause. Longer sentences such as please pause are ordinary agent messages, not control commands.

Pynchy acknowledges the command with ⏸️, hibernates the runtime, and retains the unfinished checkpoint and provider conversation. Your next ordinary message becomes guidance for that same turn; Pynchy reopens the same provider thread and continues the original work once. Pausing cannot undo side effects that completed before Pynchy received the command. System notices and automated provider events do not post into or resume the frozen thread. A direct message or provider-authenticated human comment resumes it.

If no turn is running or queued, stop and pause only hibernate the existing runtime. Autonomous work already queued behind a running turn is removed before that turn stops. A queued one-shot task remains frozen until a message in its chat or thread resumes it. A queued recurring occurrence stops without disabling or editing its definition, so a later schedule trigger can run normally. For an active scheduled turn, later triggers skip while its occurrence is frozen.

Use reset context to discard the current or frozen occurrence and its provider conversation. A recurring task stays active, and its next occurrence starts with fresh context. Existing finish commands such as done and end session keep their finish-and-hibernate behavior; they do not preserve unfinished work.

Customizing¶

Start conversationally, then put repeatable channel, workspace, and security policy in data/personalization/pynchy.toml when you need it to survive restarts and deployments. For example, you can ask Pynchy to help you:

• "Change the trigger word to @Bob"
• "Remember in the future to make responses shorter and more direct"
• "Add a custom greeting when I say good morning"
• "Store conversation summaries weekly"

Detailed Guides¶