Viwo

VIWO

git worktree + containerization + agent harness

Run coding agents in isolated git worktrees backed by disposable containers.

VIWO creates clean, isolated development sessions so you can let an agent work without cluttering your current branch or granting it access to your everyday shell.

Each session combines:

- Git worktrees for branch isolation
- Containers for runtime isolation
- An agent harness for launching and managing coding agents

Today, the primary runtime is Claude Code inside Docker, with VIWO handling worktree creation, container lifecycle, auth forwarding, prompt expansion, and session cleanup.

Why VIWO

- Isolated workspaces: Every session gets its own git worktree and containerized runtime.
- Fast agent launches: Start a workspace and hand it to Claude Code in one command.
- Safe parallel work: Run multiple agent sessions against the same repository without polluting your current branch.
- Project-aware setup: Configure host-side setup, in-container setup, and custom bind mounts with viwo.yml.
- Better auth support: Use either an Anthropic API key or Claude subscription OAuth credentials.
- Issue-driven workflows: Expand GitHub issues and GitLab issues/MRs directly into the prompt.
- Attach anytime: Reconnect to a running session through dtach in the container.
- Session visibility: Sync Docker state, inspect running/completed sessions, and capture container output.

Table of Contents

- Installation
- Quick Start
- Project Configuration
  - Post-install hooks
  - Pre-agent commands
  - Custom bind mounts
- How it works
- Authentication
- GitHub and GitLab integration
- Security
- Development
  - Prerequisites
  - Install dependencies
  - Running the CLI
  - Type checking
  - Testing
  - Code quality
  - Build
- CLI Usage
- Architecture
-…