Workspaces¶

This page explains how managed workspace definitions work under the hood. Understanding this helps you build plugins that ship preconfigured agents — periodic code reviewers, monitoring bots, or any agent that should "just work" after installation.

Workspaces are pluggable. Plugins can provide workspace specs that create groups and scheduled tasks automatically.

What Workspace Specs Do¶

A workspace spec is a declaration: "this agent should exist with these settings." It includes a folder name and configuration (schedule, prompt, access level).

At startup, Pynchy reconciles workspace specs against the database — creating groups and scheduling tasks as needed. This means a plugin can ship a fully configured periodic agent that activates the moment you install the package. Agent instructions are delivered via directives rather than seeded files.

Config Merging¶

Workspace specs come from two sources: plugins and config.toml. When both define the same workspace folder, user config always wins.

Plugin provides:   folder + config
User overrides:    [workspaces.same-folder] in config.toml
Result:            User config takes priority

This lets plugins provide sensible defaults while users retain full control.

Reconciliation¶

Scheduled tasks and workspace state live in the database, but the source of truth is config.toml (and plugin specs). On every startup, reconcile_workspaces() syncs the declared configuration into the database:

Merges plugin specs with config.toml workspaces
Creates chat groups for workspaces missing database entries
Creates or updates scheduled tasks for periodic agents (those with schedule + prompt)
Creates channel aliases across messaging platforms

Automatic config-to-database sync¶

For periodic agents, the reconciler compares the database row against config.toml on every startup. If any of the following fields differ, it patches the database to match:

schedule — also recalculates next_run when the cron expression changes
prompt — updates the prompt sent to the agent on each scheduled run
repo_access — updates the repo worktree mount

This means editing config.toml and restarting the service is all that's needed to change a schedule, prompt, or repo access. No manual database edits required.

Workspace Config Fields¶

Field	Type	Description
`is_admin`	`bool`	Whether this is an admin workspace
`profile`	`str`	Name of a sandbox profile from `[sandbox_profiles.*]`
`directives`	`list[str]`	Directive names (convention-resolved to `directives/<name>.md`)
`repo_access`	`str`	GitHub slug (`owner/repo`) from `[repos.*]`; mounts a project worktree
`schedule`	`str`	Cron expression for periodic execution
`prompt`	`str`	Prompt sent to the agent on each scheduled run
`context_mode`	`str`	`"group"` (shared session) or `"isolated"` (fresh each time)
`trigger`	`str`	`"mention"` (default) or `"always"` — whether @mention is required
`name`	`str`	Display name (defaults to folder titlecased)
`skills`	`list[str]`	Skill tier names and/or skill names to include; `"*"` = include all
`mcp_servers`	`list[str]`	MCP server names and group names to attach to the sandbox
`security`	`dict`	MCP tool access control and rate limiting

Want to customize this? Write your own workspace plugin — see the Plugin Authoring Guide. Have an idea but don't want to build it? Open a feature request.