sprawl shell

Diagnostics

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

📌 1. The Target Problem

1. The Target Problem

"How do I execute test scripts or build commands using the exact same virtual environment and dependency paths that my AI agent uses?"

When testing local skills or custom agent scripts, developers often run into import errors or dependency mismatches because their host shell uses a different Python environment or path than the sandboxed AI runtime.

⚙️ 2. Usage & Options

sprawl shell [target_dir]

Options & Flags

  • target_dir: Optional target workspace path (defaults to current folder).

🔍 3. How it Works (Under the Hood)

  1. Verifies that a valid Python virtual environment exists inside the workspace at .agents/.venv/.
  2. Prepends the virtualenv bin directory (e.g. .agents/.venv/bin/) to your shell $PATH variable.
  3. Sets standard VIRTUAL_ENV and SPRAWL_WORKSPACE environment bindings, spawning a subshell.

🩺 4. Troubleshooting

  • Error: Virtual environment not found
  • Resolution: Workspace has not been synchronized. Execute sprawl sync first to build the Python sandboxed environment.
  • How do I exit the shell?
  • Resolution: Type exit or press Ctrl+D to return to your normal host terminal.

🔗 Related Resources & Tutorials