Important: The workspace system has been moved to the data-machine-code extension plugin as of v0.45.0. This documentation is preserved for reference. Install the extension to use workspace functionality.

Important: The workspace system has been moved to the data-machine-code extension plugin as of v0.45.0. This documentation is preserved for reference. Install the extension to use workspace functionality.

Overview

Important: The workspace system has been moved to the data-machine-code extension plugin as of v0.45.0. This documentation is preserved for reference. Install the extension to use workspace functionality.

1. Workspace service — core repository management with path containment and Git operations
2. WorkspaceReader / WorkspaceWriter — file I/O within workspace repos
3. WorkspaceAbilities — WordPress 6.9 Abilities API (16 abilities)
4. WorkspaceTools / WorkspaceScopedTools — AI chat tools for global and handler-scoped access
5. Fetch and Publish handlers — pipeline integration for reading from and writing to workspace repos
6. CLI — full wp datamachine-code workspace command set (in extension)

Workspace Directory

The workspace system provides a managed external directory where Data Machine agents can clone, read, write, and perform Git operations on repositories. Unlike agent memory files (which live inside wp-content/uploads/), workspace repos live outside the web root for security and to support build tooling that shouldn’t be publicly accessible.

The workspace system consists of:

/var/lib/datamachine/workspace/
  data-machine/          # git clone of Extra-Chill/data-machine
  homeboy/               # git clone of Extra-Chill/homeboy
  chubes-docs/           # git clone of chubes4/chubes-docs

Workspace Service

Default location: /var/lib/datamachine/workspace/

The workspace directory is outside the WordPress web root. It’s created on first use and protected with an index.html file. Each cloned repository gets its own subdirectory:

Constants

Repository Management

Git Operations

Source: inc/Core/FilesRepository/Workspace.php Since: v0.30.0

Security

The Workspace class is the core service handling repository management, Git operations, and path security.

All Git operations validate path containment and execute via run_git(), a private method that shells out to the git binary within the repo directory.

The Workspace class enforces several security measures:

Path containment: validate_containment(string $full_path) ensures all resolved paths are within the workspace directory. Any path that escapes via traversal (../) or symlink resolution is rejected.

Traversal detection: has_traversal(string $path) checks for .. components and null bytes in paths.

Sensitive path protection: is_sensitive_path(string $path) blocks access to files like .git/config, .env, credentials files, and SSH keys.

• allowed_paths — restrict file access to specific subdirectories
• fixed_branch — lock a repo to a specific branch (prevent checkout of other branches)

WorkspaceReader

Git mutation guards: ensure_git_mutation_allowed(string $name) checks per-repo policies before allowing write operations (add, commit, push). Repos can be configured as read-only.

Per-repo policies: get_workspace_git_policies() returns configurable settings:

Methods

Source: inc/Core/FilesRepository/WorkspaceReader.php

Read-only file operations within workspace repos.

• Offset/limit — read a portion of the file (useful for large files)
• Binary detection — returns a warning message instead of binary content
• Size enforcement — capped at Workspace::MAX_READ_SIZE (1 MB)

read_file(string $name, string $path, ?int $offset, ?int $limit)

Reads a file from a workspace repo. Supports:

Returns {success, content, file, size, offset?, limit?, truncated?}.

list_directory(string $name, string $path)

WorkspaceWriter

Lists directory contents, sorted with directories first (suffixed with /), then files. Filters out . and .. entries.

Returns {success, repo, path, entries[]}.

Methods

Source: inc/Core/FilesRepository/WorkspaceWriter.php

Write and edit operations within workspace repos.

write_file(string $name, string $path, string $content)

Creates or overwrites a file. Creates intermediate directories as needed. Performs post-write containment verification to ensure the written file is still within the workspace.

Returns {success, file, size, message}.

• The file doesn’t exist
• old_string is not found in the file

edit_file(string $name, string $path, string $old_string, string $new_string)

Abilities

Find-and-replace within a file. Reads the file, counts occurrences of old_string, replaces all occurrences, and writes back. Returns an error if:

