Overview

Core Mission

Stop Context Pollution & Token Burn in AI Agents. Sprawl provides a local, zero-trust workspace sandboxing and context governance framework for autonomous developers.

Today's AI coding assistants (like Cursor, Windsurf, Claude Code, and RooCode) are powerful, but they operate unconstrained. They waste tokens reading irrelevant node modules, pollute codebases with conflicting rule sets, and pose security risks by escaping project boundaries.

Sprawl CLI solves this by serving as an invisible governance layer. It compiles a single, zero-waste workspace manifest into native editor rules files and Model Context Protocol (MCP) configs, keeping your IP safe, sandboxed, and optimized.

Philosophy & Principles

  • 100% Local: Runs fully on your machine. Zero cloud dependency, zero network leakage, zero telemetry.
  • Stealth Injection: AI agents operate under constraints they cannot see or modify.
  • Agnostic Outputs: Write one config manifest, automatically generate specifications for all editors.

Installation

Install Sprawl directly from GitHub. No PyPI registry dependency — the source of truth is always the repository.

Option 1: Automated Script (Recommended)

The bootstrap script handles pipx isolation, PATH configuration, and SSH fallback automatically.

curl -sL https://raw.githubusercontent.com/sprawl-software/sprawl-cli/main/install.sh | bash

Option 2: Isolated Pipx Install

If you prefer to run pipx directly for full environment isolation:

pipx install git+ssh://git@github.com/sprawl-software/sprawl-cli.git

Option 3: Standard pip

pip install git+ssh://git@github.com/sprawl-software/sprawl-cli.git

Developer Onboarding Journey (Developer Path)

For developers, Sprawl eliminates the manual overhead of synchronizing instructions, rules, and virtual environments. Write your rules once in a central DNA registry and compile them dynamically for all your active IDEs and agents.

1. Initialize DNA Core

Pull your team's centralized DNA guidelines onto your machine globally:

sprawl init https://github.com/developer/atomic-agentic-fabric-demo-dna.git

2. Graft Onto Active Workspace

Navigate to your project root and graft the Sprawl structure. This automatically harvests legacy editor rules into local_* overrides:

cd my-project/
sprawl graft

3. Compile & Sync

Download DNA files, provision the virtual environment, and compile bindings for your active editors:

sprawl sync

4. Connect Editors

Link your rules to Cursor, Cline/RooCode, Windsurf, or Copilot using the interactive menu:

sprawl bind

Watch the Developer Workflow

Security Onboarding Journey (Security/CISO Path)

For security leads, Sprawl ensures workstation boundary containment, out-of-band telemetry database harvesting, and pre-commit GitOps rule enforcement.

1. Define Workspace Boundaries

Enforce directory-level isolation using directory-locked MCP file access. Grant access to external directories (like shared dependencies or common docs) using safe mounts:

sprawl mount add /path/to/shared-library --alias shared-lib

2. Enable Stealth Isolation

Split workspace configurations. Rules are visible to the agent via AGENTS.md, but the actual security configs, sync state, and original registries are stored out-of-band in ~/.sprawl/, preventing LLM code alterations from deleting their own security limits.

3. Telemetry Log Harvesting

Sprawl scrapes editor databases (Cursor, Windsurf, Claude Code, RooCode) out-of-band on the workstation. Log timelines can be pushed directly to a self-hosted corporate dashboard behind your firewall, ensuring zero code or prompts leave your network:

sprawl status

4. Enforce Pre-Commit Compliance

Set up git pre-commit hooks that trigger diagnostics to block commits unless rules are synchronized and mandatory compliance checks have passed:

sprawl doctor

sprawl create

1. The Target Problem

"How do I instantiate a new development workspace that complies with our team's AI governance policies, without copying over configs manually?"

When starting a new project, developers have to manually copy over .cursorrules, set up local model exclusion files, and copy prompt instructions. This leads to configuration errors, missing safety guidelines, and environment leakage.

2. The Solution Command

sprawl create my-new-project

3. Command Usage & Flags

