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.

Complete Command Matrix

A reference index of all available Sprawl CLI commands and their default subsystem groupings.

Command Subsystem Group Description
sprawl init DNA Governance Clones Sovereign DNA globally (~/.sprawl/core) and links CLI.
sprawl create Workspace Lifecycle Scaffolds a new standard workspace bound to Sovereign DNA.
sprawl graft Workspace Lifecycle Surgically stitches Sprawl DNA onto an existing legacy codebase.
sprawl sync Sandboxing & DNA Injects DNA into local scope and provisions sandboxes (.venv, npm, cargo).
sprawl bind IDE & Agent Adapters Generates universal IDE/Agent bindings (Cursor, Antigravity, Windsurf, Copilot).
sprawl update DNA Governance Auto-updates both Global Sovereign DNA and local Sprawl CLI engine.
sprawl status Diagnostics Displays workspace status, DNA binding, artifacts, and venv health.
sprawl doctor Diagnostics Runs system diagnostics to verify tool dependencies and environment health.
sprawl ws Multi-Workspace Lists, removes, and pushes DNA updates across all tracked workspaces.
sprawl mount Sandboxed Context Configures allowed directory mounts for sandboxed MCP server access.
sprawl diff Diagnostics Visualizes DNA drift between local workspace and upstream registry.
sprawl ls Artifact Engine Scans active DNA registry and lists all available rules, skills, and workflows.
sprawl add Artifact Engine Smart injection of rules, skills, atoms, and workflows.
sprawl shell Sandboxing & DNA Enters a workspace-isolated subshell with activated .venv.
sprawl demo Diagnostics Interactive native demonstration engine.
sprawl man Diagnostics Prints the comprehensive AAF manual and setup guide directly.
sprawl wipe Diagnostics Nuclear wipe command to cleanly remove all Sprawl traces from your system.

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+https://github.com/sprawl-software/sprawl-cli.git

Option 3: Standard pip

pip install git+https://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 (sprawl init) ➔

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

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

2. Graft Onto Active Workspace (sprawl graft) ➔

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. Customize Local Manifest

Configure what rules, skills, and workflows your workspace needs in .agents/sprawl_manifest.yml.

4. Discover DNA Registry Artifacts (sprawl ls / add) ➔

List available registry rules, skills, and workflows, and add them dynamically to your manifest:

sprawl ls
sprawl add rules/coding-standards

5. Orchestrate Workspace (sprawl sync) ➔

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

sprawl sync

6. Connect Editors (sprawl bind) ➔

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

sprawl bind

7. Launch Isolated Agent Workflows (sprawl shell) ➔

Enter the workspace-isolated environment shell to run and test python-based agent skills or scripts in the same environment the agent uses:

sprawl shell

Watch the Developer Workflow

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_manifest.yml. 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.