Skip to main content
A Rundock workspace is a folder. This page is the canonical reference for what is inside that folder, where each thing lives, and what syncs across a team versus what stays on the individual machine. For the concept, see Workspaces. For the team setup walkthrough, see Set up a team workspace.

​
Top-level layout

The workspace folder is the unit of sharing. Everything in it is meant to be visible to the team. The ~/.rundock/ directory is per-user and never shared.

​
What each path is for

​
.claude/agents/

One markdown file per agent. The filename without the .md extension is the agent’s slug.
Each file has YAML frontmatter at the top (declaring identity, position, icon, colour) and a markdown body underneath (the agent’s system prompt). For the full reference, see Agent file format.

​
.claude/skills/

One folder per skill. The folder name is the skill’s slug. Inside each folder, a single SKILL.md holds the skill definition.
The folder shape exists so a skill can keep references, templates, sub-files, and assets next to its definition. For the full reference, see Skill file format.

​
.claude/settings.local.json

Per-user MCP server permissions and tool overrides for the workspace. Although it sits inside .claude/, this file should not sync across team members: it is per-user state. Add it to your sync tool’s exclusion list (or to .gitignore if you sync via git).

​
.mcp.json

Workspace-level MCP server configuration. Lists the MCP servers the workspace uses and the connection details. This file syncs across the team (the configuration is shared) but the credentials each MCP server needs come from each user’s ~/.rundock/secrets/. This file is optional. If your workspace uses no MCP servers, omit it.

​
CLAUDE.md

Workspace-wide instructions. Rules and context that apply to every agent in the team. House style, file path conventions, naming rules, anything you want every agent to follow. CLAUDE.md is loaded as part of every agent’s context at spawn time. Keep it focused: long, dense rules in CLAUDE.md slow every conversation down. House style and shared file path conventions belong here. Domain-specific procedures belong in skills.

​
Knowledge files

Anything else you add to the workspace folder. Brand documents, ICP definitions, voice profiles, pricing pages, reference material your agents need to read. There is no required structure: organise these however suits your work. A common shape:
Agents read these files when their instructions tell them to. Rundock does not auto-load them at spawn time: you control which files come into context, by writing it into the agent’s body or skill instructions.

​
~/.rundock/

The per-user directory, outside the workspace folder. Holds:
  • state.json: the current workspace path, the workspace mode (Knowledge or Code), and other per-user UI state.
  • secrets/: API keys, OAuth tokens, and other credentials. Encrypted at rest.
  • conversations/: conversation history and session data.
  • prefs.json: per-user preferences (model choice, theme, permission card behaviour).
This directory is created by Rundock on first launch. You do not move it, share it, or sync it.
Do not place ~/.rundock/ inside a synced folder (Dropbox, OneDrive, Google Drive, or a git repo). Doing so will leak secrets to anyone with access to that sync location. Rundock keeps ~/.rundock/ outside the workspace folder by design.

​
What syncs and what does not

The split as a table. The principle: agents and shared knowledge belong to the team. Credentials and sessions belong to the individual.

​
Hidden folders

The .claude/ directory is hidden by default in Finder (Mac) and File Explorer (Windows). This is standard behaviour for any folder name starting with a dot. Cloud sync services handle hidden folders correctly. They sync the same way as visible folders. If you want to inspect the contents directly:
  • Mac: in Finder, press Cmd + Shift + . to toggle hidden file visibility.
  • Windows: in File Explorer, View > Show > Hidden items.

​
Workspace mode

Workspace mode is a workspace-level setting that changes agent behaviour at the platform level. Set per workspace, not per agent. Mode is set in the workspace settings drawer, or by editing ~/.rundock/state.json directly:
When a workspace is first opened, Rundock auto-detects the likely mode by looking for package.json, pyproject.toml, Cargo.toml, and similar markers. The mode affects every agent in the workspace, not just one. There is no per-agent override.

​
Where to next

Workspaces concept

What a workspace is and the sync/no-sync split explained.

Set up a team workspace

Share a workspace across a team using Dropbox, OneDrive, Google Drive, or git.

Agent file format

Every field in an agent file, with a complete worked example.

Skill file format

Every field in a skill file, with a complete worked example.