FlagDescription
--path <path>Specify a custom directory to create the project in. Defaults to the current directory.
--non-interactive, -yBypass setup questionnaires and use default configuration templates.

4. How it Works (Under the Hood)

Sprawl initializes the target project directory, provisions a clean local .agents/ folder, scaffolds a default sprawl_manifest.yml, and automatically registers the new workspace path in the global tracking database (stored securely at ~/.sprawl/workspaces/).

5. Troubleshooting

  • Error: Path already exists. Choose a different workspace name or use the --path option to select a clean folder.

Example Output

╭────────────────────────── Workspace Initialization ──────────────────────────╮
│ ✔ Workspace Created                                                          │
│ • Name: qa_workspace                                                         │
│ • Path: /home/developer/Development/sprawl-cli/qa_sandbox/qa_workspace       │
│ • DNA Binding: @core                                                         │
│                                                                              │
│ • Run sprawl bind inside to select rules bindings for your IDEs/agents.      │
│ • Run sprawl sync inside to orchestrate.                                     │
╰──────────────────────────────────────────────────────────────────────────────╯

sprawl graft

1. The Target Problem

"How do I secure an existing project that contains disorganized, legacy editor rules files without losing our custom configurations?"

Over time, codebases accumulate multiple conflicting rules files (Cursor, Cline, Windsurf) representing different developer settings. AI agents reading these files get confused. Deleting them breaks custom setups, while leaving them wastes token budgets.

2. The Solution Command

cd my-legacy-project/
sprawl graft

3. Command Usage & Flags

Graft requires no additional flags and operates directly in the current directory.

4. How it Works (Under the Hood)

Sprawl scans the repository for files like .cursorrules, .clinerules, or .windsurfrules. It harvests their contents, places them inside .agents/rules/ prefixed with local_, and dynamically registers these files inside a generated sprawl_manifest.yml manifest.

5. Troubleshooting

  • Error: Not in a git repository. Ensure you are in the root directory of your project before executing the graft command.

sprawl ls

1. The Target Problem

"How do I discover what governing rules, workflows, or skill modules are available to install in my environment from the global registry?"

When customizing a workspace, developers need to know what security rules, architectural guidelines, or tool capabilities are available inside the company's global DNA registry. Checking these online breaks focus and is slow.

2. The Solution Command

sprawl ls

3. Command Usage & Flags

Lists available options categorized into rules, skills, personas, and workflows.

4. How it Works (Under the Hood)

Sprawl reads the registered global DNA registries located at ~/.sprawl/core/ and ~/.sprawl/dna/, scans their folders, and renders a structured summary directly in the terminal.

5. Troubleshooting

  • Warning: No global DNA registered. Ensure you have initialized your global DNA repository by running sprawl init <git_url> first.

Example Output

╭──────────────────────────────── DNA Registry ────────────────────────────────╮
│                                                                              │
│ Installed Contexts:                                                          │
│   • @global (Default Sprawl Hub DNA)                                         │
│   • @alt_dna                                                                 │
│                                                                              │
│ Active Context: /home/developer/.sprawl_test/core                            │
╰──────────────────────────────────────────────────────────────────────────────╯

🧬 Active DNA Artifacts (/home/developer/.sprawl_test/core)
┣━━ Personas
┃   ┣━━ persona-demo_engineer
┃   ┗━━ persona-senior_python_architect
┣━━ Rules
┃   ┣━━ demo_security.md
┃   ┗━━ python_stdlib_only.md
┗━━ Workflows
    ┗━━ demo_build.md

sprawl status

1. The Target Problem

"How do I check my workspace identity, active DNA bindings, installed files vs manifest requirements, and telemetry database health?"

Without a local status overview, developers and security auditors cannot quickly verify if their rules are out-of-sync, if their virtual environments are healthy, or if local IDE SQLite databases are being harvested correctly for session telemetry.

2. The Solution Command

sprawl status

3. Command Usage & Flags

sprawl status [target_dir]

4. How it Works (Under the Hood)

