Ever wanted to test out an idea or fix a bug, but you didn't want to pollute your working branch? Or do you ever get super annoyed by all the questions and permissions Claude asks you?
Well, VIWO (Virtual Workspaces) might just be your solution:
- Docker-sandboxed environments: In order to use Claude Code with
--dangerously-skip-permissions, we are using Docker to sandbox the runtime environment. - Git worktrees: Maintain a clean separation between your working branch and Claude's branch—so you can work while Claude works!
- Ease-of-use: Quickly jump in to a worktree session by opening it in your favourite IDE.
- Multiple agents: With VIWO, it's extremely easy to spin up multiple agents to go do your task for you.
- [COMING SOON] GitHub/GitLab integration: Once you're done, let AI handle submitting "your" work for you!
- [COMING SOON] Improved multiline support: Paste in large amounts of text and play around with your prompt before submitting.
- [COMING SOON] Recap of changes made: View a recap of the work completed by AI directly inside VIWO CLI.
- VIWO
MacOS & Linux
curl -fsSL https://raw.githubusercontent.com/OverseedAI/viwo/main/install.sh | bashWindows
irm https://raw.githubusercontent.com/OverseedAI/viwo/main/install.ps1 | iexNote:
- You may need to restart your terminal after installation for the PATH changes to take effect.
After installation, initialize your first session:
# Register your Anthropic API key
viwo auth
# Register a repository
cd /path/to/your/repo
viwo register # viwo register /path/to/your/repo also works
# Start a session
viwo start
# List sessions
viwo listThe end result is a Claude Code instance in a Docker container. To get there, VIWO takes a git repository,
creates a git worktree in a separate directory, then creates a Docker container with a volume mount to that
new git worktree. The Docker container then runs a fresh installation of Claude Code in "print" mode with
--dangerously-skip-permissions enabled to help you one-shot your prompts.
viwo authstores your API key in a sqlite database in your app data directory. This API key is then provided to the Docker containers that run Claude Code.viwo registerstores the repository path and name into the sqlite database for subsequent retrieval.viwo startcreates a new git worktree and a Docker container. This container then runsclaude -p "YOUR PROMPT".
Running Claude with --dangerously-skip-permissions (DSP) comes with its own risks. The safest way to run Claude with
DSP would be isolated virtual machines. VIWO relies on the security of Docker containers to limit the attack surface of AI hackers,
but that does not mean Docker containers are inherently impenetrable. You can learn more about how Docker manages the
security of their containers here.
- Bun v1.0 or higher
- Git
- Docker (Daemon must be running)
-
Clone and install dependencies
git clone <repository-url> cd viwo bun install
-
Link the CLI globally
cd packages/cli bun link -
Verify installation
viwo --help
That's it! No build step required during development. 🎉
viwo/
├── packages/
│ ├── core/ # Core SDK (@viwo/core)
│ └── cli/ # CLI tool (@viwo/cli)
└── apps/ # Future applications
Since this is a Bun monorepo with direct source imports, you can run the CLI immediately without building:
# Option 1: Run directly from source
bun packages/cli/src/cli.ts --help
# Option 2: Use the globally linked command (recommended)
viwo --help- Edit source files in
packages/core/src/orpackages/cli/src/ - Changes are immediately available - no build step needed!
- Run the CLI to test your changes:
viwo start
The core package uses direct TypeScript source imports - Bun's native TypeScript support makes this possible without compilation during development.
# Check all packages
bun run typecheck
# Check specific package
cd packages/core && bun run typecheck# Run tests in core package
cd packages/core && bun test# Format code
bun run format
# Check formatting
bun run format:check
# Lint code
bun run lintviwo startviwo listWhile development doesn't require a build step, you can build for production/publishing:
# Build all packages
bun run build
# Build specific package
cd packages/core && bun run buildThis creates the dist/ directories with compiled JavaScript and type definitions.
Remove all build artifacts, caches, and dependencies:
bun run cleanThe core package provides:
- Git worktree management
- Docker container orchestration
- AI agent initialization (Claude Code, Cline, Cursor)
- Session state management with Bun's native SQLite
- Port allocation
Key Feature: Uses direct source imports - exports TypeScript files directly without a build step during development.
A command-line interface built on top of @viwo/core:
- Interactive session management
- Pretty-printed output with colors and tables
- Progress indicators
- Comprehensive error handling
rm /usr/local/bin/viwo # or wherever you installed it# Remove the binary
Remove-Item "$env:LOCALAPPDATA\Programs\viwo\viwo.exe"
# Remove from PATH (optional)
# Open "Edit environment variables for your account" and remove the viwo directory from PATH