Instances

Instances enable parallel development streams within a single project. Each instance maintains its own workspace, branch, and execution state—allowing you to work on multiple features simultaneously without interference.

What are Instances?

Think of instances as parallel universes for your codebase:

┌─────────────────────────────────────────────────────────────┐
│                     PROJECT: my-saas-app                    │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Instance: auth-overhaul                                    │
│  ├── Branch: feat/auth-v2                                   │
│  ├── Nanocycles: NC-010, NC-011, NC-012                    │
│  └── Status: Active                                         │
│                                                             │
│  Instance: dashboard-redesign                               │
│  ├── Branch: feat/dashboard-v2                              │
│  ├── Nanocycles: NC-013, NC-014                            │
│  └── Status: Active                                         │
│                                                             │
│  Instance: api-performance                                  │
│  ├── Branch: feat/api-perf                                  │
│  ├── Nanocycles: NC-015                                    │
│  └── Status: Paused                                         │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Why Use Instances?

Parallel Development

Work on multiple features without waiting:

Without instances (sequential):
  auth ──────────────────────────▶ dashboard ─────────────────▶

With instances (parallel):
  auth     ──────────────────────▶
  dashboard ──────────────────────────────▶
  api-perf      ────────────────▶

Feature Isolation

Each instance has complete isolation:

• Own git branch
• Own workspace
• Own nanocycle history
• Own execution state

Changes in one instance don't affect others.

Context Switching

Switch between work streams without losing context:

# Working on auth
tevis instance switch auth-overhaul

# Need to fix dashboard bug? Switch contexts
tevis instance switch dashboard-redesign

# Back to auth
tevis instance switch auth-overhaul
# Everything exactly where you left it

Instance Lifecycle

Creating an Instance

# Create from main branch
tevis instance create auth-overhaul

# Create from existing branch
tevis instance create auth-overhaul --from-branch feat/auth-wip

# Create with description
tevis instance create auth-overhaul \
  --description "Complete authentication system overhaul"

What happens:

1. New workspace created
2. Branch created (or checked out)
3. Instance registered
4. Ready for nanocycles

Working in an Instance

# Switch to instance
tevis instance switch auth-overhaul

# Create nanocycles within instance
tevis nanocycle create --description "Add OAuth providers"

# All work happens in instance context

Pausing an Instance

When switching focus:

# Pause current instance
tevis instance pause

# Or pause specific instance
tevis instance pause dashboard-redesign

Paused instances:

• Workspace preserved
• State saved
• No active TPUs
• Can resume anytime

Completing an Instance

When feature is done:

# Complete the instance
tevis instance complete auth-overhaul

# This:
# - Ensures all nanocycles closed
# - Creates final PR if needed
# - Archives artifacts
# - Optionally removes workspace

Archiving an Instance

After merge:

# Archive (preserves history, cleans workspace)
tevis instance archive auth-overhaul

Instance States

State	Description	Actions
active	Currently being worked on	Create nanocycles, execute
paused	Temporarily suspended	Resume, archive
completed	Work done, ready for merge	Merge, archive
archived	Fully complete	View history

Managing Instances

List Instances

tevis instance list

# Output
NAME                 BRANCH              STATUS    NANOCYCLES  LAST ACTIVE
auth-overhaul        feat/auth-v2        active    3           5 min ago
dashboard-redesign   feat/dashboard-v2   active    2           2 hours ago
api-performance      feat/api-perf       paused    1           2 days ago

Instance Details

tevis instance info auth-overhaul

# Output
Instance: auth-overhaul
Description: Complete authentication system overhaul
Branch: feat/auth-v2
Status: active
Created: 2026-02-01 09:00:00
Last Active: 5 minutes ago

Workspace: ~/.tevis-runtime/instances/auth-overhaul
Size: 156 MB

Nanocycles:
  NC-010: completed (OAuth providers)
  NC-011: completed (Session management)
  NC-012: in_progress (Security hardening)

Progress: 89%

Switch Instances

# Switch to named instance
tevis instance switch dashboard-redesign

# Or use interactive picker
tevis instance switch
# → Shows list, arrow keys to select

Delete Instance

# Delete with confirmation
tevis instance delete auth-overhaul

# Force delete (no confirmation)
tevis instance delete auth-overhaul --force

Instance in Mission Control

Instance Selector

The Mission Control UI includes an instance selector:

• Dropdown showing all instances
• Status indicators (active/paused/completed)
• Quick switch between instances
• "New Instance" button

Instance Panel

Each instance shows:

• Branch information
• Nanocycle list and status
• Progress metrics
• Quick actions

Instance Timeline

Visual timeline of instance activity:

• Nanocycle starts/completions
• Branch commits
• Status changes

Best Practices

One Feature Per Instance

✅ Instance: auth-system
   - All authentication work
   - Related nanocycles grouped

❌ Instance: miscellaneous
   - Auth + dashboard + random fixes
   - No coherent theme

Name Descriptively

✅ auth-oauth-integration
✅ dashboard-charts-redesign
✅ api-rate-limiting

❌ feature-1
❌ test
❌ wip

Complete Before Archiving

Don't archive with unfinished work:

# Check instance status
tevis instance info my-instance

# Ensure all nanocycles completed
# Then archive
tevis instance archive my-instance

Keep Count Manageable

Active instances consume resources:

# Check instance count
tevis instance list | wc -l

# Aim for:
# - 2-3 active instances max
# - Archive completed work promptly
# - Pause inactive instances

Instance vs Session vs Workspace

Concept	Scope	Lifetime	Purpose
Instance	Feature stream	Days/weeks	Parallel feature development
Session	Work period	Hours	Active work context
Workspace	Execution	Minutes/hours	Isolated git clone

Instance (auth-overhaul)
    │
    └── Session (sess_abc)
            │
            └── Workspace (nc-010-feat-oauth)

Merging Instances

When instance work is complete:

Option 1: PR from Instance Branch

# Complete instance
tevis instance complete auth-overhaul

# Instance creates PR: feat/auth-v2 → main
# Review and merge on GitHub

Option 2: Squash Merge

# Complete and squash all commits
tevis instance complete auth-overhaul --squash

# Single commit with all changes

Option 3: Rebase and Merge

# Rebase onto latest main first
tevis instance rebase auth-overhaul

# Then complete
tevis instance complete auth-overhaul

Troubleshooting

Instance Won't Switch

# Check current instance state
tevis instance info current

# Check for active TPUs
tevis tpu list

# Force pause current instance
tevis instance pause --force

# Then switch
tevis instance switch other-instance

Instance Workspace Missing

# Recreate workspace from branch
tevis instance repair auth-overhaul

# Or if branch still exists on remote
tevis instance repair auth-overhaul --from-remote

Conflicting Branches

If instance branch conflicts with main:

# Rebase onto main
tevis instance rebase auth-overhaul

# Resolve conflicts in workspace
cd ~/.tevis-runtime/instances/auth-overhaul
git status
# ... resolve conflicts ...
git rebase --continue

# Or abort and try different strategy
git rebase --abort