Sprawl queries the workspace config database, parses .agents/sprawl_manifest.yml, checks local .agents/ folders, inspects the virtual environment Python binary, and renders a Rich terminal status panel showing any rules drift or synchronization lag.

5. Troubleshooting

  • Diagnostics show "Python not executable". The local virtual environment has been corrupted. Run sprawl sync to repair it.
  • Sync status is shown as STALE. Run sprawl sync to download DNA registry updates.

Example Output

╭───────────────────────────── Workspace Identity ─────────────────────────────╮
│  Workspace             qa_workspace                                          │
│  Path                  /home/developer/Development/sprawl-cli/qa_sandbox/qa… │
│  DNA Binding           @core                                                 │
│  Active Model          Not set                                               │
│  Venv                  ● Healthy (Python 3.12.3)                             │
│  Last Sync             2026-07-05 11:09:43                                   │
╰──────────────────────────────────────────────────────────────────────────────╯

sprawl add

1. The Target Problem

"How do I inject a new rule, skill, or workflow from our company's DNA registry directly into my project's manifest without editing YAML files manually?"

Manually editing YAML manifests often results in syntax issues (like incorrect spaces or tabs) and requires looking up the exact file name online, slowing down setup.

2. The Solution Command

sprawl add rules/security-standards

3. Command Usage & Flags

sprawl add <item_name>

4. How it Works (Under the Hood)

Sprawl verifies the existence of the artifact in the registry, parses sprawl_manifest.yml, injects the new item under the appropriate category block, and automatically runs a workspace sync to compile the rules and update the compiled AGENTS.md file.

5. Troubleshooting

  • Error: Artifact not found. Run sprawl ls to check availability and verify spelling.

sprawl mount

1. The Target Problem

"How do I stop my AI assistant from reading files outside my workspace while still granting it secure access to specific shared folders?"

AI agents run with full host filesystem permissions and can exfiltrate SSH keys or database secrets. Blocking filesystem access entirely prevents models from reading legitimate shared dependencies, APIs, or documentation templates on disk.

2. The Solution Command

sprawl mount add /home/user/shared-libs/ --alias shared-lib

3. Command Usage & Flags

sprawl mount add <path> [--alias NAME]
sprawl mount remove <alias>
sprawl mount list

Running sprawl mount without subcommands opens the interactive checkbox TUI.

4. How it Works (Under the Hood)

Registers directory paths to alias keys in .agents/sprawl-config.json under allowed_mounts. Sprawl automatically updates the Claude Desktop/IDE MCP configs (mcp_config.json). Any path start with @alias/ is resolved. Out-of-bounds paths return a JSON-RPC containment error, preventing traversal.

5. Troubleshooting

  • Agent fails to find files. Make sure to instruct the agent in your prompts or instructions to use the @<alias>/ path prefix (e.g. @shared-lib/utils.py) instead of direct system paths.

Example Output

Tracked Mounts                               
┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Alias/Prefix   ┃ Absolute Target Path                                        ┃
┡━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ @shared-lib    │ /home/developer/Development/shared-libs                     │
└────────────────┴─────────────────────────────────────────────────────────────┘

sprawl bind

1. The Target Problem

"How do I compile my centralized rules manifest into the native configuration formats of all my active IDEs and agents without manual copying?"

Configuring multiple files like .cursorrules, .windsurfrules, .clinerules, and Claude Desktop's config files manually is repetitive and results in outdated rule configurations.

2. The Solution Command

sprawl bind

3. Command Usage & Flags

FlagDescription
--allBind all available IDEs and agents without running the interactive menu.
--forceForce compile and overwrite existing configuration files.
--only <adapters>Specify a comma-separated list of adapters to bind (e.g. --only cursor,cline).

4. How it Works (Under the Hood)

Binds the workspace configurations dynamically. The interactive checkbox menu lets you toggle adapters, updating sprawl_manifest.yml and generating the required configuration files automatically.

5. Troubleshooting

  • IDE configurations do not update. Run the command with the --force flag to overwrite write-protected config files.

sprawl update

1. The Target Problem

"How do I keep my Sprawl CLI engine and my global team DNA rules synchronised with upstream repository updates?"

