Skip to main content

Workspaces

Workspaces are isolated git clones where Tevis executes code. Each TPU, session, or instance operates within its own workspace, ensuring clean separation and safe parallel execution.

Why Workspaces?​

Traditional development uses a single repository clone. This creates problems for parallel AI execution:

  • Conflicts — Multiple agents editing same files
  • State pollution — One agent's changes affecting another
  • No isolation — Failures cascade across work
  • Single-threaded — Can't parallelize safely

Workspaces solve this by giving each execution unit its own isolated environment.

Workspace Types​

TPU Workspaces​

Created for nanocycle execution:

.tevis-runtime/tpu-repos/
├── nc-007-feat-settings-api/     # Feature 1 workspace
├── nc-007-feat-settings-ui/      # Feature 2 workspace
└── nc-007-feat-integration/      # Feature 3 workspace

Each TPU feature gets its own workspace with:

  • Full repository clone
  • Independent git state
  • Own branch for changes
  • Isolated file system

Session Workspaces​

Created for interactive sessions:

.tevis-runtime/session-repos/
└── sess_a1b2c3/                  # Session workspace
    ├── .git/
    ├── src/
    └── ...

Session workspaces are used for:

  • File browsing in Mission Control
  • Quick edits outside nanocycles
  • Repository exploration

Instance Workspaces​

Created for parallel development instances:

.tevis-runtime/instances/
├── auth-feature/                 # Instance 1
├── dashboard-redesign/           # Instance 2
└── api-v2/                       # Instance 3

Instance workspaces enable multiple Flight Directors (or one Flight Director with multiple focus areas).

Workspace Lifecycle​

Creation​

Request Workspace
       │
       ▼
┌──────────────────────┐
│   Clone Repository   │
│   (fresh copy)       │
└──────────────────────┘
       │
       ▼
┌──────────────────────┐
│   Create Branch      │
│   (if needed)        │
└──────────────────────┘
       │
       ▼
┌──────────────────────┐
│   Initialize         │
│   (deps, env)        │
└──────────────────────┘
       │
       ▼
    Ready for Use

Usage​

During execution:

  • Files created/modified
  • Tests run
  • Commits made to feature branch
  • Progress logged

Completion​

Execution Complete
       │
       ▼
┌──────────────────────┐
│   Push Branch        │
│   (to origin)        │
└──────────────────────┘
       │
       ▼
┌──────────────────────┐
│   Archive Artifacts  │
│   (logs, progress)   │
└──────────────────────┘
       │
       ▼
┌──────────────────────┐
│   Cleanup            │
│   (delete workspace) │
└──────────────────────┘

Workspace Structure​

A typical workspace mirrors the repository with execution additions:

.tevis-runtime/tpu-repos/nc-007-feat-auth/
├── .git/                    # Independent git state
├── .tevis/                  # Tevis execution metadata
│   ├── workspace.json       # Workspace config
│   └── execution.log        # Local execution log
├── TEVIS.md                 # Agent instructions (gitignored)
├── tasks.json               # Task definitions (gitignored)
├── progress.txt             # Execution progress (gitignored)
├── src/                     # Repository code
├── tests/
└── ...

Special Files​

FilePurposeCommitted
TEVIS.mdInstructions for AI agentNo
tasks.jsonTask definitionsNo
progress.txtExecution progressNo
.tevis/workspace.jsonWorkspace metadataNo
All other filesNormal repositoryYes

Git in Workspaces​

Branch Strategy​

Each workspace operates on its own branch:

main
 │
 ├── nc-007-feat-settings-api      # TPU-1 branch
 │
 ├── nc-007-feat-settings-ui       # TPU-2 branch
 │
 └── nc-007-feat-integration       # TPU-3 branch

On completion, branches merge:

nc-007-feat-settings-api  ──┐
                            ├── nc-007-execution (merged)
nc-007-feat-settings-ui   ──┤           │
                            │           └── PR to main
nc-007-feat-integration   ──┘

Commit Conventions​

Commits within workspaces follow the pattern:

[Tevis NC-007] T003: Add password validation schema

