Sessions

A Session in Tevis represents an active work context—a focused period where you're working on a specific project with a particular configuration.

What is a Session?

Think of a session like opening a project in your IDE, but with superpowers:

• Repository binding — Connected to a specific git repository
• Context preservation — Your work state persists
• Nanocycle container — All nanocycles are created within sessions
• Real-time sync — Changes stream to Mission Control

┌─────────────────────────────────────────────────────┐
│                    SESSION                           │
│                                                      │
│  Project: my-saas-app                               │
│  Repository: github.com/user/my-saas-app           │
│  Started: 2026-02-06 09:00                          │
│                                                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐ │
│  │   NC-001    │  │   NC-002    │  │   NC-003    │ │
│  │  Complete   │  │  Complete   │  │ In Progress │ │
│  └─────────────┘  └─────────────┘  └─────────────┘ │
│                                                      │
└─────────────────────────────────────────────────────┘

Session Lifecycle

Creating a Session

# Via CLI
tevis session create --project my-project

# Or in Mission Control
# Click "New Session" in the project view

When a session starts:

1. Repository cloned — Fresh workspace created
2. Context loaded — Planning docs, memory, preferences
3. Services connected — Tevis Local, Core API, LPU
4. Session ID assigned — Unique identifier for tracking

During a Session

While a session is active:

• Create and execute nanocycles
• View real-time execution streams
• Access repository files
• Receive hold point notifications
• Review and merge completed work

Ending a Session

Sessions can be ended explicitly or timeout after inactivity:

# Via CLI
tevis session end

# Or in Mission Control
# Click "End Session" in session view

When a session ends:

1. Workspace preserved — Code stays in place
2. State saved — Progress, context, preferences
3. Cleanup — Temporary files removed
4. Summary generated — Session recap available

Session vs Project

Aspect	Project	Session
Lifecycle	Permanent	Temporary
Scope	All work ever	Current work context
Nanocycles	Contains all	Contains active ones
Repository	Configuration	Live workspace
Memory	Historical	Active context

A project can have many sessions. Each session is a focused work period.

Session Types

Development Session

The standard session type for active development:

type: development
repository: git@github.com:user/repo.git
branch: main
capabilities:
  - nanocycle_creation
  - code_execution
  - file_editing

Review Session

For reviewing completed nanocycles without execution:

type: review
repository: git@github.com:user/repo.git
branch: feat/nc-007-auth
capabilities:
  - code_viewing
  - diff_review
  - merge_approval

Planning Session

For strategic planning without code execution:

type: planning
capabilities:
  - plan_drafting
  - context_editing
  - memory_browsing

Session State

Sessions maintain state including:

Active Context

{
  "session_id": "sess_a1b2c3",
  "project_id": "proj_xyz",
  "repository": "git@github.com:user/repo.git",
  "branch": "main",
  "started_at": "2026-02-06T09:00:00Z",
  "nanocycles": ["NC-001", "NC-002", "NC-003"],
  "active_nanocycle": "NC-003"
}

Workspace State

{
  "workspace_path": "~/.tevis-runtime/session-repos/sess_a1b2c3",
  "git_status": "clean",
  "last_commit": "abc123",
  "modified_files": []
}

Execution State

{
  "active_tpus": 2,
  "pending_holdpoints": 0,
  "execution_status": "running"
}

Working with Sessions

List Active Sessions

# CLI
tevis session list

# Output
ID           PROJECT      STARTED              STATUS
sess_a1b2c3  my-saas-app  2026-02-06 09:00    active
sess_d4e5f6  docs-site    2026-02-05 14:30    paused

Switch Sessions

# CLI
tevis session switch sess_d4e5f6

# Or in Mission Control
# Click on session in session list

Session Details

tevis session info sess_a1b2c3

# Output
Session: sess_a1b2c3
Project: my-saas-app
Repository: git@github.com:user/repo.git
Branch: main
Started: 2026-02-06 09:00:00
Duration: 2h 30m

Nanocycles:
  NC-001: completed (auth-system)
  NC-002: completed (dashboard)
  NC-003: in_progress (settings-page)

Active TPUs: 2
Hold Points: 0

Session Best Practices

One Session Per Focus Area

Don't mix unrelated work in one session:

❌ Single session
   - Working on auth
   - Also fixing unrelated bugs
   - Also updating docs

✅ Separate sessions
   - Session 1: Authentication feature
   - Session 2: Bug fixes
   - Session 3: Documentation

End Sessions When Done

Don't leave sessions running indefinitely:

# End session when switching focus
tevis session end

# Start fresh session for new work
tevis session create --project other-project

Review Session Summaries

After ending a session, review the summary:

tevis session summary sess_a1b2c3

# Shows:
# - Nanocycles completed
# - Files changed
# - Time spent
# - Metrics

Session in Mission Control

The Mission Control UI provides rich session management:

Session Panel

• Active session details
• Nanocycle list and status
• Quick actions (new nanocycle, end session)

Session Switcher

• All sessions for current project
• Switch with one click
• Visual status indicators

Session Timeline

• Chronological view of session activity
• Nanocycle starts/completions
• Hold points and interventions

Troubleshooting

Session Won't Start

# Check for port conflicts
lsof -i :8082

# Verify Docker is running
docker info

# Check Tevis Local status
tevis-local status

Lost Session State

Sessions auto-save state, but if issues occur:

# Recover session
tevis session recover sess_a1b2c3

# Or create new session with same config
tevis session create --project my-project --from-config

Multiple Sessions Conflict

Only one session can be active at a time per project:

# End conflicting session
tevis session end sess_old

# Then start new one
tevis session create --project my-project