As team guidelines change, rules and CLI tooling must be updated. Doing so manually results in local drift and deprecated rules configurations across different developer workstations.

2. The Solution Command

sprawl update

3. Command Usage & Flags

FlagDescription
--dry-runPreview update changes without downloading or modifying local files.

4. How it Works (Under the Hood)

Performs a git pull inside the global registry folder at ~/.sprawl/core/, then re-runs the installer via pipx to compile and build the CLI binary cleanly.

5. Troubleshooting

  • Update fails during git clone/pull. Ensure you are authenticated with your git provider (e.g. running gh auth login or linking your SSH keys). Sprawl automatically falls back to HTTPS if SSH authentication fails.

Example Output

[*] Initiating Sprawl Update Sequence...
[*] Updating Global DNA at /home/developer/.sprawl_test/core...
Already up-to-date.
[*] Global DNA updated successfully.
[*] Production/release installation detected. Installing update from GitHub...
[*] Attempting installation via SSH: git+ssh://git@github.com/sprawl-software/sprawl-cli.git...
[*] Sprawl CLI updated successfully from GitHub via SSH.
[*] Update Sequence complete.

sprawl dna

1. The Target Problem

"How do I add secondary DNA registries for other teams or projects without polluting my global core DNA guidelines?"

Developers working on multiple client projects need isolated DNA registries. Modifying the global core repository results in conflict, while changing registry settings manually for every project is slow.

2. The Solution Command

sprawl fetch-dna https://github.com/my-org/custom-team-dna.git custom-team

3. Command Usage & Flags

sprawl dna list
sprawl dna inspect
sprawl dna update

4. How it Works (Under the Hood)

Clones the secondary DNA repository inside ~/.sprawl/dna/<alias>/, registers it, and resolves dependencies from the secondary registry if specified in the workspace manifest (e.g. dna: custom-team).

5. Troubleshooting

  • Error: DNA alias already exists. Ensure you specify a unique custom alias name when fetching a new registry.

Example Output (dna list)

Registered DNA Sources                           
┏━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Status ┃ Alias    ┃ Type      ┃ Path                                     ┃
┡━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│   ●    │ @global  │ Primary   │ /home/developer/.sprawl_test/core        │
│   ●    │ @alt_dna │ Secondary │ /home/developer/.sprawl_test/dna/alt_dna │
└────────┴──────────┴───────────┴──────────────────────────────────────────┘

sprawl sync

1. The Target Problem

"How do I ensure my workspace virtual environment is provisioned and all agent IDE bindings are freshly compiled when DNA rules are updated?"

When you pull updates to your global DNA rules registry, your active local workspaces fall out-of-sync. Running agents might continue using stale configurations, or their virtual environments might lack required dependencies, causing agent failures.

2. The Solution Command

sprawl sync [target_dir]

3. Command Usage & Flags

Syncs DNA context and provisions the workspace environment in the specified directory (defaults to current directory).

4. How it Works (Under the Hood)

Sync pulls DNA rule files, provisions the python virtual environment inside .agents/.venv, aggregates prompt files into a compiled AGENTS.md manifest, and regenerates Claude Desktop/IDE MCP schemas.

5. Troubleshooting

  • Virtual environment provisioning fails. Ensure you have Python 3.10+ installed and the python3-venv library present on your operating system.

Example Output

[*] Syncing /home/developer/Development/sprawl-cli/qa_sandbox/qa_workspace...
[*] Provisioning sandboxed virtual environment at /home/developer/Development/sprawl-cli/qa_sandbox/qa_workspace/.agents/.venv...
[*] Generating IDE & Agent bindings (standard mode)...
  [-] Antigravity MCP Schemas: Removed → sprawl-workspace-fs
  [-] Antigravity MCP Schemas: Removed → sprawl-vault

Bindings are present, to configure you bindings run sprawl bind.