Returns {success, file, occurrences, message}.

Read-Only Abilities

Mutating Abilities

Source: inc/Abilities/WorkspaceAbilities.php

AI Tools

Global Tools (WorkspaceTools)

Note: WorkspaceTools have been moved to the data-machine-code extension plugin.

Sixteen abilities registered under the datamachine category, split into read-only and mutating operations:

Note: WorkspaceTools have been moved to the data-machine-code extension plugin.

Read-only abilities have show_in_rest: true. Mutating abilities have show_in_rest: false for safety.

Scoped Tools (WorkspaceScopedTools)

Note: WorkspaceTools have been moved to the data-machine-code extension plugin.

Source: inc/Engine/AI/Tools/Global/WorkspaceTools.php (in extension) Tool ID: Various (workspace_path, workspace_list, workspace_show, workspace_ls, workspace_read) Contexts: chat, pipeline, standalone

Five read-only tools available globally to AI agents:

These tools are available whenever the workspace is configured (is_configured() checks that the workspace directory exists and is readable).

Pipeline Integration

Fetch Handler

Source: inc/Core/Steps/Workspace/Tools/WorkspaceScopedTools.php

Handler-scoped tools registered by the Workspace fetch and publish handlers. These tools enforce per-handler path allowlists — operations are restricted to the paths configured in the handler settings.

8 operations dispatched via handle_tool_call():

Publish Handler

All operations validate paths against the handler’s configured allowlist before delegating to the Abilities API.

Source: inc/Core/Steps/Fetch/Handlers/Workspace/Workspace.php

Reads data from workspace repositories as a pipeline fetch source. Configured with:

The fetch handler produces structured JSON data packets and registers scoped workspace_fetch_ls and workspace_fetch_read tools for the AI step.

CLI

Source: inc/Core/Steps/Publish/Handlers/Workspace/Workspace.php

Repository Management

# Show workspace path
wp datamachine workspace path

# List all repositories
wp datamachine workspace list [--format=table|json]

# Clone a repository
wp datamachine workspace clone <url> [<name>]

# Remove a repository
wp datamachine workspace remove <name>

# Show repository details
wp datamachine workspace show <name>

File Operations

# Read a file
wp datamachine workspace read <name> <path> [--offset=<n>] [--limit=<n>]

# List directory contents
wp datamachine workspace ls <name> [<path>]

# Write a file (supports @/path/to/local/file syntax)
wp datamachine workspace write <name> <path> --content=<content>

# Edit a file (find-and-replace)
wp datamachine workspace edit <name> <path> --old=<old_string> --new=<new_string>

Git Operations

# Git status
wp datamachine workspace git <name> status

# Pull latest
wp datamachine workspace git <name> pull

# Stage files
wp datamachine workspace git <name> add [<path>]

# Commit
wp datamachine workspace git <name> commit --message=<message>

# Push
wp datamachine workspace git <name> push

# View log
wp datamachine workspace git <name> log [--limit=<n>]

# View diff
wp datamachine workspace git <name> diff [<path>]

Special Syntax

Writes data to workspace repositories as a pipeline publish target. Configured with:

wp datamachine workspace write my-repo docs/README.md --content=@/tmp/readme-content.md

Architecture Diagram

AI Chat Tools              Pipeline Steps              CLI
                 |                          |                       |
    +------------+-------+       +---------+--------+              |
    |                    |       |                   |              |
    v                    v       v                   v              v
WorkspaceTools    WorkspaceScopedTools    Fetch/Publish      WorkspaceCommand
  (global,          (handler-scoped,      Handlers              |
   read-only)        path-restricted)        |                  |
    |                    |                   |                  |
    +--------+-----------+-------------------+------------------+
             |
             v
      WorkspaceAbilities
    (16 WordPress Abilities)
             |
      +------+------+
      |             |
      v             v
  Workspace    WorkspaceReader
  (core)       WorkspaceWriter
      |
      v
  /var/lib/datamachine/workspace/
    repo-1/  repo-2/  repo-3/

Source Files