Skip to main content

Quick Start

Get Tevis running and create your first nanocycle in under 5 minutes.

Prerequisites​

Before you begin, ensure you have:

  • Python 3.11+ installed
  • Docker installed and running
  • Claude CLI authenticated (claude login)
  • Git configured
# Verify prerequisites
python3 --version   # Should be 3.11+
docker --version    # Should be 20.10+
git --version       # Any recent version
claude --version    # Should show Claude CLI version

Step 1: Install Tevis Local​

# Install the Tevis Local package
pip install tevis-local

# Verify installation
tevis-local --version

Step 2: Start the Services​

# Start Tevis Local API (handles execution and knowledge base)
tevis-local serve

# This starts the local API on port 8082

In a separate terminal:

# Start Mission Control (Flight Director UI)
mc start

# This starts Mission Control on port 8083

Step 3: Open Mission Control​

Open your browser and navigate to:

http://localhost:8083

You should see the Mission Control dashboard.

Step 4: Create a Project​

  1. Click "New Project" in the Projects panel
  2. Enter project details:
    • Name: My First Project
    • Slug: my-first-project
    • Repository URL: (optional) Link to your git repo
  3. Click "Create Project"

Step 5: Create Your First Session​

  1. Click on your project to open it
  2. Click "New Session"
  3. Select a repository or use the default
  4. Your session is now active

Step 6: Start a Nanocycle​

  1. In your active session, click "New Nanocycle"
  2. Describe what you want to build:
Add a user authentication system with:
- Login page with email/password
- JWT token-based authentication
- Password reset flow
- Session management

  1. Tevis will generate a plan with:

    • Feature breakdown
    • Task list
    • Estimated scope

  2. Review the plan and click "Approve"

Step 7: Watch the Magic​

Once approved, Tevis begins execution:

  • AI agents spin up in isolated containers
  • Work progresses in parallel where possible
  • Real-time updates stream to Mission Control
  • Hold points pause for your review
NC-001 Status: IN_PROGRESS

Feature 1: Auth API       [████████░░] 80%
Feature 2: Login UI       [██████░░░░] 60%
Feature 3: Password Reset [████░░░░░░] 40%

Active TPUs: 3

Step 8: Review and Merge​

When execution completes:

  1. Review the generated code in Mission Control
  2. Check the diff view for each file
  3. Approve changes or request modifications
  4. Merge the completed nanocycle

What's Next?​

You've completed your first Tevis workflow. Here's what to explore next:

Quick Commands Reference​

# Start all services
tevis-local serve     # API on :8082
mc start              # UI on :8083

# Stop services
mc stop
tevis-local stop

# Check status
tevis-local status
mc status

# View logs
tevis-local logs
mc logs

Troubleshooting​

Docker not running​

# macOS
open -a Docker

# Linux
sudo systemctl start docker

Port already in use​

# Check what's using the port
lsof -i :8082
lsof -i :8083

# Kill the process or use a different port
tevis-local serve --port 8092
mc start --port 8093

Claude CLI not authenticated​

# Authenticate with Claude
claude login

# Copy credentials for Tevis
mkdir -p ~/.tevis
cp ~/.claude/.credentials.json ~/.tevis/claude_oauth_credentials.json
Need Help?

If you encounter issues, open an issue or reach out to the community.