╭────────────────────────── Workspace Orchestration ───────────────────────────╮
│ ✔ Sync Complete                                                              │
│ • Files Synced: 0                                                            │
│ • Files Pruned: 0                                                            │
│ • Venv Provisioned: Yes                                                      │
│ • Bindings Created: Yes                                                      │
╰──────────────────────────────────────────────────────────────────────────────╯

sprawl shell

1. The Target Problem

"How do I run and test python-based agent skills or scripts in the same isolated virtual environment that the editor agent runs in?"

When debugging agent tools or running custom python scripts, running them in your global system python environment can lead to dependency conflicts or missing modules that only exist in the agent's sandboxed environment.

2. The Solution Command

sprawl shell [target_dir]

3. Command Usage & Flags

Activates the workspace virtual environment in a subshell, pre-configuring VIRTUAL_ENV and path settings.

4. How it Works (Under the Hood)

Spawns a new subshell with .agents/.venv/bin/activate sourced. This isolates path lookups and libraries so that your terminal execution matches the agent's runtime environment.

5. Troubleshooting

  • Error: Virtual environment is not provisioned. Run sprawl sync first to build the workspace virtual environment.

sprawl doctor

1. The Target Problem

"How do I run sanity diagnostics on my developer workstation to check if the path, global core DNA files, and editor settings are intact?"

When troubleshooting configuration issues or setup mismatches, it is difficult to isolate whether the issue is a missing system package, a corrupted DNA registry, or misconfigured IDE bindings.

2. The Solution Command

sprawl doctor

3. Command Usage & Flags

Runs system-wide checks checking for dependencies and active configuration directories.

4. How it Works (Under the Hood)

Verifies OS prerequisites (Python, Git, Node, Cargo), validates the global DNA registry in ~/.sprawl/core/, and checks the status of active IDE bindings.

5. Troubleshooting

  • Node/NPM or Rust/Cargo warnings. These are optional dependencies. You can continue using Sprawl, but some language-specific agent skills may fail to install.

Example Output

Running Sprawl Diagnostics...

✔ Python 3.10+
✔ Git
⚠ Node/NPM
⚠ Rust/Cargo
✔ Global DNA
✔ Local Workspace

Diagnostic Summary                                                              
┏━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Component       ┃ Status ┃ Details                                           ┃
┡━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Python 3.10+    │ ✔ PASS │ 3.12.3                                            │
│ Git             │ ✔ PASS │ Installed (/usr/bin/git)                          │
│ Node/NPM        │ ⚠ WARN │ Not Found (Optional for TS/JS skills)             │
│ Rust/Cargo      │ ⚠ WARN │ Not Found (Optional for Rust skills)              │
│ Global DNA      │ ✔ PASS │ Initialized at /home/developer/.sprawl_test/core  │
│ Local Workspace │ ✔ PASS │ Active at /home/developer/my-project              │
└─────────────────┴────────┴───────────────────────────────────────────────────┘

╭──────────────────────────────────────────────────────────────────────────────╮
│ Diagnostics passed with 2 warning(s).                                        │
│ Sprawl will function, but some language-specific skills may fail to install. │
╰──────────────────────────────────────────────────────────────────────────────╯

sprawl ws

1. The Target Problem

"How do I manage, list, deregister, or mass-update (push changes to) all tracked workspace directories from a single centralized management registry?"

As you scale your AI workflows, you accumulate dozens of sandboxed workspaces. Manually checking their synchronisation states, cleaning up stale paths, or updating them one-by-one is tedious and error-prone.

2. The Solution Command

sprawl ws list
sprawl ws remove my-old-project --delete
sprawl ws push

3. Command Usage & Flags

Command / FlagDescription
listLists all tracked workspaces with name, path, DNA binding, and status.
remove <name>Deregisters the workspace from global tracking.
remove <name> --deleteDeregisters the workspace AND recursively deletes the project directory from disk.
push [name]Bulk-synchronizes DNA updates to all tracked workspaces (or a specific workspace if name is provided).

4. How it Works (Under the Hood)

Sprawl queries the tracking registries inside ~/.sprawl/workspaces/, verifies that the configured paths exist on the local file system, and compares timestamps to determine sync health. The bulk-push mechanism loops over matching targets and executes isolated clean-room synchronisation sweeps.