- Created PasswordChangeSchema with current/new password fields
- Added password strength validation
- Includes minimum length and complexity requirements

Co-Authored-By: Claude <noreply@anthropic.com>

Conflict Handling​

If branches conflict during merge:

  1. Tevis detects conflict
  2. Hold point triggered
  3. Flight Director resolves or provides guidance
  4. Merge continues

Workspace Isolation​

Why Isolation Matters​

Without isolation:

❌ TPU-1 modifies auth.py
❌ TPU-2 also modifies auth.py
❌ Conflict! Both agents confused
❌ Work lost or corrupted

With workspace isolation:

✅ TPU-1 modifies auth.py in workspace-1
✅ TPU-2 modifies auth.py in workspace-2
✅ No conflict during execution
✅ Merge handled at completion

Security Boundaries​

TPU containers can only access their workspace:

# Container config (simplified)
volumes:
  - ~/.tevis-runtime/tpu-repos/nc-007-feat-auth:/workspace:rw
  - ~/.tevis/claude_oauth_credentials.json:/credentials:ro

# No access to:
# - Other workspaces
# - Host file system
# - Network (except allowed APIs)

Managing Workspaces​

List Workspaces​

# List all active workspaces
tevis workspace list

# Output
TYPE      ID                          STATUS    SIZE
tpu       nc-007-feat-settings-api    active    145 MB
tpu       nc-007-feat-settings-ui     active    145 MB
session   sess_a1b2c3                 active    148 MB
instance  auth-feature                paused    152 MB

Inspect Workspace​

tevis workspace info nc-007-feat-settings-api

# Output
Workspace: nc-007-feat-settings-api
Type: tpu
Nanocycle: NC-007
Feature: settings-api
Created: 2026-02-06 10:00:00
Branch: nc-007-feat-settings-api
Status: active
Size: 145 MB

Files Modified: 12
Commits: 3
Last Activity: 2 minutes ago

Clean Up Workspaces​

# Remove specific workspace
tevis workspace remove nc-007-feat-settings-api

# Clean all completed workspaces
tevis workspace cleanup --completed

# Clean all workspaces (caution!)
tevis workspace cleanup --all

Workspace Best Practices​

Don't Modify Directly​

Avoid manually editing files in workspaces:

❌ cd ~/.tevis-runtime/tpu-repos/nc-007-feat-auth
❌ vim src/auth.py

✅ Let TPUs handle execution
✅ Use hold points for interventions
✅ Make changes through nanocycle scope

Monitor Disk Usage​

Workspaces accumulate during active development:

# Check workspace disk usage
du -sh ~/.tevis-runtime/*/

# Clean up regularly
tevis workspace cleanup --completed

Preserve for Debugging​

If execution fails, keep workspace for investigation:

# Don't auto-cleanup failed workspaces
tevis config set cleanup.preserve_failed true

# Then inspect
cd ~/.tevis-runtime/tpu-repos/nc-007-feat-auth
git log
cat progress.txt

Runtime Directory Structure​

All workspaces live under .tevis-runtime/:

.tevis-runtime/
├── tpu-repos/           # TPU execution workspaces
│   ├── nc-007-feat-x/
│   └── nc-008-feat-y/
├── session-repos/       # Session workspaces
│   └── sess_xyz/
├── instances/           # Instance workspaces
│   └── feature-z/
├── logs/               # Runtime logs
├── cache/              # Temporary cache
└── instances.json      # Instance registry

This directory is gitignored and can be safely deleted to reset all workspaces.

Troubleshooting​

Workspace Creation Failed​

# Check git access
ssh -T git@github.com

# Check disk space
df -h ~/.tevis-runtime

# Check Docker
docker info

Workspace Stuck​

# Check workspace status
tevis workspace info <workspace-id>

# Force cleanup
tevis workspace remove <workspace-id> --force

Out of Disk Space​

# Clean completed workspaces
tevis workspace cleanup --completed

# Clean cache
rm -rf ~/.tevis-runtime/cache/*

# Nuclear option (removes all)
rm -rf ~/.tevis-runtime