5. Troubleshooting

  • Status circle shows as missing (○). The project directory was moved or deleted outside Sprawl. Run sprawl ws remove <name> to prune the registry.

Example Output (ws list)

Tracked Workspaces                               
┏━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┓
┃ Status ┃ Name         ┃ Path                    ┃ DNA Binding    ┃ Last Sync ┃
┡━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━┩
│   ●    │ qa_workspace │ /home/developer/Develo… │ Global/Default │ Never     │
└────────┴──────────────┴─────────────────────────┴────────────────┴───────────┘

Example Output (ws remove)

[*] Workspace 'qa_workspace' has been deregistered.
[*] Workspace directory /home/developer/Development/sprawl-cli/qa_sandbox/qa_workspace has been deleted.

Example Output (ws push)

[*] Pushing updates to workspace 'qa_workspace' at /home/developer/Development/sprawl-cli/qa_sandbox/qa_workspace...
[*] Syncing /home/developer/Development/sprawl-cli/qa_sandbox/qa_workspace...
[*] Generating IDE & Agent bindings (standard mode)...
  ✔ Codex Binding: Created symlink → ../AGENTS.md
  ✔ Antigravity MCP Schemas: Provisioned → ~/.gemini/antigravity/mcp/

╭────────────────────────── Workspace Orchestration ───────────────────────────╮
│ ✔ Sync Complete                                                              │
│ • Files Synced: 1                                                            │
│ • Files Pruned: 0                                                            │
│ • Venv Provisioned: Existing                                                 │
│ • Bindings Created: Yes                                                      │
╰──────────────────────────────────────────────────────────────────────────────╯

sprawl diff

1. The Target Problem

"How do I check if my local workspace rules have drifted or been modified compared to the organization's central DNA registry?"

When working on customized local workspaces, you may accidentally modify rules or miss updates pushed to the central DNA repository, leading to drift in configuration standards.

2. The Solution Command

sprawl diff [workspace_path]

3. Command Usage & Flags

Runs a hash-based file contents comparison against the active core DNA template.

4. How it Works (Under the Hood)

Queries core templates and performs file-by-file text content comparisons, showing line-by-line differences of your workspace rules and configurations against the registry source.

5. Troubleshooting

  • To overwrite local drift and reset to DNA standard. Simply execute a fresh sprawl sync.

Example Output

Comparing local DNA drift against @core...

╭──────────────────────────────── Sync Status ─────────────────────────────────╮
│ ✔ No DNA drift detected. Your local workspace perfectly matches the upstream │
│ registry.                                                                    │
╰──────────────────────────────────────────────────────────────────────────────╯

sprawl demo

1. The Target Problem

"How do I test how Sprawl intercepts process execution or directory traversal requests without setting up a full workspace?"

Validating path-traversal safeguards or checking the sandbox environment without starting a full project layout is difficult and can cause configuration clutter.

2. The Solution Command

sprawl demo

3. Command Usage & Flags

Runs interactive sandbox demonstrations locally in your shell environment.

4. How it Works (Under the Hood)

Spawns a mock sandboxed subshell and triggers mock absolute path queries to showcase standard stdio path interceptors and containment boundaries.

sprawl man

1. The Target Problem

"How do I access the full Sprawl documentation, guidebooks, and command examples when I am offline or have no internet access?"

When working in offline or secure air-gapped environments, loading web documentation is impossible. Developers need a direct terminal-accessible reference manual.

2. The Solution Command

sprawl man

3. Command Usage & Flags

Loads and displays the full formatted manual directly inside your current terminal session.

4. How it Works (Under the Hood)

Reads the built-in text manual database included in the Sprawl CLI library bundle and renders it using Rich formatting directly to standard output.

sprawl wipe

1. The Target Problem

"How do I completely and cleanly uninstall all Sprawl-generated directories, global registries, and editor configs without leaving configuration trails on my machine?"

When shifting between workstations or removing toolchains, you want to leave no trace of Sprawl configuration settings, virtual environments, or symlinks behind.

2. The Solution Command

sprawl wipe [target_dir] [--force] [--local-only]

3. Command Usage & Flags

FlagDescription
--forceBypass confirmation prompts and wipe folders immediately.
--local-onlyOnly wipe the local workspace .agents/ folders, leaving the global registry intact.

4. How it Works (Under the Hood)

Deletes the target workspace .agents/ directory, cleans up local editor symlinks and config files, deregisters the workspace from global tracking, and (if not --local-only) completely deletes the global core registry inside ~/.sprawl/.

5. Troubleshooting

  • Wipe does not delete the CLI command itself. Sprawl wipe only deletes config folders and symlinks. To remove the binary, run pipx uninstall sprawl-cli.

Example Output

!!! NUCLEAR WIPE INITIATED !!!
Will destroy local workspace: /home/developer/Development/sprawl-cli/qa_sandbox/qa_workspace/.agents
Will destroy global DNA registry & configuration: /home/developer/.sprawl_test
Note: To completely uninstall the CLI tool itself, run: pipx uninstall sprawl-cli
[*] Deregistered workspace 'qa_workspace' from global tracking.
[*] Destroyed local workspace: /home/developer/Development/sprawl-cli/qa_sandbox/qa_workspace/.agents
[*] Destroyed global DNA registry and configuration: /home/developer/.sprawl_test

✔ Sprawl traces have been wiped.

Stealth Isolation Layer

The core mechanism of Sprawl v2 is the Stealth Isolation Layer. To prevent un-sandboxed agents from mutating Sprawl controls or escaping boundaries, the workspace rules are isolated into two separate planes.

VISIBLE WORKSPACE (Stealth) AGENTS.md Only files/paths visible to LLM .agents/sprawl_manifest.yml User definitions / dependency locks INVISIBLE MANAGEMENT PLANE ~/.sprawl/workspaces/ Binds, sync states, & security locks ~/.sprawl/core/ & ~/.sprawl/dna/ Untouchable global DNA registries

By storing operational metadata (DNA bindings, sync status, and original repositories) completely outside the project directory in ~/.sprawl/, the agent is kept unaware of the containment environment. It operates purely within the confines of the workspace files, preventing LLM code alterations from deleting their own security configs.

Model Context Protocol (MCP) Safeguards

Sprawl CLI secures developer environments by managing filesystem permissions directly at the **Model Context Protocol (MCP) layer** and **IDE system prompt level**, rather than modifying the operating system kernel or command shell process directly.

When an AI agent (such as Claude Code, Cursor, or RooCode) attempts to read, write, or list directories, it does so by calling custom tools exposed by Sprawl's native sprawl-workspace-fs MCP server.

During tool execution, Sprawl's filesystem wrapper validates the input paths against the workspace boundaries and active allowed directory mounts in .agents/sprawl-config.json. If a model tries to escape these boundaries (e.g. via parent directory traversal .. or absolute paths /), the MCP server halts execution and returns a strict JSON-RPC standard error response.

JSON-RPC Containment Error Response

When an agent attempts to call the read_file tool with an out-of-bounds absolute path like /home/user/.ssh/id_rsa, Sprawl returns the following security violation payload:

{
  "jsonrpc": "2.0",
  "id": 42,
  "error": {
    "code": -32602,
    "message": "Security Violation: Absolute paths and home expansion are not allowed."
  }
}

Architectural Decisions (ADR)

ADR 001: Zero Heavy Third-Party Dependencies

Context: CLI runtimes must boot in sub-100ms speeds to prevent developers and agents from experiencing synchronization latency.

Decision: Use pure Python standard library packages for all CLI core functions (argparse, shutil, subprocess, os). Rich is only imported for visual terminal styling on demand.

ADR 002: Stealth Containment

Context: Un-sandboxed coding agents may hallucinate or intentionally modify security configs within the workspace if they detect them.

Decision: Keep all global registry paths in user home directory and enforce workspace isolation invisibly, exporting a read-only compiled context file (`AGENTS.md`) for agent training.