# Add a Product
Source: https://docs.oppla.ai/analytics/add-website
Learn how to add Oppla analytics to your product in minutes
# Add a Product
Get started with Oppla analytics in just a few simple steps. Track user behavior, feature usage, and experiments with a single lightweight script.
## Quick Start
### Step 1: Get Your Product Credentials
1. Log into your [Oppla Dashboard](https://app.oppla.ai)
2. Navigate to **My Products** → **Add Product**
3. Click **Add Product**
4. Copy your `Product ID` and `Account ID`
### Step 2: Add the Tracking Script
Add this script to your product's `` section:
```html
```
**That's it!** Oppla will automatically start tracking:
* Page views
* User sessions
* Click events (with `data-oppla-event` attributes)
* Feature flag usage
* Experiment participation
## Advanced Features
### Track Custom Events
Track button clicks, form submissions, or any custom event:
```html expandable
```
### Identify Users
Track logged-in users across sessions:
```javascript expandable
// When user logs in
window.oppla.identify('user-123', {
email: 'user@example.com',
plan: 'premium',
company: 'Oppla AI'
});
```
### Feature Flags
Control feature visibility based on user segments:
```javascript expandable
// Check if a feature is enabled
if (window.oppla.getFeatureFlagStatus('new-dashboard')) {
// Show new dashboard
}
```
### A/B Testing
Run experiments to optimize your user experience:
```javascript expandable
// Get experiment variant
const variant = window.oppla.getExperimentStatus('homepage-cta');
if (variant === 'variant-a') {
// Show variant A
} else if (variant === 'variant-b') {
// Show variant B
}
```
## Configuration
### Configuration Options
Customize tracking behavior with optional attributes:
```javascript expandable
```
### JavaScript API
Once installed, these methods are available globally:
```javascript expandable
// Track custom events
window.oppla.track('event-name', {
property1: 'value1',
property2: 'value2'
});
// Identify users
window.oppla.identify('user-id', {
email: 'user@example.com',
customProperty: 'value'
});
// Feature flags
const isEnabled = window.oppla.getFeatureFlagStatus('feature-id');
// Experiments
const variant = window.oppla.getExperimentStatus('experiment-id');
// Automation triggers
window.oppla.trigger('trigger-name', 'automation-id', {
customData: 'value'
});
```
## Verification
### Testing the Installation
1. **Check the Console**
* Open browser Developer Tools (F12)
* Type `window.oppla` in the Console
* You should see the Oppla object with available methods
2. **Check Network Activity**
* Go to Network tab in Developer Tools
* Look for requests to `tracker.oppla.ai`
* Verify requests to `/api/send` are successful (200 status)
3. **Check Your Dashboard**
* Visit your [Oppla Dashboard](https://app.oppla.ai)
* Navigate to **Analytics** → **Real-time**
* You should see your current session
### Common Issues
* **`window.oppla is undefined`**: Ensure the script is in the `` section and has loaded
* **No data in dashboard**: Verify your Product ID and Account ID are correct
* **Blocked by ad blocker**: Ask users to whitelist `tracker.oppla.ai`
* **Not tracking localhost**: Localhost tracking is disabled by default for development
## Next Steps
Learn how to track custom events
Control feature rollouts and A/B tests
Create user segments for targeted features
Complete JavaScript SDK documentation
# Compare Metrics
Source: https://docs.oppla.ai/analytics/compare
Learn how to compare and analyze metrics in Oppla
# Compare Metrics
Learn how to compare and analyze metrics across different time periods, segments, and dimensions in Oppla.
## Basic Comparison
### Compare Time Periods
Compare metrics across different time periods:
```javascript
// Browser implementation
window.oppla.analytics.compare({
metric: 'page_views',
timeRange: {
current: {
start: '2024-03-01',
end: '2024-03-31'
},
previous: {
start: '2024-02-01',
end: '2024-02-29'
}
}
});
// Node.js implementation
oppla.analytics.compare({
metric: 'page_views',
timeRange: {
current: {
start: '2024-03-01',
end: '2024-03-31'
},
previous: {
start: '2024-02-01',
end: '2024-02-29'
}
}
});
```
### Compare Segments
Compare metrics between different user segments:
```javascript
// Browser implementation
window.oppla.analytics.compare({
metric: 'conversion_rate',
segments: {
current: ['premium-users'],
previous: ['free-users']
}
});
// Node.js implementation
oppla.analytics.compare({
metric: 'conversion_rate',
segments: {
current: ['premium-users'],
previous: ['free-users']
}
});
```
## Advanced Comparison
### Multiple Metrics
Compare multiple metrics simultaneously:
```javascript
// Browser implementation
window.oppla.analytics.compare({
metrics: ['page_views', 'bounce_rate', 'avg_session_duration'],
timeRange: {
current: {
start: '2024-03-01',
end: '2024-03-31'
},
previous: {
start: '2024-02-01',
end: '2024-02-29'
}
}
});
// Node.js implementation
oppla.analytics.compare({
metrics: ['page_views', 'bounce_rate', 'avg_session_duration'],
timeRange: {
current: {
start: '2024-03-01',
end: '2024-03-31'
},
previous: {
start: '2024-02-01',
end: '2024-02-29'
}
}
});
```
### Custom Dimensions
Compare metrics across custom dimensions:
```javascript
// Browser implementation
window.oppla.analytics.compare({
metric: 'revenue',
dimensions: {
current: {
device: 'mobile',
country: 'US'
},
previous: {
device: 'desktop',
country: 'US'
}
}
});
// Node.js implementation
oppla.analytics.compare({
metric: 'revenue',
dimensions: {
current: {
device: 'mobile',
country: 'US'
},
previous: {
device: 'desktop',
country: 'US'
}
}
});
```
## Visualization
### Basic Charts
Create basic comparison charts:
```javascript
// Browser implementation
window.oppla.analytics.visualize({
type: 'line',
metric: 'page_views',
timeRange: {
current: {
start: '2024-03-01',
end: '2024-03-31'
},
previous: {
start: '2024-02-01',
end: '2024-02-29'
}
}
});
// Node.js implementation
oppla.analytics.visualize({
type: 'line',
metric: 'page_views',
timeRange: {
current: {
start: '2024-03-01',
end: '2024-03-31'
},
previous: {
start: '2024-02-01',
end: '2024-02-29'
}
}
});
```
### Advanced Visualizations
Create advanced comparison visualizations:
```javascript
// Browser implementation
window.oppla.analytics.visualize({
type: 'bar',
metrics: ['page_views', 'bounce_rate'],
segments: {
current: ['premium-users'],
previous: ['free-users']
},
options: {
stacked: true,
showPercentage: true
}
});
// Node.js implementation
oppla.analytics.visualize({
type: 'bar',
metrics: ['page_views', 'bounce_rate'],
segments: {
current: ['premium-users'],
previous: ['free-users']
},
options: {
stacked: true,
showPercentage: true
}
});
```
## Best Practices
1. **Choose Relevant Metrics**: Select metrics that align with your goals
2. **Use Appropriate Time Ranges**: Ensure fair comparison periods
3. **Consider Context**: Account for external factors
4. **Validate Data**: Check for data quality issues
## Next Steps
Learn about event tracking
Organize your data for comparison
# Data Tags
Source: https://docs.oppla.ai/analytics/data-tags
Learn how to organize and segment your data using tags in Oppla
# Data Tags
Learn how to use data tags to organize, segment, and analyze your tracking data in Oppla.
## What are Data Tags?
Data tags are labels you can add to your events and users to:
* Organize related data
* Create segments
* Filter analytics
* Group similar events
## Adding Tags to Events
### Using Data Attributes
Add tags to your events using data attributes:
```html
```
### Using JavaScript
Add tags programmatically:
```javascript
// Browser implementation
window.oppla.track('Button Clicked', {
buttonId: 'signup-button',
tags: ['conversion', 'signup', 'homepage']
});
// With tag categories
window.oppla.track('Feature Used', {
feature: 'search',
tags: {
category: 'core-feature',
priority: 'high',
stage: 'beta'
}
});
// Node.js implementation
oppla.track('Button Clicked', {
buttonId: 'signup-button',
tags: ['conversion', 'signup', 'homepage']
});
```
## User Tags
### Adding User Tags
Tag users for segmentation:
```javascript
// Browser implementation
window.oppla.identify({
userId: 'user_123',
traits: {
name: 'John Doe',
tags: ['premium', 'active', 'beta-tester']
}
});
// Node.js implementation
oppla.identify({
userId: 'user_123',
traits: {
name: 'John Doe',
tags: ['premium', 'active', 'beta-tester']
}
});
```
### Updating User Tags
Update user tags over time:
```javascript
// Browser implementation
window.oppla.identify({
userId: 'user_123',
traits: {
tags: {
add: ['power-user'],
remove: ['beta-tester']
}
}
});
// Node.js implementation
oppla.identify({
userId: 'user_123',
traits: {
tags: {
add: ['power-user'],
remove: ['beta-tester']
}
}
});
```
## Tag Management
### Best Practices
1. **Be Consistent**: Use consistent tag names
2. **Be Specific**: Use descriptive tags
3. **Be Organized**: Group related tags
4. **Be Careful**: Don't use too many tags
### Common Tag Categories
* User type (e.g., 'free', 'premium')
* Feature usage (e.g., 'uses-search', 'uses-analytics')
* User stage (e.g., 'new', 'active', 'churned')
* Campaign (e.g., 'summer-sale', 'winter-promo')
## Using Tags in Analysis
### Filtering Data
Filter your analytics by tags:
```javascript
// Browser implementation
window.oppla.analytics.getEvents({
tags: ['conversion', 'signup']
});
window.oppla.analytics.getUsers({
tags: ['premium', 'active']
});
// Node.js implementation
oppla.analytics.getEvents({
tags: ['conversion', 'signup']
});
```
### Creating Segments
Create user segments based on tags:
```javascript
// Browser implementation
window.oppla.analytics.createSegment({
name: 'Power Users',
tags: ['premium', 'active', 'power-user']
});
// Node.js implementation
oppla.analytics.createSegment({
name: 'Power Users',
tags: ['premium', 'active', 'power-user']
});
```
## Next Steps
Compare tagged data over time
Server-side tag management
# Disable Local Tracking
Source: https://docs.oppla.ai/analytics/disable-local-tracking
Learn how to disable local tracking in Oppla
# Disable Local Tracking
Learn how to disable local tracking and ensure your tracking works in production.
## Configuration
### Disable Local Tracking
Disable local tracking in your configuration:
```javascript
window.oppla.config({
disableLocalTracking: true
});
```
### Environment-Specific Configuration
Configure different settings for development and production:
```javascript
// Development environment
if (process.env.NODE_ENV === 'development') {
window.oppla.config({
debug: true,
disableLocalTracking: false
});
} else {
// Production environment
window.oppla.config({
debug: false,
disableLocalTracking: true
});
}
```
## Best Practices
1. **Enable in Development**: Keep local tracking enabled during development
2. **Disable in Production**: Always disable local tracking in production
3. **Use Environment Variables**: Configure based on environment
4. **Test Thoroughly**: Verify tracking works in production
## Common Issues
### Local Tracking Still Active
* Check configuration
* Verify environment settings
* Clear browser cache
* Check for conflicting settings
### Tracking Not Working
* Verify configuration
* Check network requests
* Ensure proper initialization
* Check for console errors
## Next Steps
Learn about event tracking
Configure your tracking script
# Google Tag Manager
Source: https://docs.oppla.ai/analytics/google-tag-manager
Learn how to integrate Oppla with Google Tag Manager
# Google Tag Manager
Learn how to integrate Oppla with Google Tag Manager (GTM) for easier tracking implementation.
## Setup
### 1. Create a Custom HTML Tag
In Google Tag Manager:
1. Go to Tags > New
2. Click on Tag Configuration
3. Select "Custom HTML"
4. Add the Oppla tracking code:
```html
```
### 2. Configure Triggers
Set up triggers for when the tag should fire:
* **All Pages**: For basic tracking
* **Specific Pages**: For targeted tracking
* **User Interactions**: For event tracking
## Event Tracking
### Track Page Views
```javascript
// In GTM Custom HTML tag
window.oppla.track('Page Viewed', {
path: window.location.pathname,
title: document.title,
referrer: document.referrer
});
```
### Track User Interactions
```javascript
// In GTM Custom HTML tag
window.oppla.track('Button Clicked', {
buttonId: '{{Click ID}}',
buttonText: '{{Click Text}}',
page: '{{Page Path}}'
});
```
## Data Layer Integration
### Push to Data Layer
```javascript
// In your website code
window.dataLayer.push({
'event': 'opplaEvent',
'eventName': 'Purchase Completed',
'eventProperties': {
'orderId': '12345',
'amount': 99.99
}
});
```
### Listen for Data Layer Events
```javascript
// In GTM Custom HTML tag
window.dataLayer.push = function(e) {
if (e.event === 'opplaEvent') {
window.oppla.track(e.eventName, e.eventProperties);
}
};
```
## User Identification
### Identify Users
```javascript
// In GTM Custom HTML tag
window.oppla.identify({
userId: '{{User ID}}',
traits: {
name: '{{User Name}}',
email: '{{User Email}}',
plan: '{{User Plan}}'
}
});
```
## Best Practices
1. **Use Variables**: Store Oppla project ID in GTM variables
2. **Test in Preview**: Always test in GTM preview mode
3. **Use Data Layer**: Push events to data layer for consistency
4. **Monitor Performance**: Check tag loading impact
## Common Issues
### Tag Not Loading
* Check GTM container code is properly installed
* Verify trigger conditions
* Check for JavaScript errors
### Events Not Tracking
* Verify data layer pushes
* Check event names and properties
* Ensure proper timing of tag loading
## Next Steps
Learn more about event tracking
Organize your GTM events
# Node Client
Source: https://docs.oppla.ai/analytics/node-client
Learn how to use Oppla's Node.js client for server-side tracking
# Node Client
Learn how to use Oppla's Node.js client for server-side tracking and analytics.
## Installation
Install the Oppla Node.js client:
```bash
npm install @oppla/node
# or
yarn add @oppla/node
```
## Basic Usage
### Initialize the Client
```javascript
const Oppla = require('@oppla/node');
const oppla = new Oppla({
projectId: 'YOUR_PROJECT_ID',
apiKey: 'YOUR_API_KEY'
});
```
### Track Events
```javascript
// Track a simple event
await oppla.track({
event: 'Order Completed',
userId: 'user_123',
properties: {
orderId: 'order_123',
amount: 99.99
}
});
// Track with additional context
await oppla.track({
event: 'Payment Processed',
userId: 'user_123',
timestamp: new Date(),
context: {
ip: '192.168.1.1',
userAgent: 'Mozilla/5.0...'
},
properties: {
paymentId: 'pay_123',
amount: 99.99,
currency: 'USD'
}
});
```
## User Management
### Identify Users
```javascript
await oppla.identify({
userId: 'user_123',
traits: {
name: 'John Doe',
email: 'john@example.com',
plan: 'premium',
signupDate: new Date()
}
});
```
### Update User Properties
```javascript
await oppla.identify({
userId: 'user_123',
traits: {
lastLogin: new Date(),
loginCount: 5
}
});
```
## Batch Operations
### Track Multiple Events
```javascript
await oppla.batch([
{
event: 'Page Viewed',
userId: 'user_123',
properties: { path: '/products' }
},
{
event: 'Product Viewed',
userId: 'user_123',
properties: { productId: 'prod_123' }
}
]);
```
### Identify Multiple Users
```javascript
await oppla.batch([
{
identify: {
userId: 'user_123',
traits: { name: 'John Doe' }
}
},
{
identify: {
userId: 'user_456',
traits: { name: 'Jane Smith' }
}
}
]);
```
## Error Handling
```javascript
try {
await oppla.track({
event: 'Order Completed',
userId: 'user_123'
});
} catch (error) {
console.error('Failed to track event:', error);
// Handle specific error types
if (error.code === 'RATE_LIMIT') {
// Implement retry logic
}
}
```
## Best Practices
1. **Use Environment Variables**: Store API keys securely
2. **Implement Retry Logic**: Handle rate limits and network issues
3. **Batch When Possible**: Reduce API calls
4. **Validate Data**: Ensure required fields are present
## Next Steps
Integrate with Google Tag Manager
Organize your server-side data
# Script
Source: https://docs.oppla.ai/analytics/script
Learn how to add and configure the Oppla tracking script
# Script
Learn how to add and configure the Oppla tracking script in your application.
## Installation
### Basic Installation
Add the Oppla tracking script to your website's `` section:
```html
```
### Async Loading
For better performance, load the script asynchronously:
```html
```
## Configuration
### Basic Configuration
Configure basic tracking settings:
```javascript
window.oppla.config({
trackPageViews: true,
trackClicks: true,
trackForms: true,
debug: false
});
```
### Advanced Configuration
Add advanced tracking options:
```javascript
window.oppla.config({
// Enable automatic tracking
autoTrack: {
pageViews: true,
clicks: true,
forms: true,
scroll: true
},
// Configure session settings
session: {
timeout: 30, // minutes
extendOnActivity: true
},
// Set up custom domains
domains: ['yourdomain.com', 'app.yourdomain.com'],
// Configure data collection
dataCollection: {
ipAddress: false,
userAgent: true,
referrer: true
}
});
```
## Event Tracking
### Track Events
Track events using the script:
```javascript
// Track a simple event
window.oppla.track('Button Clicked', {
buttonId: 'signup-button',
page: 'homepage'
});
// Track with additional context
window.oppla.track('Purchase Completed', {
orderId: '12345',
amount: 99.99,
currency: 'USD',
items: ['product1', 'product2']
});
```
### User Identification
Identify users:
```javascript
window.oppla.identify({
userId: 'user_123',
traits: {
name: 'John Doe',
email: 'john@example.com',
plan: 'premium'
}
});
```
## Data Attributes
### Track Events with Data Attributes
Add data attributes to your HTML elements:
```html
```
## Best Practices
1. **Load Early**: Add the script as early as possible in the ``
2. **Use Async**: Load the script asynchronously for better performance
3. **Configure Properly**: Set up tracking options based on your needs
4. **Test Thoroughly**: Verify tracking in development environment
## Common Issues
### Script Not Loading
* Check network connectivity
* Verify script URL is correct
* Check for JavaScript errors
* Ensure proper script placement
### Events Not Tracking
* Verify initialization
* Check event names and properties
* Ensure proper timing of script loading
* Check for console errors
## Next Steps
Learn about event tracking
Organize your tracking data
# Sessions & Cross-Device Tracking
Source: https://docs.oppla.ai/analytics/sessions
Track user sessions across devices, platforms, and products with unified analytics
# Sessions & Cross-Device Tracking
Oppla provides advanced session tracking with cross-device identification, session stitching, and unified user journey analytics. Track users seamlessly as they move between devices, browsers, and products.
## Advanced Session Capabilities
Track users across mobile, desktop, and tablet seamlessly
Automatically connect anonymous and identified sessions
Track sessions across multiple products and platforms
Automatic location tracking via ipapi.co integration
## What are Sessions?
Sessions in Oppla represent continuous periods of user activity with advanced features:
* **Cross-Device Journey**: Track users across all their devices
* **Unified Identity**: Connect anonymous and authenticated sessions
* **Real-Time Tracking**: Monitor active sessions as they happen
* **Smart Attribution**: Understand true conversion paths across devices
* **Session Replay**: Reconstruct user journeys across touchpoints
## Cross-Device User Identification
### Identifying Users Across Devices
Connect user sessions across all devices:
```javascript
// When user logs in on any device
window.oppla.identify('user_123', {
email: 'user@example.com',
name: 'John Doe',
plan: 'premium',
// Device-specific attributes
device: {
type: getDeviceType(), // 'mobile', 'desktop', 'tablet'
id: getDeviceId(),
platform: navigator.platform
}
});
// This automatically:
// 1. Links current session to user_123
// 2. Connects all past anonymous sessions
// 3. Enables cross-device tracking
// 4. Enriches with IP geolocation
```
### Session Stitching
Oppla automatically stitches sessions when users authenticate:
```javascript
// Anonymous session (before login)
window.oppla.track('product_viewed', {
productId: 'prod_123',
sessionId: 'anon_session_456' // Automatic
});
// User logs in
window.oppla.identify('user_123', {
email: 'user@example.com'
});
// Previous anonymous events are now linked to user_123
// Continued tracking (after login)
window.oppla.track('product_purchased', {
productId: 'prod_123',
sessionId: 'auth_session_789' // Automatic
});
```
## Enhanced Session Events
Oppla tracks comprehensive session data with cross-device context:
```javascript
// Session Started (with enrichment)
{
event: 'session_started',
properties: {
timestamp: '2024-03-20T10:00:00Z',
sessionId: 'sess_abc123',
userId: 'user_123', // If identified
deviceId: 'device_456',
referrer: 'https://google.com',
userAgent: 'Mozilla/5.0...',
// IP Geolocation (automatic)
location: {
ip: '192.168.1.1',
country: 'United States',
region: 'California',
city: 'San Francisco',
lat: 37.7749,
lon: -122.4194
},
// Device context
device: {
type: 'mobile',
os: 'iOS',
browser: 'Safari',
screenResolution: '390x844'
},
// Cross-device context
crossDevice: {
isReturning: true,
lastDevice: 'desktop',
totalDevices: 3
}
}
}
// Cross-Device Session Link
{
event: 'session_linked',
properties: {
currentSession: 'sess_mobile_123',
linkedSessions: ['sess_desktop_456', 'sess_tablet_789'],
userId: 'user_123',
linkMethod: 'authentication' // or 'fingerprint', 'email_link'
}
}
// Session Handoff (device switch)
{
event: 'session_handoff',
properties: {
fromDevice: 'mobile',
toDevice: 'desktop',
handoffMethod: 'qr_code', // or 'email_link', 'deep_link'
continuityScore: 0.95 // Confidence in session continuity
}
}
```
## Cross-Device Tracking Implementation
### Mobile App Tracking
Track mobile sessions with device context:
```javascript
// React Native
import OPPLATracker from '@oppla/react-native';
OPPLATracker.initialize({
productId: 'prod_mobile_app',
enableCrossDevice: true
});
// Track with device context
OPPLATracker.track('app_opened', {
deviceId: getDeviceId(),
platform: Platform.OS,
appVersion: getVersion()
});
// Link to web session
OPPLATracker.linkWebSession({
webSessionId: 'sess_web_123',
method: 'deep_link'
});
```
### Desktop Tracking
Desktop session with cross-device awareness:
```javascript
// Desktop web app
window.oppla.track('session_started', {
device: 'desktop',
screenResolution: `${screen.width}x${screen.height}`,
// Check for mobile sessions
checkCrossDevice: true
});
// Generate QR code for mobile continuation
const qrData = window.oppla.generateSessionHandoff({
targetDevice: 'mobile',
expiresIn: 300 // 5 minutes
});
```
### Session Continuity
Maintain session continuity across devices:
```javascript
// Save session for cross-device access
window.oppla.saveSessionForDevice({
userId: 'user_123',
sessionData: {
cart: getCartItems(),
preferences: getUserPreferences(),
progress: getCurrentProgress()
}
});
// Restore on another device
window.oppla.restoreSession({
userId: 'user_123',
merge: true // Merge with current session
});
```
## Advanced Session Analytics
### Cross-Device Funnels
Track conversion funnels across devices:
```javascript
// Track funnel step with device context
window.oppla.track('funnel_step', {
funnel: 'purchase_flow',
step: 2,
stepName: 'add_to_cart',
device: getCurrentDevice(),
// Previous steps on other devices
crossDeviceJourney: [
{ step: 1, device: 'mobile', timestamp: '2024-01-01T10:00:00Z' }
]
});
// Analyze cross-device conversion
const funnelAnalysis = await oppla.analyzeFunnel({
funnel: 'purchase_flow',
includeCrossDevice: true,
attribution: 'last_touch' // or 'linear', 'time_decay'
});
```
### Device Switching Patterns
Analyze how users switch between devices:
```javascript
// Track device switch
window.oppla.track('device_switched', {
from: getPreviousDevice(),
to: getCurrentDevice(),
reason: 'user_initiated', // or 'session_timeout', 'app_switch'
sessionContinuity: true,
timeBetweenDevices: 120 // seconds
});
// Common patterns
window.oppla.track('device_pattern', {
pattern: 'research_mobile_purchase_desktop',
devices: ['mobile', 'desktop'],
totalTime: 3600, // 1 hour
conversions: 1
});
```
### Multi-Product Sessions
Track sessions across multiple products:
```javascript
// Product A (Web App)
window.oppla.track('cross_product_session', {
currentProduct: 'web_app',
userId: 'user_123',
sessionFlow: ['landing_page', 'signup', 'dashboard']
});
// Product B (Mobile App)
OPPLATracker.track('cross_product_session', {
currentProduct: 'mobile_app',
userId: 'user_123',
previousProduct: 'web_app',
continuationMethod: 'push_notification'
});
// Product C (API)
oppla.track('cross_product_session', {
currentProduct: 'api',
userId: 'user_123',
apiClient: 'mobile_app',
sessionChain: ['web_app', 'mobile_app', 'api']
});
```
## Session Intelligence Dashboard
### Cross-Device Analytics
View comprehensive cross-device metrics:
1. **Device Distribution**: See how users split across devices
2. **Journey Maps**: Visualize cross-device user paths
3. **Attribution Models**: Understand conversion attribution
4. **Session Timeline**: View unified session history
5. **Device Cohorts**: Analyze behavior by device combinations
### Real-Time Session Monitoring
Monitor active sessions across all devices:
```javascript
// Real-time session feed
const activeSessions = await oppla.getActiveSessions({
includeCrossDevice: true,
groupByUser: true
});
// Returns
{
"user_123": {
"devices": ["mobile", "desktop"],
"sessions": [
{
"device": "mobile",
"started": "2024-01-01T10:00:00Z",
"location": "San Francisco, CA",
"active": true
},
{
"device": "desktop",
"started": "2024-01-01T10:05:00Z",
"location": "San Francisco, CA",
"active": true
}
],
"isMultiDevice": true
}
}
```
## Best Practices
### 1. User Identification Strategy
```javascript
// Identify users consistently across devices
const identifyUser = (userId, userData) => {
// Always include email for cross-device matching
window.oppla.identify(userId, {
email: userData.email, // Key for cross-device
...userData,
identifiedAt: new Date().toISOString(),
identificationMethod: getIdentificationMethod()
});
};
```
### 2. Handle Device Transitions
```javascript
// Smooth device handoff
const initiateDeviceHandoff = async () => {
const handoffToken = await window.oppla.createHandoffToken({
currentSession: getSessionId(),
expiresIn: 300,
targetDevices: ['mobile', 'tablet']
});
// Display QR code or send email
displayHandoffQR(handoffToken);
};
```
### 3. Privacy Considerations
```javascript
// Respect user privacy preferences
window.oppla.configure({
crossDeviceTracking: getUserConsent('cross_device'),
ipGeolocation: getUserConsent('location'),
sessionRecording: getUserConsent('recording')
});
```
### 4. Session Quality Metrics
Monitor cross-device session quality:
* **Multi-Device Users**: Percentage using multiple devices
* **Device Switching Rate**: How often users switch
* **Cross-Device Conversion**: Conversion rates for multi-device users
* **Session Continuity**: Success rate of session handoffs
* **Device Attribution**: Which devices drive conversions
## Troubleshooting
### Common Issues
| Issue | Solution |
| -------------------------- | ------------------------------------------------------- |
| **Sessions not linking** | Ensure users are identified with same ID across devices |
| **Missing device context** | Check that device detection is enabled |
| **Incorrect attribution** | Verify attribution model settings |
| **Session timeout** | Adjust session timeout settings for your use case |
### Debug Mode
```javascript
// Enable cross-device debug mode
localStorage.setItem('oppla.crossdevice.debug', 'true');
// Log all session events
window.oppla.onSessionEvent = (event) => {
console.log('[Oppla Session]', event);
};
```
## Next Steps
Monitor sessions in real-time
Track across multiple products
Analyze cross-device journeys
Configure privacy and consent
# Track Events
Source: https://docs.oppla.ai/analytics/track-events
Track user interactions, feature flags, experiments, and custom events with Oppla
# Track Events
Oppla provides comprehensive event tracking capabilities including standard events, feature flag interactions, experiment conversions, and automation triggers. All events are automatically enriched with user context, IP geolocation, and session data.
## Using Data Attributes
Track events by adding data attributes to your HTML elements:
```html
```
## Using JavaScript
Track events programmatically using the Oppla object:
```javascript
// Browser implementation
window.oppla.track('Button Clicked', {
buttonId: 'signup-button',
page: 'homepage'
});
// Node.js implementation
oppla.track('Button Clicked', {
buttonId: 'signup-button',
page: 'homepage'
});
```
## Event Properties
Add detailed properties to your events:
```javascript
// Browser implementation
window.oppla.track('Purchase Completed', {
// Order details
orderId: '12345',
amount: 99.99,
currency: 'USD',
items: ['product1', 'product2'],
// User context
userId: 'user_123',
userType: 'premium',
// Custom properties
source: 'homepage',
campaign: 'summer_sale'
});
// Node.js implementation
oppla.track('Purchase Completed', {
// Same properties as above
});
```
## Standard Event Types
### Page Views
Track page views with automatic enrichment:
```javascript
// Automatic tracking (enabled by default)
// Tracks: URL, referrer, title, session info, IP location
// Manual tracking with custom properties
window.oppla.track('Page Viewed', {
path: '/products',
title: 'Products Page',
referrer: document.referrer,
category: 'product_catalog',
searchQuery: 'premium plans'
});
```
### User Actions
Track user interactions:
```html
View Pricing
```
### E-commerce Events
Track e-commerce activities:
```javascript
// Browser implementation
window.oppla.track('Product Viewed', {
productId: 'prod_123',
name: 'Premium Plan',
price: 99.99
});
window.oppla.track('Added to Cart', {
productId: 'prod_123',
quantity: 1,
price: 99.99
});
window.oppla.track('Checkout Started', {
orderId: 'order_123',
total: 99.99,
items: ['prod_123']
});
// Node.js implementation
oppla.track('Product Viewed', {
productId: 'prod_123',
name: 'Premium Plan',
price: 99.99
});
```
## Feature Flag Events
Track feature flag exposures and interactions:
```javascript
// Automatic tracking when checking flag status
const isEnabled = window.oppla.getFeatureFlagStatus('new-feature');
// Automatically tracks: { event: 'new-feature', flg_name: 'new-feature', flg_value: true }
// Track feature interaction
if (isEnabled) {
window.oppla.track('feature-interaction', {
feature: 'new-feature',
action: 'clicked',
variant: 'enabled',
interactionCount: 1
});
}
// Track feature adoption
window.oppla.track('feature-adopted', {
feature: 'ai-assistant',
timeToAdopt: 120, // seconds
onboardingStep: 'completed'
});
```
## Experiment Events
Track experiment exposures and conversions:
```javascript
// Get experiment variant (automatically tracks exposure)
const variant = window.oppla.getExperimentStatus('pricing-test');
// Track conversion event
window.oppla.track('experiment-conversion', {
experiment: 'pricing-test',
variant: variant,
action: 'purchase',
revenue: 99.99
});
// Track experiment interactions
window.oppla.track('experiment-interaction', {
experiment: 'homepage-test',
variant: variant,
element: 'hero-cta',
timeOnPage: 45 // seconds
});
// Track guardrail metrics
window.oppla.track('experiment-guardrail', {
experiment: 'performance-test',
variant: variant,
metric: 'page-load-time',
value: 1.2 // seconds
});
```
## Automation Trigger Events
Trigger automated workflows based on user behavior:
```javascript
// Trigger cart abandonment automation
window.oppla.trigger('cart-abandoned', 'auto_recovery', {
cartValue: 299.99,
items: ['product_1', 'product_2'],
userSegment: 'high_value',
abandonedAt: new Date().toISOString()
});
// Trigger churn prevention
window.oppla.trigger('churn-risk', 'auto_retention', {
userId: 'user_123',
lastLoginDaysAgo: 14,
usageDecline: 60, // percentage
subscriptionEndDate: '2024-03-01'
});
// Trigger onboarding assistance
window.oppla.trigger('onboarding-stuck', 'auto_help', {
step: 'profile_setup',
timeOnStep: 300, // seconds
attemptsCount: 3
});
```
## Cross-Product Tracking
Track users across multiple products:
```javascript
// Track cross-product navigation
window.oppla.track('product-switched', {
fromProduct: 'web_app',
toProduct: 'mobile_app',
method: 'deep_link',
userId: 'user_123'
});
// Track feature usage across products
window.oppla.track('cross-product-feature', {
feature: 'advanced_search',
products: ['web', 'mobile', 'api'],
primaryProduct: 'web'
});
```
## User Identification Events
Track user identity and properties:
```javascript
// Identify user (enriches all subsequent events)
window.oppla.identify('user_123', {
email: 'user@example.com',
name: 'John Doe',
plan: 'premium',
company: 'Acme Corp',
signupDate: '2024-01-01',
location: 'auto' // Uses IP geolocation
});
// Track user property changes
window.oppla.track('user-upgraded', {
previousPlan: 'free',
newPlan: 'premium',
upgradeReason: 'needed_more_features'
});
```
## Performance Tracking
Monitor application performance:
```javascript
// Track page load performance
window.addEventListener('load', () => {
const perfData = performance.getEntriesByType('navigation')[0];
window.oppla.track('page-performance', {
url: window.location.href,
loadTime: perfData.loadEventEnd - perfData.fetchStart,
domInteractive: perfData.domInteractive,
firstPaint: perfData.responseEnd - perfData.fetchStart
});
});
// Track API performance
const startTime = performance.now();
fetch('/api/data')
.then(response => {
const duration = performance.now() - startTime;
window.oppla.track('api-performance', {
endpoint: '/api/data',
duration: duration,
status: response.status,
success: response.ok
});
});
```
## Event Batching
Oppla automatically batches events for performance:
```javascript
// Events are automatically batched and sent every 5 seconds
// or when 10 events accumulate, whichever comes first
// Force immediate send (useful for critical events)
window.oppla.track('critical-event', {
type: 'payment_completed',
amount: 999.99
}, { immediate: true });
```
## Important Notes
1. **Automatic Enrichment**:
* All events include timestamp, session ID, and user context
* IP geolocation is automatically added via ipapi.co
* Device and browser information is captured
2. **Data Types**:
* JavaScript method supports all data types
* HTML attributes are converted to strings
* Nested objects and arrays are supported
3. **Privacy**:
* Never include passwords or sensitive data
* PII should be hashed when necessary
* Respect user privacy preferences
## Best Practices
### Naming Conventions
```javascript
// Use consistent naming patterns
window.oppla.track('product.viewed', { id: '123' }); // Good
window.oppla.track('product.added_to_cart', { id: '123' }); // Good
window.oppla.track('checkout.started', { total: 99.99 }); // Good
```
### Event Properties
```javascript
// Include comprehensive context
window.oppla.track('button.clicked', {
// What
buttonId: 'cta-hero',
buttonText: 'Start Free Trial',
// Where
page: '/homepage',
section: 'hero',
// When
sessionDuration: 45,
isFirstVisit: false,
// Who
userSegment: 'trial',
accountType: 'business'
});
```
### Error Tracking
```javascript
// Track errors with context
window.addEventListener('error', (e) => {
window.oppla.track('error.occurred', {
message: e.message,
source: e.filename,
line: e.lineno,
column: e.colno,
stack: e.error?.stack,
url: window.location.href
});
});
```
## Next Steps
Control features and track adoption
Run A/B tests and track conversions
Automate workflows based on events
Understand session tracking
# Track Outbound Links
Source: https://docs.oppla.ai/analytics/track-outbound-clicks
Learn how to track outbound link clicks in Oppla
# Track Outbound Links in Oppla
When a user clicks on a link to an external site, this event is normally not captured because the user is leaving the site where Oppla runs. However, you can use events to track this behavior.
### Using Data Attributes
To track outbound links, add data attributes to the anchor tag containing the external link. When the tag is clicked, the event will be triggered. For example:
```html
External link
```
This sends an event named **outbound-link-click** with the value of `url` set to the external URL.
### Automating Event Attributes
If you don't want to manually update all your anchor tags, use the following script to automatically add the event attributes to all outbound tags. Place this script at the bottom of your HTML body:
```html
```
### Verifying Outbound Link Tracking
After implementing the above, verify the tracking by clicking on an outbound link and checking the **Events** section in your Oppla dashboard.
💡 For further guidance, visit our Help Center or reach out to support.
# Tracker
Source: https://docs.oppla.ai/analytics/tracker
Learn how to use Oppla's tracking functionality
# Tracker
Learn how to use Oppla's tracking functionality to monitor user behavior and collect analytics data.
## Basic Tracking
### Initialize Tracker
Initialize the tracker with your project ID:
```javascript
window.oppla.init('YOUR_PROJECT_ID');
```
### Track Page Views
Track page views automatically or manually:
```javascript
// Automatic tracking (configured in init)
window.oppla.init({
projectId: 'YOUR_PROJECT_ID',
trackPageViews: true
});
// Manual tracking
window.oppla.track('Page Viewed', {
path: window.location.pathname,
title: document.title,
referrer: document.referrer
});
```
### Track User Actions
Track user interactions:
```javascript
// Track button clicks
window.oppla.track('Button Clicked', {
buttonId: 'signup-button',
buttonText: 'Sign Up',
page: 'homepage'
});
// Track form submissions
window.oppla.track('Form Submitted', {
formId: 'contact-form',
formType: 'contact',
success: true
});
// Track link clicks
window.oppla.track('Link Clicked', {
linkId: 'pricing-link',
linkText: 'View Pricing',
destination: '/pricing'
});
```
### Track Outbound Clicks
Track clicks on external links:
```javascript
// Configure outbound click tracking
window.oppla.config({
trackOutboundClicks: true,
outboundDomains: ['example.com', 'external-site.com']
});
// Track outbound clicks manually
window.oppla.track('Outbound Click', {
linkId: 'external-link',
linkText: 'Visit External Site',
destination: 'https://example.com',
domain: 'example.com'
});
```
## Advanced Tracking
### Track Custom Events
Track custom events with detailed properties:
```javascript
// Track feature usage
window.oppla.track('Feature Used', {
feature: 'search',
query: 'example search',
results: 42,
filters: ['price', 'category']
});
// Track e-commerce events
window.oppla.track('Purchase Completed', {
orderId: '12345',
amount: 99.99,
currency: 'USD',
items: [
{
id: 'prod_123',
name: 'Product 1',
price: 49.99,
quantity: 1
},
{
id: 'prod_456',
name: 'Product 2',
price: 50.00,
quantity: 1
}
]
});
```
### Track User Properties
Track user properties and traits:
```javascript
// Identify user
window.oppla.identify({
userId: 'user_123',
traits: {
name: 'John Doe',
email: 'john@example.com',
plan: 'premium',
signupDate: '2024-01-01'
}
});
// Update user properties
window.oppla.identify({
userId: 'user_123',
traits: {
lastLogin: new Date(),
loginCount: 5,
preferences: {
theme: 'dark',
notifications: true
}
}
});
```
## Data Attributes
### Track with Data Attributes
Use data attributes for automatic tracking:
```html
View Pricing
Visit External Site
```
## Best Practices
1. **Be Consistent**: Use consistent event names and properties
2. **Be Specific**: Include relevant context in event properties
3. **Be Organized**: Group related events with similar naming patterns
4. **Be Careful**: Don't include sensitive user data in events
## Common Issues
### Events Not Tracking
* Verify initialization
* Check event names and properties
* Ensure proper timing of tracking calls
* Check for console errors
### Data Not Appearing
* Check network requests
* Verify project ID
* Check for data validation errors
* Ensure proper event structure
### Outbound Clicks Not Tracking
* Verify outbound click configuration
* Check domain list
* Ensure proper link attributes
* Check for JavaScript errors
## Next Steps
Learn about session tracking
Organize your tracking data
# FreeBSD
Source: https://docs.oppla.ai/development/freebsd
Build, install, and run Oppla on FreeBSD — guidance for contributors and advanced users
This page is a practical stub with guidance for running Oppla on FreeBSD systems. FreeBSD is not a primary target for packaged releases for many desktop-first projects, so this document focuses on recommended approaches: using the ports collection or packages where possible, running in Linux compatibility layers, containers or VMs for runtimes that are Linux-first (local model runtimes), and building from source for contributors.
Status
* Target: Provide workable paths to run Oppla and its AI features on FreeBSD.
* Current: FreeBSD support is community-driven. Expect more manual steps than Linux/macOS.
* Recommended for most users: run Oppla inside a Linux VM/container on FreeBSD (bhyve, Docker via Linux emulation) for best compatibility with model runtimes and GPU acceleration.
Supported FreeBSD releases
* Aim for FreeBSD 13.x and 14.x (release and stable branches). Adjust for your environment and kernel modules.
* Verify availability of required packages and drivers for your target release.
Quick overview (recommended options)
1. Easiest (recommended): Run Oppla in a Linux VM (bhyve / bhyveload + cloud image) or a container runtime that can run Linux images on FreeBSD.
2. Intermediate: Build Oppla from source on FreeBSD when dependencies are available as packages/ports.
3. Advanced: Try native run with the FreeBSD Linux compatibility layer for specific Linux-only runtimes — expect limitations and additional troubleshooting.
Prerequisites & tooling
* pkg: FreeBSD package manager
* ports collection (optional): for packages not available as prebuilt binaries
* git: source control
* build tools: cmake, make, gmake, gcc/clang, pkgconf
* language runtimes: Python, Node.js, Rust toolchains — depending on project build system
* virtualization/container: bhyve + cloud images, or Linux container support via sysutils/docker (limited), or use iocage/jails for isolation
* GPU drivers (optional, advanced): vendor drivers for NVIDIA/AMD; additional setup often required
Install common developer tools
Example (as root or using sudo):
pkg update
pkg install git cmake pkgconf python node rust npm gmake
If a package is not available, use the ports collection:
portsnap fetch extract
cd /usr/ports/devel/``
make install clean
Build-from-source (high-level)
Note: exact build steps depend on Oppla repository build system (Electron/Node, Rust, or mixed). The following is a generic guide.
1. Clone the repository:
git clone [https://github.com/oppla/oppla.git](https://github.com/oppla/oppla.git)
cd oppla
2. Read the repository README for platform-specific notes. Install any prerequisites listed there.
3. Install Node/npm dependencies (if applicable):
npm install
# or
yarn install
4. Build native components:
# Example for a generic build that uses a build script
npm run build
5. Package / run:
npm start
# or run built binary from provided output directory
If the project uses Rust for native backends, ensure rustup and cargo are installed:
pkg install rust
rustup default stable
cargo build --release
Notes for package authors and contributors
* Provide a Makefile or simple build script that documents FreeBSD-specific prerequisites.
* Prefer portable build tools: CMake + Ninja or cross-platform Node build scripts.
* Include a minimal list of pkg packages required to build on FreeBSD.
Local AI model runtimes & GPU support on FreeBSD
* Many popular local model runtimes (Ollama, llama.cpp wrappers, LM Studio) are Linux-first.
* FreeBSD has limited support for GPU toolchains (CUDA/ROCm) and fewer prebuilt inference runtimes.
* Recommended approaches:
* Run local model runtimes in a Linux VM (bhyve) or container to use vendor drivers and established runtimes.
* For CPU-only evaluation, llama.cpp and other C/C++ based runtimes may be buildable on FreeBSD — expect to compile dependencies (BLAS, SSE/AVX flags) and tune build flags.
* NVIDIA: FreeBSD supports the proprietary NVIDIA driver in some versions. GPU-accelerated inference on FreeBSD is an advanced path and may require Linux compatibility layers or running models in a Linux VM with GPU passthrough.
* AMD ROCm: Generally not available on FreeBSD.
* If your organization requires on-host local models, prefer a Linux VM for reliability.
Linux compatibility & containers
* FreeBSD provides a Linux compatibility layer (linuxulator) for running some Linux binaries — but effectiveness varies by binary and kernel.
* For more robust compatibility, use a Linux VM via bhyve or a small VM image (Ubuntu) to run Oppla or local model servers.
* Docker support on FreeBSD is limited. Use VM-based workflows for containerized runtimes.
Security & sandboxing
* Run unfamiliar builds in isolated environments (jails or VMs).
* For local model runtimes and agent tools, prefer running them under a dedicated user or container and restrict filesystem/network access.
* Use FreeBSD jails (iocage or ezjail) for lightweight isolation of tool runtimes when full VM is overkill.
Network & firewall considerations
* Ensure outbound HTTPS is allowed for cloud AI providers if you choose cloud models.
* For local-only or air-gapped setups, configure `ai.privacy.mode` to `local_only` in Oppla settings and host model runtimes in the private network or VM accessible only to authorized hosts.
Troubleshooting
* Build issues:
* Missing libraries: install corresponding -devel ports or packages.
* Incorrect toolchain: ensure CFLAGS and linker flags are appropriate for FreeBSD (some projects expect glibc-specific behavior).
* Runtime issues:
* GUI issues: ensure a compatible X11/Wayland/desktop environment and runtime dependencies (GTK/Qt) are installed.
* Missing binary compat: if a bundled Linux binary fails, prefer running in a Linux VM.
* Local model connectivity:
* Check that the local model server is reachable from the host (curl [http://localhost:PORT/health](http://localhost:PORT/health)).
* For VMs, verify port forwarding and network interfaces (bhyve bridged networking or host-only with forwarded ports).
CI & packaging recommendations
* Add a FreeBSD build job in CI to smoke-test compilation steps (ports or packages).
* Provide a simple packaging recipe (pkg or ports) for easier installs by users.
* When distributing release artifacts, provide checksums and signatures; document verification steps.
Developer & contribution checklist
* Add a README section: FreeBSD notes, required pkg/packages, known limitations.
* Provide scripts to install build deps via pkg or ports.
* Maintain a minimal test that runs headless features (CLI) so FreeBSD CI can exercise core functionality.
* Document recommended approach for local models (VM vs native) for contributors.
Related documentation
* System Requirements: ../ide/general/system-requirements.mdx
* Linux guide (for VM-based approach): ../ide/general/linux.mdx
* AI Configuration & Privacy: ../ide/ai/configuration.mdx and ../ide/ai/privacy-and-security.mdx
* Development guide: ../development.mdx
Next steps for docs team (suggested)
* Add concrete build/test commands specific to this repo (once maintainers provide build steps).
* Add example bhyve VM image or a small script to create a Linux VM preconfigured for Oppla and local models.
* Track known-good package versions and document any third-party runtimes that are known to work on FreeBSD.
If you'd like, I can:
* Draft a step-by-step FreeBSD port/PKG recipe based on the repository build system.
* Produce a bhyve VM provisioning script (cloud-init or Packer) that sets up a Linux environment optimized for running Oppla and local models.
* Add a small CI job example that runs basic smoke tests on FreeBSD in your CI provider.
# Windows
Source: https://docs.oppla.ai/development/windows
Windows-specific build, install, and troubleshooting notes for Oppla (preview)
Note: Native Windows support for Oppla is under active development. This page is a practical stub with guidance for developers and advanced users who want to run Oppla on Windows (native build or via WSL). It includes prerequisites, build-from-source tips, GPU/AI runtime notes, and troubleshooting steps. We'll expand this with signed installer instructions, CI recipes, and full troubleshooting flows.
Status
* Goal: Full native Windows 11 support with GPU acceleration and CLI integration.
* Current: Preview and build-from-source guidance available. Native packaged installers will follow in future releases.
* Workarounds: WSL2 and containerized builds are recommended for earlier/experimental Windows setups.
Quick overview (recommended approaches)
1. Easiest (recommended today for many users): Run Oppla inside WSL2 (Ubuntu or Debian) with GUI support (WSLg or an X server). This leverages Linux packaging and is simpler for local-model workloads.
2. Native build: Build from source on Windows — supported but requires Visual Studio toolchain, correct native dependencies, and GPU drivers. Best for contributors and QA.
3. Container: Use a Linux container (Docker Desktop) with device / GPU passthrough (NVIDIA) for testing local models.
Prerequisites (developer/build environment)
* OS: Windows 10 (1909+) / Windows 11 recommended for best WSL2 and GPU support.
* Windows Subsystem for Linux (WSL2) recommended:
* Install WSL2 and a Linux distro (Ubuntu LTS recommended).
* Ensure WSLg (graphic support) or an X server is available for GUI forwarding.
* Native toolchain (for building from source on Windows):
* Visual Studio 2022 or newer with "Desktop development with C++" workload.
* CMake (recent version)
* Git (for source checkout)
* Python 3.x (if the build uses Python tools)
* Node.js / npm or Rust toolchain depending on native components (check the repository README)
* GPU & AI runtimes:
* NVIDIA: CUDA toolkit + drivers (for CUDA-enabled local inference). Install the latest drivers compatible with your GPU and CUDA version.
* DirectML or Windows ML: For DirectML-backed model runtimes, ensure DirectX/DirectML support — verify via Microsoft's guidance.
* Vulkan: If Oppla uses Vulkan acceleration on Windows, install the latest GPU Vulkan drivers from vendor (NVIDIA/AMD/Intel).
* Signing & verification tools (for packagers / release authors):
* signtool.exe (Windows SDK) for code signing
* GPG / SHA256 utilities for release verification
WSL2 (recommended for faster setup)
* Why WSL2:
* You can use the Linux packaging, dependencies, and runtimes that the project primarily targets.
* Easier to run local model runtimes that are Linux-first (llama.cpp, Ollama, etc.)
* GUI support via WSLg enables a native-like graphical experience.
* Setup notes:
1. Enable WSL and install a distro (e.g., Ubuntu 22.04 LTS).
2. Install required Linux dependencies inside WSL (build-essential, cmake, libvulkan\*, etc.)
3. Install and configure local model runtime (e.g., ollama) in WSL.
4. Launch Oppla from the WSL environment and use WSLg for GUI — or run headless server and connect from Windows client.
* GPU passthrough:
* NVIDIA supports CUDA in WSL2 via the CUDA on WSL driver stack; follow NVIDIA docs to enable GPU acceleration inside WSL.
Building from source (native Windows)
* General flow (high-level):
1. Clone repository: git clone ``
2. Install required SDKs/toolchains (Visual Studio with C++ workload, CMake, Python).
3. Follow repository README build steps (project-specific flags, dependencies).
4. Build native binaries and package them (MSIX/NSIS/Wix/Cab as appropriate).
* Common tips:
* Use the Visual Studio Developer x64 Command Prompt when running build scripts that expect MSVC toolchain.
* Ensure environment variables point to correct SDK locations (e.g., VCPKG\_ROOT if using vcpkg).
* For Electron/Node frontends, ensure Node version matches the repo requirements and run npm/yarn install from a POSIX-compatible shell if necessary (Git Bash or WSL may simplify).
* Be prepared to install or build native dependencies (libvulkan, OpenSSL, etc.) for Windows.
Local model / inference runtime notes on Windows
* Many inference runtimes are Linux-first. Check whether the runtime you want (Ollama, llama.cpp wrappers, etc.) has a Windows build or run it inside WSL.
* If using NVIDIA for local inference, install CUDA and the cuDNN versions required by your model runtime.
* For AMD GPUs, Windows ROCm support is limited — prefer Linux for ROCm-based acceleration.
* DirectML can be used as an alternative GPU backend on Windows for some runtimes; check compatibility.
Packaging & distribution
* When creating Windows installers or packages:
* Sign installers and binaries (signtool) to reduce antivirus/SmartScreen friction.
* Provide SHA256 checksums and GPG signatures for release artifacts.
* Offer both native installers and a portable ZIP distribution when possible.
* Consider publishing a Microsoft Store or winget package once stable.
Security & privacy notes
* Avoid running untrusted install scripts (copy-paste `curl | sh`) without validating signatures.
* For cloud AI providers, follow the same privacy model as other platforms: use environment variables / OS credential stores for keys and prefer local-only mode for sensitive projects.
* Audit logging and enterprise RBAC may require extra configuration in Windows deployments (file storage locations, secure transports).
Troubleshooting (common issues)
* Oppla won't start / crashes on launch:
* Run the binary from a terminal to capture stderr/stdout.
* Check `%LOCALAPPDATA%\Oppla\logs` or `~/.config/oppla/logs` (WSL) for logs.
* Verify GPU drivers and runtime libraries (Vulkan, CUDA) are installed.
* GUI rendering issues:
* If running natively, check GPU driver and Vulkan / DirectX versions.
* If using WSLg, ensure WSL and your distro are up to date; try toggling WSLg vs. an external X server.
* Local models not reachable:
* Confirm runtime is running and listening on the expected endpoint.
* In WSL, check localhost/port mapping — consider using `wsl --shutdown` and restarting if networking acts odd.
* High latency for cloud models:
* Verify network connectivity and low-latency routing to provider endpoints; consider regional endpoints.
* Build failures:
* Ensure Visual Studio workloads and CMake are installed.
* Inspect build logs for missing libraries; install required SDKs and ensure PATH includes required tools.
Developer notes & contribution checklist
* Provide a CONTRIBUTING.md at repo root describing Windows build steps and recommended tool versions.
* Add CI job for Windows build & smoke tests to catch regressions.
* Include a small "hello world" native example that verifies the runtime and GPU acceleration on Windows.
* Maintain a signed installer process and publish checksums/signatures for releases.
Related docs
* Linux-specific guidance: docs/ide/general/linux.mdx
* System Requirements: docs/ide/general/system-requirements.mdx
* AI Configuration & Privacy: docs/ide/ai/configuration.mdx and docs/ide/ai/privacy-and-security.mdx
* If you need FreeBSD notes, see docs/development/freebsd.mdx (stub to be created)
Want me to:
* Add a step-by-step native Windows build recipe tailored to this repo (with exact CMake flags, dependencies, and dev env commands)?
* Create a signed-installer checklist and CI jobs for Windows builds?
* Create the FreeBSD stub now as well?
Select which and I'll produce the next file or detailed build script.
# Feedback Analytics
Source: https://docs.oppla.ai/feedback/analytics
Learn how to track and analyze feedback data in Oppla
# Feedback Analytics
Learn how to track, analyze, and make use of the feedback data collected through Oppla's feedback system.
## Tracking Feedback
### Basic Event Tracking
Feedback events are automatically tracked when users interact with the feedback system:
```typescript
// Events are automatically tracked
- feedback_panel_opened
- feedback_submitted
- feedback_cancelled
- feedback_error
```
### Custom Event Properties
Add custom properties to feedback events:
```typescript
publicFeedback({
form: {
title: "Your Feedback",
description: "We would love to hear from you"
},
analytics: {
properties: {
page: "homepage",
section: "features",
userType: "premium"
}
}
});
```
## Analytics Dashboard
### Key Metrics
Track important feedback metrics:
* Total feedback submissions
* Feedback categories distribution
* User engagement rates
* Response times
* User satisfaction scores
### Filtering and Segmentation
Filter feedback data by:
* Date range
* User segments
* Feedback categories
* Response status
* Priority levels
## Data Export
### Export Options
Export feedback data in various formats:
```typescript
// Export all feedback
const feedback = await oppla.feedback.export({
format: 'csv',
dateRange: {
start: '2024-01-01',
end: '2024-03-20'
}
});
// Export specific categories
const bugReports = await oppla.feedback.export({
format: 'json',
categories: ['bug', 'issue'],
status: 'open'
});
```
### Integration with Analytics Tools
Connect feedback data with other analytics tools:
```typescript
// Send feedback events to analytics
oppla.feedback.on('submitted', (feedback) => {
window.oppla.track('Feedback Submitted', {
category: feedback.category,
priority: feedback.priority,
userType: feedback.userType
});
});
```
## Best Practices
1. **Regular Analysis**: Review feedback data regularly
2. **Actionable Insights**: Focus on actionable feedback
3. **User Segmentation**: Analyze feedback by user segments
4. **Trend Analysis**: Track feedback trends over time
## Common Issues
### Data Not Appearing
* Verify tracking implementation
* Check event properties
* Ensure proper initialization
* Check for network issues
### Export Problems
* Verify date ranges
* Check export permissions
* Ensure proper data format
* Check for large dataset limits
## Next Steps
Learn how to customize the feedback form
Learn about basic integration
# Feedback Customization
Source: https://docs.oppla.ai/feedback/customization
Learn how to customize the feedback form and panel in Oppla
# Feedback Customization
Learn how to customize the appearance and behavior of your feedback form and panel.
## Form Customization
### Basic Form Options
```typescript
publicFeedback({
form: {
title: "Your Feedback", // Custom title
description: "We would love to hear from you", // Custom description
submitButtonText: "Submit Feedback", // Custom submit button text
placeholder: "Tell us what you think...", // Custom input placeholder
}
});
```
### Form Fields
Customize the form fields:
```typescript
publicFeedback({
form: {
fields: {
name: {
label: "Your Name",
placeholder: "Enter your name",
required: true
},
email: {
label: "Email Address",
placeholder: "Enter your email",
required: true
},
feedback: {
label: "Your Feedback",
placeholder: "Share your thoughts...",
required: true,
multiline: true
}
}
}
});
```
## Visual Customization
### Colors and Theme
```typescript
publicFeedback({
config: {
primaryColor: "#6366f1", // Primary color
backgroundColor: "#ffffff", // Background color
textColor: "#1f2937", // Text color
borderColor: "#e5e7eb", // Border color
borderRadius: "8px", // Border radius
}
});
```
### Typography
```typescript
publicFeedback({
config: {
typography: {
fontFamily: "Inter, sans-serif",
headingSize: "1.5rem",
bodySize: "1rem",
buttonSize: "0.875rem"
}
}
});
```
### Layout
```typescript
publicFeedback({
config: {
layout: {
width: "400px", // Panel width
maxHeight: "600px", // Maximum height
padding: "24px", // Inner padding
spacing: "16px" // Element spacing
}
}
});
```
## Section Headers
Customize section headers:
```typescript
publicFeedback({
config: {
heading: {
ideas: "💡 Ideas",
announcement: "🔥 Recent Updates",
roadMap: "🛣️ Roadmap",
feedback: "📝 Feedback",
bug: "🐛 Bug Report"
}
}
});
```
## Advanced Customization
### Custom CSS
Add custom CSS classes:
```typescript
publicFeedback({
config: {
customClasses: {
container: "my-custom-container",
form: "my-custom-form",
input: "my-custom-input",
button: "my-custom-button"
}
}
});
```
### Custom Components
Replace default components:
```typescript
publicFeedback({
config: {
components: {
submitButton: CustomSubmitButton,
inputField: CustomInputField,
header: CustomHeader
}
}
});
```
## Best Practices
1. **Consistent Branding**: Match your application's design system
2. **Accessibility**: Ensure sufficient color contrast and readable text
3. **Mobile Responsiveness**: Test on different screen sizes
4. **Performance**: Keep customizations lightweight
## Common Issues
### Styling Conflicts
* Check for CSS specificity issues
* Verify class name conflicts
* Test in different browsers
### Layout Problems
* Verify responsive behavior
* Check container dimensions
* Test with different content lengths
## Next Steps
Track and analyze feedback data
Learn about basic integration
# Feedback Overview
Source: https://docs.oppla.ai/feedback/overview
Learn how to integrate and use Oppla's Feedback feature
# Feedback
Oppla's Feedback feature allows you to collect user feedback, ideas, and feature requests directly from your application. This guide will help you integrate and customize the feedback functionality.
## Installation
Install the Feedback package:
```bash
npm install @oppla-ai/feedback
# or
yarn add @oppla-ai/feedback
```
## Basic Integration
### Initialize Feedback
Create a Feedback component to initialize the feedback system:
```typescript
"use client";
import { useEffect } from "react";
import { init } from "@oppla-ai/feedback"
interface FeedbackProps {
name?: string;
email?: string;
id?: string;
phone_number?: string;
job_title?: string;
}
export const Feedback = ({
name,
email,
id,
phone_number,
job_title
}: FeedbackProps) => {
useEffect(() => {
const properties = {
name: name || "",
email: email || "",
id: id || "",
phone_number: phone_number || "",
job_title: job_title || ""
};
try {
init({
organizationId: "YOUR_ORGANIZATION_ID",
websiteId: "YOUR_WEBSITE_ID",
properties
});
} catch (error) {
console.error('Error initializing feedback:', error);
}
}, [name, email, id, phone_number, job_title])
return null;
};
```
### Open Feedback Panel
Add a button or link to open the feedback panel:
```typescript
import { publicFeedback } from "@oppla-ai/feedback"
// In your component:
{
e.preventDefault();
publicFeedback({
form: {
title: "Your Feedback",
description: "We would love to hear from you"
},
config: {
primaryColor: "#6366f1",
heading: {
ideas: "💡 Ideas",
announcement: "🔥 Recent Updates",
roadMap: "🛣️ Roadmap"
}
}
});
}}
className="flex items-center gap-2 text-sm text-muted hover:underline cursor-pointer"
>
Feedback
```
## Configuration Options
### Form Configuration
Customize the feedback form:
```typescript
publicFeedback({
form: {
title: "Your Feedback", // Custom title
description: "We would love to hear from you", // Custom description
// Add more form customization options
}
});
```
### Visual Configuration
Customize the appearance:
```typescript
publicFeedback({
config: {
primaryColor: "#6366f1", // Custom primary color
heading: {
ideas: "💡 Ideas",
announcement: "🔥 Recent Updates",
roadMap: "🛣️ Roadmap"
}
// Add more visual customization options
}
});
```
## Best Practices
1. **Initialize Early**: Initialize the feedback system as early as possible in your application
2. **User Context**: Provide user information when available for better feedback context
3. **Strategic Placement**: Place feedback triggers in relevant locations
4. **Clear Call-to-Action**: Use clear and inviting language for feedback buttons
## Common Issues
### Initialization Errors
* Verify organization and website IDs
* Check for network connectivity
* Ensure proper user properties format
### Panel Not Opening
* Check for JavaScript errors
* Verify event handler implementation
* Ensure proper component mounting
## Next Steps
Learn how to customize the feedback form
Track and analyze feedback data
# Advanced Keybindings
Source: https://docs.oppla.ai/ide/advanced/keybindings
Deep dive: keymap syntax, contexts, conflict resolution, AI-aware modifiers, and debugging
This guide is for power users and extension authors who need precise control over Oppla keymaps. It complements the user-facing Key Bindings page and shows advanced patterns, context expressions, conflict resolution rules, and troubleshooting steps.
If you're new to keymaps, start with the user guide: ../configuration/key-bindings.mdx
## Where keymaps live
* User keymap: `~/.config/oppla/keymap.json`
* Project keymap (optional): `.oppla/keymap.json` (project-specific overrides)
* Default keymaps: packaged with the app (read-only)
User keymaps merge with defaults; project keymaps take precedence for that workspace.
## Keymap JSON schema (overview)
Keymaps are arrays of entries. Each entry can contain:
* `bindings`: map of key sequences to action names or \[action, args]
* `context`: optional context expression (see below)
* `description`: optional human-friendly description
Example: (structured example below)
```docs/ide/advanced/keybindings.mdx#L1-60
{
"bindings": {
"ctrl-right": "editor::SelectLargerSyntaxNode",
"ctrl-left": "editor::SelectSmallerSyntaxNode",
"cmd-shift-a": "ai::InlineAssist",
"cmd-enter": "ai::AcceptSuggestion"
}
}
```
> Note: Use environment-appropriate modifier names (`cmd-` on macOS, `super-`/`win-` on Windows).
## Key sequence syntax
* Keys are lowercased, modifiers prefixed (e.g., `cmd-`, `ctrl-`, `alt-`, `shift-`).
* Multi-key sequences use space separation: `"cmd-k cmd-s"` means press Cmd-K, then Cmd-S.
* Double-tap: `"shift shift"` maps a double Shift press.
* Special `ai-` modifier: maps to your platform's AI modifier (default: `cmd-shift`), useful for AI-specific shortcuts.
## Context expressions
Contexts scope bindings to specific UI states or editor modes. They follow a simple boolean expression language:
* Basic: `Editor`, `ProjectPanel`, `ai_panel_focused`
* Predicates: `mode=full`, `extension=py`
* Logical operators: `&&` (and), `||` (or), `!` (not)
* Example: `Editor && mode=full && !ai_suggestion_active`
Context specificity rules:
* More specific contexts win over generic ones.
* When multiple bindings match, the one with the most specific context expression (highest number of positive clauses) takes precedence.
* User keymaps override defaults regardless of specificity.
## AI-aware contexts & modifiers
Oppla introduces several AI-specific contexts and actions; keep these in mind for smooth AI UX:
Common AI contexts:
* `ai_suggestion_active`
* `ai_panel_focused`
* `ai_refactoring`
* `ai_generating`
Common AI actions:
* `ai::InlineAssist`
* `ai::AcceptSuggestion`
* `ai::DismissSuggestion`
* `ai::NextSuggestion`
* `ai::PreviousSuggestion`
Use contexts to avoid conflicts between regular editor bindings and AI suggestions (e.g., map `tab` to `ai::AcceptSuggestion` only in `ai_suggestion_active`).
## Conflict resolution & timing
* Prefix conflicts: If you have `ctrl-w` and `ctrl-w left`, Oppla uses a smart delay based on learned typing speed. You can configure wait time via settings.
* User bindings override packaged defaults.
* For ambiguous multi-key sequences, prefer explicit contexts or longer sequences to disambiguate.
## Debugging keymaps
* From Command Palette: `dev: Open Key Context View` — shows current context tree and active bindings.
* Run "AI: Analyze Keymap Usage" after a week of usage to generate suggested remaps.
* When bindings don't fire:
* Check context expression (negations and scope).
* Ensure there are no higher-priority bindings in project or default maps.
* Use the Key Context View to trace the evaluated contexts.
## Best practices
* Keep ergonomic frequency in mind: bind common actions to easily reachable keys.
* Use `ai_keymap_learning` sparingly for teams; require review before applying org-wide changes.
* Prefer sequential combos (`cmd-k cmd-s`) for rarely used or destructive commands.
* Provide `--dry-run` or preview actions for AI-powered shortcuts that apply multi-file changes.
## Examples
Keymap example (project-level) showing context use, AI actions, and action arguments:
```docs/ide/advanced/keybindings.mdx#L61-140
[
{
"description": "Editor selection helpers",
"bindings": {
"ctrl-right": "editor::SelectLargerSyntaxNode",
"ctrl-left": "editor::SelectSmallerSyntaxNode"
}
},
{
"context": "Editor && ai_suggestion_active",
"bindings": {
"tab": "ai::AcceptSuggestion",
"escape": "ai::DismissSuggestion",
"cmd-right": "ai::NextSuggestion",
"cmd-left": "ai::PreviousSuggestion"
}
},
{
"context": "ProjectPanel && not_editing",
"bindings": {
"o": "project_panel::Open",
"a": "ai::AnalyzeFile"
}
},
{
"description": "AI-refactor with args and approval requirement",
"context": "ai_refactoring && user_role=maintainer",
"bindings": {
"cmd-shift-r": ["ai::Refactor", { "style": "functional", "require_approval": true }]
}
}
]
```
## Migration tips (from other editors)
* Map common chords (VSCode `ctrl-k ctrl-s`) to sequential combos to preserve muscle memory.
* Provide a compatibility base keymap in `base_keymap` settings and layer project overrides.
* Audit conflicts by exporting your current keymap and running the Key Context View to surface conflicts.
## Troubleshooting
* After edits, restart or reload Oppla to ensure changes are applied.
* If keys behave differently across OSes, check `use_key_equivalents` and platform-specific modifiers.
* If AI accepts `Tab` unexpectedly, constrain `tab` binding to `ai_suggestion_active` context.
## Further reading
* User guide: ../configuration/key-bindings.mdx
* Configuration reference: ../configuring-oppla.mdx
* AI Overview & related features: ../ai/overview\.mdx
If you want, I can:
* Produce a linter that validates keymap JSON and context expressions.
* Generate a sample migration script that converts a VSCode keybindings.json into Oppla's format.
# Agent Panel
Source: https://docs.oppla.ai/ide/ai/agent-panel
Interact with autonomous AI agents to perform multi-file tasks, refactors, and intelligent code actions
The Agent Panel is Oppla's interactive workspace for autonomous and semi-autonomous AI agents. Agents are specialized AI workflows that can understand project context, execute multi-step tasks, and produce or modify code across files while respecting your project rules and permissions.
This page is a stub that describes the Agent Panel's core concepts, primary workflows, security considerations, and links to related AI features. Full how-tos and deep-dive guides will be added soon.
## Quick summary
* Purpose: Run focused AI agents to automate complex developer tasks (refactors, migrations, bulk edits, documentation generation, testing).
* Access: Command Palette → "AI: Open Agent Panel" or use the keyboard shortcut (configurable).
* Safety: Agents run in a constrained environment with granular permissions and audit logging.
* Integrations: Works with AI Rules, Model Context Protocol (MCP), and external tools for enhanced capabilities.
**\[PLACEHOLDER: Agent Panel UI screenshot]**
*This image will show: the Agent Panel UI with agent list, task builder, logs, and a preview of file changes.*
*Dimensions: 1400x900*
*Priority: High*
## Open the Agent Panel
1. Open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P).
2. Run: `AI: Open Agent Panel`.
3. Choose an agent from the gallery or create a new one using the "New Agent" button.
4. Provide the task prompt or select a predefined workflow (e.g., "Refactor imports", "Migrate to async/await", "Add unit tests for module").
Tip: You can pin frequently used agents to the panel for quick access.
## Core agent capabilities
* Project-aware analysis: Agents inspect the repository to build context (imports, modules, tests).
* Multi-file edits: Propose and apply changes across many files with preview and staged commits.
* Rules-aware behavior: Agents follow AI Rules that enforce style, safety, or project-specific constraints. See [AI Rules](./rules.mdx).
* Tool usage: Agents can call configured tools (linters, formatters, test runners) via the Model Context Protocol. See [AI Tools](./tools.mdx) and [Models](./models.mdx).
* Conversational control: Use a conversational thread to refine agent behavior while the task is running. See [Text Threads](./text-threads.mdx).
* Dry run / preview mode: Always preview changes before applying; use the built-in diff viewer.
## Typical agent workflows
1. Single-file task (quick fix)
* Use an inline assistant or the Agent Panel to request a concise fix (e.g., "Simplify this function").
* Agent proposes a patch; review and apply.
2. Multi-file refactor (medium risk)
* Select "Refactor" agent and describe the transformation.
* Review the agent's proposed changes across files in the staged preview.
* Run unit tests with the agent before applying changes.
3. Full migration or architecture change (high risk)
* Create an agent workflow that includes planning, a staged rollout, and tests.
* Use "Canary" or "Incremental apply" options to apply changes in small batches.
* Enable audit logging and require human approval before final commit.
4. Test generation and validation
* Generate unit or integration tests for a target module.
* Agent runs tests in an isolated sandbox and reports failures with suggestions.
## Configuration & customization
* Default model: Choose which model agents use for planning vs. execution in AI settings. See [AI Configuration](./configuration.mdx).
* Agent templates: Create and save project-specific agent templates for recurring tasks.
* Timeouts and retries: Configure per-agent timeouts and retry policies to avoid runaway tasks.
* Human-in-the-loop: Require approvals for changes above a given risk threshold.
## Permissions & safety
Oppla enforces layered safety controls for agents:
* Per-project permissions: Restrict which users or roles can run or approve agents.
* Scopes: Agents must request explicit scopes (read, write, run-tests, access-secrets). Admins can whitelist or blacklist scopes.
* Audit logging: Every agent run can be logged (who ran it, what model/provider was used, diffs proposed, approvals).
* Dry-run-first default: Agents open in preview mode by default; changes are not applied until explicitly approved.
* Rate limits & quotas: Prevent excessive automated changes by enforcing quotas.
See [Privacy & Security](./privacy-and-security.mdx) for details on data handling and encryption.
## Integrations
* Tools (linters, formatters, test runners): Agents can call external tools via the Model Context Protocol. See [AI Tools](./tools.mdx).
* Extension hooks: Extensions can register agent-aware hooks to add custom capabilities or validation steps.
* CI/CD: Export agent-produced patches as PRs or link them to your CI pipeline for validation.
## Troubleshooting & tips
* Agent produces unexpected changes:
* Check the preview diff and rollback.
* Re-run the agent with a narrower scope or explicit constraints.
* Use AI Rules to encode prohibited transformations.
* Agent fails due to model limits:
* Switch to a larger model for planning or enable multi-pass execution.
* Reduce context size by focusing the agent on specific files.
* Tests fail after applying agent changes:
* Use the Agent Panel to revert the last applied change.
* Iterate with an agent configured to prioritize test passing.
## Best practices
* Start small: Run agents on unit-sized scopes before broad refactors.
* Use rules: Encode coding standards and safety checks to guide agents.
* Review diffs: Human review of proposed changes is essential for maintainability.
* Combine tools: Run linters and tests inside agent workflows to validate output.
* Track provenance: Keep notes in commits indicating which agent and prompt produced the changes.
## Links & next steps
* AI Overview: [Overview](./overview.mdx)
* Configure AI providers: [AI Configuration](./configuration.mdx)
* Related AI pages (stubs — content to be added):
* Edit Prediction: [Edit Prediction](./edit-prediction.mdx)
* AI Rules: [Rules](./rules.mdx)
* AI Tools: [Tools](./tools.mdx)
* Available Models: [Models](./models.mdx)
* Privacy & Security: [Privacy & Security](./privacy-and-security.mdx)
* Text Threads: [Text Threads](./text-threads.mdx)
## Feedback & contribution
This page is a stub. If you have feature requests, bug reports, or design suggestions for the Agent Panel, please file an issue in the docs repo or contact the AI docs team.
***
# AI Configuration
Source: https://docs.oppla.ai/ide/ai/configuration
Configure AI providers, local models, and privacy settings for Oppla
This page explains how to configure AI providers and local models in Oppla. It's a concise, actionable reference for developers and users who want to get AI features working quickly while maintaining control over privacy and cost.
If you're new to Oppla, start with the AI Overview: [AI Overview](./overview.mdx)
## Supported Providers (summary)
Oppla supports both cloud and local AI providers. Choose one based on your latency, privacy, and cost needs.
* Cloud providers
* OpenAI (GPT family)
* Anthropic (Claude)
* Google AI (Gemini)
* Azure OpenAI
* AWS Bedrock
* Local providers
* Ollama
* LLama-based runtimes (llama.cpp, GGML variants)
* Custom HTTP endpoints (self-hosted inference)
* Note: Provider availability depends on your Oppla build channel (stable/preview) and platform.
## Quick setup (2–5 minutes)
1. Open Oppla → Preferences → AI or open the Command Palette and run `oppla: Open AI Settings`.
2. Select your provider (Cloud or Local).
3. Add credentials (API key or local endpoint). Prefer using OS secret stores or environment variables (see below).
4. Choose the default model for completions and the model for heavier tasks (agents, refactoring).
5. Save and test the connection via the "Test Provider" button.
## Configuration locations
* GUI: Preferences → AI
* CLI / config file: your Oppla settings file (user-level)
* macOS / Linux: `~/.config/oppla/settings.json`
* Windows (when supported): `%APPDATA%\Oppla\settings.json`
(If you prefer config files or automation, you can provision these settings in your settings JSON — see example below.)
## Credentials and secrets (best practices)
* Do not store API keys in plain text in your project repositories.
* Use platform secret stores:
* macOS Keychain
* Linux: Secret Service / GNOME Keyring / pass
* Environment variables for CI: OPPLA\_AI\_PROVIDER, OPPLA\_AI\_API\_KEY
* Oppla will prompt to store keys in the OS secret store by default.
* For self-hosted endpoints, use HTTPS and certificate validation; provide an access token instead of an API key when available.
## Example settings (user-level)
This example shows the keys commonly used in the Oppla settings file. Adapt to your environment and provider.
```json
{
"ai": {
"provider": "openai",
"providers": {
"openai": {
"api_key_env": "OPENAI_API_KEY",
"default_model": "gpt-4o-mini",
"timeout_ms": 30000,
"max_tokens": 2048
},
"anthropic": {
"api_key_env": "ANTHROPIC_API_KEY",
"default_model": "claude-2.1"
},
"ollama": {
"endpoint": "http://localhost:11434",
"default_model": "llama2-13b"
}
},
"privacy": {
"send_code": "opt_in", // options: opt_in | opt_out | allow_local_only
"telemetry": false,
"local_model_preferred": true
},
"agent": {
"enabled": true,
"default_timeout_seconds": 300
}
}
}
```
Notes:
* `api_key_env` references an environment variable. Using env vars avoids storing secrets in plain files.
* `local_model_preferred: true` prefers local models when available.
## Local models & on-premises
To run models locally:
* Install and run your chosen runtime (Ollama, llama.cpp frontend, or containerized inference).
* Point Oppla to the runtime endpoint in settings (e.g., `http://localhost:11434`).
* For large models, ensure you meet the hardware and storage requirements (see System Requirements).
* If you operate in an air-gapped environment, enable "local only" mode in AI settings. This prevents any outbound requests.
## Privacy & security highlights
* Data residency: When using cloud providers, code context sent to the provider may be logged according to the provider's policy — review provider privacy docs.
* Granular control: Use per-project privacy settings to limit what is shared with cloud providers.
* Audit logging: Enterprise installs can enable audit logs for AI requests and agent actions.
* Secure endpoints: For custom endpoints, use HTTPS and validate certificates. Rotate tokens frequently and use short-lived credentials where possible.
## Cost & usage controls
* Configure model choice per task (cheap, fast models for completion; larger models for agents).
* Set per-user or per-team quotas in enterprise environments.
* Monitor usage in the Oppla dashboard or via provider billing dashboards.
## Troubleshooting
* "Test Provider" fails:
* Verify API key / token is valid and not expired.
* Ensure network connectivity and low latency to provider endpoints.
* Check OS secret store permissions.
* Slow suggestions or high latency:
* Switch to a lower-latency or local model.
* Reduce requested context window or tokens.
* Unsatisfactory completions:
* Try a different model or tweak temperature/settings.
* Provide more relevant context files in the editor.
* Local model not found:
* Confirm runtime is running and endpoint is reachable (curl / HTTP request).
* Check logs for model-loading errors and memory availability.
## Recommended defaults
* Completions: fast, small model (low cost, low latency)
* Refactoring / code transforms: medium-sized model with higher reasoning capability
* Agents & multi-file tasks: powerful model or enterprise-hosted model
## Links & next steps
* AI Overview: [AI Overview](./overview.mdx)
* AI edit prediction (coming soon): [Edit Prediction (stub)](./edit-prediction.mdx)
* Agent Panel (coming soon): [Agent Panel (stub)](./agent-panel.mdx)
* Privacy & security (recommended — create page): [Privacy & Security (stub)](./privacy-and-security.mdx)
* Themes and keybindings are separate configs:
* [Key Bindings](../configuration/key-bindings.mdx)
* [Themes](../configuration/themes.mdx)
## Audit & validation
Before publishing specific latency or accuracy claims:
* Run benchmarks on representative hardware and network conditions.
* Document test environment, date, and methodology.
***
If you want, I can:
* Create small stubs for the referenced pages (edit-prediction, agent-panel, privacy-and-security) so these links resolve.
* Add an OS-specific credential-storage guide with commands.
* Provide example curl tests for each provider to validate connectivity.
Which would you like me to create next?
# Edit Prediction
Source: https://docs.oppla.ai/ide/ai/edit-prediction
How Oppla's Edit Prediction anticipates and suggests your next code edits
Edit Prediction is Oppla's low-latency, context-aware feature that surfaces likely next edits as you type or navigate code. It blends language-model completions with predictive heuristics so suggestions feel proactive and relevant to your current intent.
This page is a practical stub with conceptual details, setup, and troubleshooting for engineers and power users. Full examples and UX screenshots will be added soon.
## What is Edit Prediction?
Edit Prediction predicts your next changes in-place — not just completing a token, but suggesting whole edits, ranges, and intent-aware transformations such as:
* Completing multi-line constructs (loops, function bodies)
* Proposing import additions and automatic reordering
* Fixing off-by-one or common logic mistakes
* Suggesting refactor steps (rename, extract function) as a preview
It is optimized for minimal latency so predictions appear while you type, and for correctness by using project-wide context.
## How it works (high-level)
1. Context collection: Oppla constructs a lightweight context window from the active file, open buffers, and important project files (imports, configs).
2. Local heuristics: Fast, local heuristics apply to produce immediate suggestions for trivial edits.
3. Model scoring: If deeper reasoning is required, the configured model scores candidate edits and ranks them by confidence.
4. Presentation: The top predictions are shown inline or in a suggestion strip; accept, cycle, or dismiss them.
Key considerations:
* Privacy: By default, context sent to cloud models is minimized; local models avoid outbound traffic.
* Safety: Predictions are suggestions — they require explicit acceptance to modify files unless configured otherwise.
## Quick start
1. Open AI Settings: Command Palette → `oppla: Open AI Settings` (or Preferences → AI)
2. Ensure an AI provider or local model is configured (see AI Configuration).
3. Enable Edit Prediction:
* Preferences → AI → Enable "Edit Prediction"
4. Try it: Open a source file and start typing a function or a common pattern. Watch for inline predictions.
## Keyboard & UX
* Accept inline prediction: `Tab` (configurable)
* Accept in suggestion strip: `Cmd-Enter` / `Ctrl-Enter`
* Next suggestion: `Cmd-Right` / `Ctrl-Right`
* Previous suggestion: `Cmd-Left` / `Ctrl-Left`
* Dismiss: `Esc`
* Toggle Edit Prediction on/off: Command Palette → `AI: Toggle Edit Prediction`
You can customize these bindings in your keymap. See Key Bindings.
## Configuration (example)
Add or edit your user settings (\~/.config/oppla/settings.json) to tweak how Edit Prediction behaves:
```docs/ide/ai/edit-prediction.mdx#L1-120
{
"ai": {
"edit_prediction": {
"enabled": true,
"local_first": true,
"max_suggestions": 3,
"accept_key": "tab",
"confidence_threshold": 0.65,
"context_window_lines": 400,
"prefetch_on_file_open": true,
"auto_apply_low_risk": false
}
}
}
```
Field notes:
* local\_first: Prefer local runtime when available (reduces latency & improves privacy).
* confidence\_threshold: Minimum confidence to show a suggestion (0–1).
* auto\_apply\_low\_risk: When true, low-risk single-line fixes (e.g., missing semicolon) can be applied automatically — use with caution.
## Privacy & security
* Default behavior minimizes remote context: only line ranges and a short surrounding window are sent to cloud providers unless you opt in to broader context.
* For sensitive projects, enable `local_first` and run models locally (Ollama, llama.cpp, etc.).
* Audit logs: Enterprise builds can record prediction requests for compliance — check Privacy & Security docs for configuration details.
* Always review edits before accepting. Predictions are heuristics and may be incorrect.
## Developer & integration notes
* Edit Prediction exposes an internal API for extensions to register custom predictors (planned). Extensions may provide domain-specific suggestions (e.g., SQL snippets, test generation).
* Prediction scoring uses a hybrid model: a lightweight local scorer for immediate suggestions plus server/model scoring for higher-quality options.
* If you're building tooling that interacts with predictions, prefer non-blocking callbacks and provide opt-out settings to users.
## Troubleshooting
* No suggestions appearing:
* Confirm `ai.edit_prediction.enabled` is true.
* Check your provider is configured and reachable (AI Configuration).
* If using local models, ensure the local runtime is running and reachable.
* Suggestions are low quality:
* Increase context by opening relevant files (Edit Prediction prefers open buffers).
* Try a different model or adjust `confidence_threshold`.
* Disable any experimental rules that modify code structure.
* High latency:
* Enable `local_first`.
* Reduce `context_window_lines` or set `prefetch_on_file_open` to false.
* Unexpected auto-applies:
* Ensure `auto_apply_low_risk` is false; if true, set to false while debugging.
## Best practices
* Let Edit Prediction learn: use defaults for a week before heavy customization.
* Use `local_first` on private codebases.
* Combine with AI Rules to constrain behaviors (e.g., disallow certain automated edits).
* Keep open only files relevant to the task — smaller context often leads to better suggestions.
## Related pages
* AI Overview: [AI Overview](./overview.mdx)
* AI Configuration: [AI Configuration](./configuration.mdx)
* Agent Panel: [Agent Panel](./agent-panel.mdx)
* Key Bindings: [Key Bindings](../configuration/key-bindings.mdx)
* Themes: [Themes](../configuration/themes.mdx)
* Privacy & Security (stub): [Privacy & Security](./privacy-and-security.mdx)
## Feedback
This is a living feature. If Edit Prediction behaves unexpectedly or you have ideas for improvements (acceptance UX, confidence tuning, domain-specific predictors), please open a docs or feature request.
***
Note: This page is a functional stub. Full UX examples, GIFs, and benchmarked latency/accuracy numbers will be added after engineering provides measurement artifacts.
# Inline Assistant
Source: https://docs.oppla.ai/ide/ai/inline-assistant
In-context AI help directly inside your editor — suggestions, explanations, and quick fixes
The Inline Assistant brings Oppla's AI directly into your code editor so you can get context-aware help without leaving the file. Use it for quick explanations, suggested edits, one-line fixes, documentation generation, and other small-scale tasks that benefit from immediate, low-latency assistance.
This page is a concise, actionable stub that explains core concepts, usage patterns, configuration options, privacy considerations, and troubleshooting. Full UX screenshots and GIFs will be added later.
## What is the Inline Assistant?
* Lightweight, in-place AI that analyzes the current buffer and surrounding context.
* Designed for short interactions: explain this function, suggest a fix, write a docstring, or convert a code snippet.
* Works with local or cloud models depending on your AI Configuration and AI Rules.
* Complements Edit Prediction (predicts edits as you type) and the Agent Panel (for multi-file or higher-risk tasks).
## Core capabilities
* Explain code: produce concise, line-by-line or function-level explanations.
* Quick fixes: propose single-file, low-risk edits (format, small refactors).
* Documentation: generate docstrings, README snippets, or code comments.
* Examples: produce example usage for functions or APIs.
* Small refactor hints: suggest variable renames or extract helpers (applied only with approval).
* Test suggestions: propose simple unit test templates for the current function.
## Quick start
1. Open a code file in Oppla.
2. Place the cursor on a symbol, select a code range, or highlight a function.
3. Invoke Inline Assistant:
* Command Palette: `AI: Inline Assist`
* Default keybinding: `Cmd-Shift-A` (macOS) / `Ctrl-Shift-A` (Linux)
4. Choose the action (Explain, Suggest Fix, Generate Tests, Add Docstring).
5. Inline suggestions will appear as ephemeral edits or as a preview panel — review before accepting.
Tip: Inline Assistant prefers small scopes (a single function or a code block) for the best results and lowest latency.
## Keyboard & UX
* Open Inline Assistant: Command Palette → `AI: Inline Assist`
* Accept inline suggestion: `Tab`
* Apply suggestion as patch: `Cmd-Enter` / `Ctrl-Enter`
* Dismiss: `Esc`
* Cycle alternatives: `Cmd-Right` / `Cmd-Left` (configurable)
* Trigger contextual help hover: `Alt-Enter` (or platform equivalent)
Customize these in your keymap. See Key Bindings for examples and advanced configuration.
## Configuration & settings
Inline Assistant settings live in the AI section of your settings file or preferences UI. Example settings (user-level):
```json
{
"ai": {
"inline_assistant": {
"enabled": true,
"local_first": true,
"max_context_lines": 200,
"suggestion_confidence_threshold": 0.6,
"auto_accept_trivial_fixes": false
}
}
}
```
* local\_first: Prefer a configured local runtime for privacy and lower latency.
* max\_context\_lines: How much surrounding code to send to the model.
* auto\_accept\_trivial\_fixes: When true, trivial single-token or formatting fixes can be applied automatically (use with caution).
## Integration with other AI features
* Edit Prediction: Use inline suggestions for immediate edits while Edit Prediction offers next-step predictions as you type.
* Agent Panel: When a task requires multi-file changes or high-risk operations, the Inline Assistant will recommend using the Agent Panel instead.
* AI Rules: Inline Assistant respects AI Rules — any suggestion that would violate a rule is blocked or redacted.
* MCP & Tools: For verification (e.g., run tests), Inline Assistant can invoke tools via the Model Context Protocol if allowed by project settings.
## Privacy & security
* Default behavior: minimal outgoing context. Only the selected lines and a short surrounding window are sent to the model.
* Use local-only mode for air-gapped or sensitive projects (see AI Configuration).
* For cloud providers, the user must configure and permit provider usage. Inline Assistant will not send secrets or files matching AI Rules patterns.
* Audit logs: enterprise installs can log inline requests and responses for review (subject to redaction policies).
## Best practices
* Scope requests narrowly: select the function or block you want help with instead of the whole file.
* Review suggestions: always review AI edits before applying them, especially for security- or correctness-critical code.
* Use local-first on proprietary codebases to reduce risk of exfiltration.
* Combine with linters and tests: treat AI suggestions as first drafts and validate them with existing tooling.
## Troubleshooting
* No suggestions appear:
* Ensure `ai.inline_assistant.enabled` is true.
* Check AI provider availability and that credentials are configured (AI Configuration).
* If using a local runtime, verify it is running and reachable.
* Suggestions are low quality:
* Provide more focused context (open related files or select a larger range).
* Try a different model or increase the confidence threshold.
* High latency:
* Enable local\_first or choose a lower-latency model.
* Reduce `max_context_lines`.
* Suggestions blocked:
* AI Rules may be redacting or blocking the required context (check project `.oppla/ai-rules.json`).
## Developer notes
* Extensions can implement custom inline handlers to provide domain-specific suggestions (for example, language-aware autofixes). Prefer structured suggestion outputs (patches, ranges, replacements).
* Keep outputs small and machine-friendly (JSON patches) to allow reliable application by the editor.
* Provide dry-run and preview modes for any extension-provided inline actions.
## Links & next steps
* AI Configuration: [AI Configuration](./configuration.mdx)
* Edit Prediction: [Edit Prediction](./edit-prediction.mdx)
* Agent Panel: [Agent Panel](./agent-panel.mdx)
* AI Rules: [AI Rules](./rules.mdx)
* Privacy & Security: [Privacy & Security](./privacy-and-security.mdx)
* Model Context Protocol: [MCP](./mcp.mdx)
***
This is a stub intended to resolve missing links and provide immediate guidance. I can add UI screenshots, GIFs for common flows, or full step-by-step examples for specific languages next. Would you like a walkthrough for JavaScript, Python, or another language first?
# Model Context Protocol (MCP)
Source: https://docs.oppla.ai/ide/ai/mcp
Spec and developer guide for Oppla's Model Context Protocol — how AI agents securely call tools and services
The Model Context Protocol (MCP) is Oppla's standardized integration layer that lets AI agents and features call deterministic tools, services, and extension-provided capabilities in a safe, auditable, and structured way.
This page is a technical stub that outlines MCP's purpose, key concepts, message patterns, security model, and example registration/invocation schemas. Full API references, SDK samples, and end-to-end tutorials will be added in subsequent docs.
Core goals
* Provide a consistent, machine-readable contract for tools so models and agents can rely on structured outputs.
* Ensure tool calls run in sandboxed environments with fine-grained permissions and audit logging.
* Make tool outputs deterministic and parseable (JSON schemas preferred) for reliable downstream processing.
* Support synchronous, asynchronous, and streaming tool interactions.
Key concepts
* Tool: Any deterministic operation an agent may request (linters, test runners, formatters, vulnerability scanners, CI triggers).
* Tool Registration: Metadata that advertises a tool's capabilities, input schema, output schema, and required scopes.
* Invocation: A single call from an agent (or UI) to a registered tool through the MCP broker.
* Broker: The MCP runtime inside Oppla that validates requests, enforces AI Rules and permissions, runs the tool, and returns structured results.
* Schema-first: Tools should expose JSON schemas for inputs and outputs to make parsing and validation reliable.
* Audit: Every invocation is logged with requester, arguments (redacted per rules), and results for traceability.
MCP message patterns
* Synchronous request/response
* Agent sends a single request; the broker runs the tool and returns a JSON result or error.
* Asynchronous job
* Useful for long-running tasks (test suites, large builds). Broker returns a job ID; the agent polls or subscribes to status updates.
* Streaming
* For progressively-emitted outputs (test progress, build logs). Broker streams events while the agent consumes them.
* Dry-run vs apply
* Tools should support a `dry_run` mode that returns proposed changes without applying them. Agents should default to dry-run for high-risk operations.
Tool registration (recommended fields)
* id: Stable tool identifier (string)
* name: Human-friendly name
* description: Short description of what the tool does
* inputs: JSON Schema for the tool input
* outputs: JSON Schema for tool output
* scopes: Permissions required (read\_workspace, write\_workspace, run\_tests, network)
* dry\_run\_supported: boolean
* timeout\_seconds: recommended max runtime
* example\_invocations: small examples to help model planning
Example tool registration (recommended minimal manifest)
```docs/ide/ai/mcp.mdx#L1-40
{
"id": "jest-runner",
"name": "Jest Test Runner",
"description": "Run jest on a list of files or a workspace; returns structured test results",
"inputs": {
"type": "object",
"properties": {
"files": { "type": "array", "items": { "type": "string" } },
"ci": { "type": "boolean", "default": false },
"dry_run": { "type": "boolean", "default": true }
},
"required": ["files"]
},
"outputs": {
"type": "object",
"properties": {
"exit_code": { "type": "integer" },
"duration_ms": { "type": "integer" },
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"file": { "type": "string" },
"test_name": { "type": "string" },
"status": { "type": "string", "enum": ["passed", "failed", "skipped"] },
"error": { "type": ["string", "null"] }
}
}
}
}
},
"scopes": ["read_workspace"],
"dry_run_supported": true,
"timeout_seconds": 120
}
```
Invocation flow (high-level)
1. Agent composes a plan and determines required tool(s).
2. Agent issues an MCP invocation: { tool_id, arguments, request_context }.
3. Broker validates:
* Tool exists and is registered
* Caller has the required scopes (AI Rules & RBAC)
* Inputs validate against tool input schema
* No redaction policy violations
4. Broker runs tool in sandbox:
* Constrains filesystem access, network, CPU/memory, and time
* Optionally runs inside container / ephemeral environment
5. Tool returns structured output (or job ID for async)
6. Broker validates output schema, redacts sensitive fields if necessary, logs the invocation, and returns the result to the agent.
Example synchronous invocation (payload)
```docs/ide/ai/mcp.mdx#L41-96
{
"request_id": "req-2025-0001",
"tool_id": "jest-runner",
"arguments": {
"files": ["packages/api/__tests__/user.test.js"],
"dry_run": true
},
"caller": {
"type": "agent",
"id": "agent-42",
"user": "alice@example.com"
},
"context": {
"repo": "acme/starship",
"commit": "a1b2c3d"
}
}
```
Example synchronous response
```docs/ide/ai/mcp.mdx#L97-160
{
"request_id": "req-2025-0001",
"status": "success",
"result": {
"exit_code": 0,
"duration_ms": 3400,
"results": [
{ "file": "packages/api/__tests__/user.test.js", "test_name": "creates user", "status": "passed", "error": null }
]
},
"metadata": {
"worker_id": "worker-7",
"started_at": "2025-08-01T12:34:56Z",
"completed_at": "2025-08-01T12:35:00Z"
}
}
```
Asynchronous invocation (job pattern)
* Agent requests a long-running job; broker returns job\_id.
* Agent polls `mcp/jobs/{job_id}` or receives event notifications.
* Broker enforces timeouts, retries, and job cancellation semantics.
Security & permissions
* Principle of least privilege: Tools declare required scopes; MCP enforces requester permissions before invocation.
* AI Rules are evaluated before any outbound request or tool run. Rules can:
* Block invocations on certain paths
* Redact or transform arguments
* Override provider selection (local-only enforcement)
* Sandboxing:
* Tools run with confined access (container, chroot, restricted user).
* Filesystems mounted read-only unless write access is explicitly requested and permitted.
* Network access:
* By default, tool network access is restricted. If a tool requires outbound access, it must declare that scope and be explicitly allowed by project/organization policy.
* Secrets & redaction:
* Tool inputs/outputs are scanned for secrets per AI Rules; redaction happens before logs or outbound transmissions.
* Audit logging:
* Every invocation and result is logged with requester, tool\_id, redaction decisions, and outcome. Enterprise installations must configure retention policies.
Developer guidance & best practices
* Prefer structured outputs (JSON) with stable schemas. Avoid free-form text where machines need to act on the data.
* Provide a `dry_run` mode to enable previewing changes (patches) without applying them.
* Keep outputs small and paginated if needed; prefer references (artifact IDs) for large logs or binaries.
* Return meaningful error codes and structured error objects for deterministic handling.
* Include `example_invocations` and small fixtures to help AI planning and prompt engineering.
* Implement idempotent operations and safe rollback semantics for applying changes.
* Validate inputs aggressively to avoid injection or command-execution vulnerabilities.
Example output schema for a "format" tool (suggested)
```docs/ide/ai/mcp.mdx#L161-220
{
"type": "object",
"properties": {
"exit_code": { "type": "integer" },
"files_modified": {
"type": "array",
"items": { "type": "object", "properties": { "path": { "type": "string" }, "diff": { "type": "string" } } }
},
"errors": { "type": ["array", "null"], "items": { "type": "string" } }
}
}
```
Observability & troubleshooting
* Correlate MCP `request_id` to agent traces and audit logs.
* Broker should expose a `mcp/health` and `mcp/jobs` endpoints for diagnostics.
* Provide a developer `dry-run` harness to validate registrations locally.
* Surface structured tool logs in developer UI and keep large logs as downloadable artifacts.
Integration patterns
* Extension authors: register tools via an extension manifest and expose a stable endpoint (local binary, HTTP, or via Oppla extension API).
* CI integration: use MCP to run CI checks deterministically and return results for agents to act on (e.g., apply suggested fixes if CI passes).
* Agents: plan -> ask MCP for verification (lint/tests) -> receive structured results -> propose final patches.
Next steps (docs & implementation)
* Create detailed API reference for MCP endpoints (REST/HTTP + event/websocket schemas).
* Provide SDK samples in TypeScript/Python for:
* Tool registration
* Tool invocation (sync/async/stream)
* Debugging harness
* Publish a set of example tools (jest-runner, eslint-runner, prettier-format) with manifests and test fixtures.
Related pages (stubs to create)
* Inline Assistant: ../ai/inline-assistant.mdx
* Subscription & billing: ../ai/subscription.mdx
* Visual customization: ../general/visual-customization.mdx
* Extensions index: ../extensions/index.mdx
If you'd like, I can:
* Draft the MCP API reference (endpoints, request/response examples) next.
* Generate sample extension code that registers a tool and a matching test harness.
* Create the related stub pages (inline-assistant, subscription, visual-customization, extensions index) to resolve cross-links.
# Available Models
Source: https://docs.oppla.ai/ide/ai/models
Overview of supported AI models (cloud and local), selection guidance, and configuration examples
This page describes Oppla's supported language and reasoning models, guidance for choosing models based on task, and configuration examples. It also includes short stubs and links for related privacy & security and text-threads pages (create separate files for full docs).
## Supported Model Categories
Oppla supports two broad model deployment modes:
* Cloud providers (hosted by third parties)
* OpenAI (GPT family)
* Anthropic (Claude family)
* Google AI (Gemini)
* Azure OpenAI
* AWS Bedrock
* Local / on-prem runtimes
* Ollama
* llama.cpp / GGML-based runtimes
* LM Studio-style local servers
* Custom HTTP endpoints (self-hosted inference)
Each category has tradeoffs in latency, cost, privacy, and reasoning capability. Choose the model that matches your workflow and constraints.
## Recommendations by Task
* Completions & Inline Assist
* Priority: low latency, low cost
* Recommended: small, fast models (small GPT-family, Gemini-lite, local quantized models)
* Refactoring & Code Transformations
* Priority: accuracy and code-understanding
* Recommended: mid-to-large models with strong code capabilities (GPT-4 style, Claude-instant/2)
* Agents & Multi-file Workflows
* Priority: strong reasoning, context handling
* Recommended: larger or specialized models that can handle multi-step planning; consider cloud models for scale or on-prem larger models for privacy
* Test Generation & Explanations
* Priority: correctness & explainability
* Recommended: reasoning-capable models; consider multi-pass (draft + verify) with deterministic tool checks
## Cost, Latency & Privacy Tradeoffs
* Cloud models typically offer best reasoning per token but incur API costs and outbound data considerations.
* Local models reduce outbound data risk and latency for some workflows but may require significant local hardware and maintenance.
* A hybrid strategy often works best: use local/fast models for everyday completions; use powerful cloud models for heavy reasoning tasks when policy permits.
## Model Selection Strategies
* Multi-model strategy: route simple completions to fast models, heavy tasks to powerful models.
* Context window management: larger context windows help for agents and multi-file tasks; but increase cost and latency.
* Adaptive selection: configure default models per task in AI Configuration and allow per-agent overrides.
* Fallbacks: define fallbacks (e.g., if local model unavailable, use approved cloud provider) and surface policy to users.
## Example configuration snippets
Example: default model settings in your user settings file.
```docs/ide/ai/models.mdx#L221-300
{
"ai": {
"default_provider": "ollama",
"providers": {
"openai": {
"default_model": "gpt-4o-mini",
"timeout_ms": 30000
},
"anthropic": {
"default_model": "claude-2.1",
"timeout_ms": 30000
},
"ollama": {
"endpoint": "http://localhost:11434",
"default_model": "llama2-13b-q4"
}
},
"task_model_overrides": {
"completion": "ollama::llama2-13b-q4",
"refactor": "openai::gpt-4o-mini",
"agent_planning": "anthropic::claude-2.1"
}
}
}
```
Notes:
* Use environment variables or OS secret stores for provider keys.
* Keep model choices explicit per task to control cost and behavior.
## Validation & Benchmarking
Before publishing hard performance numbers:
* Run representative benchmarks on target hardware/network.
* Document the test environment (hardware, model version, dataset, date).
* Measure latency, throughput, and failure modes.
## Best Practices
* Prefer "local\_first" on sensitive projects to reduce exfiltration risk.
* Use model-specific temperature and max-token tuning per task.
* Combine models with deterministic tools (linters, test runners) to verify results.
* Record provenance: which model and prompt produced a change.
## Model Safety Controls
* Limit model capabilities via AI Rules (e.g., forbid external network calls, restrict provider usage).
* Use redaction rules to remove secrets or PII before sending context to cloud providers.
* Enable audit logging for all model requests in enterprise installs.
## Related pages (stubs)
The following related pages should exist as separate docs. If they don't yet exist, create them with matching filenames listed below.
* Privacy & Security (stub)
* Filename: ./privacy-and-security.mdx
* Short description: Covers data handling, encryption, local-only modes, audit logs, and enterprise controls.
* Inline stub (brief):
* Oppla supports local-only model modes, OS secret stores, and audit logging. Create a dedicated page (docs/ide/ai/privacy-and-security.mdx) to document:
* What context is sent to providers by default
* How to enable local-only mode
* Secret storage best practices
* Audit/logging and compliance features
* Example: configuration to disable outbound model requests
* Text Threads (stub)
* Filename: ./text-threads.mdx
* Short description: Persistent conversational threads tied to project context (for agent interactions, history, and collaboration).
* Inline stub (brief):
* Text Threads let you have persistent, context-rich chats about code. Create docs/ide/ai/text-threads.mdx to cover:
* Creating and pinning threads
* Linking threads to files or PRs
* Retention and export options
* Privacy controls (who can read / write threads)
## Quick creation checklist (for docs team)
* Create docs/ide/ai/privacy-and-security.mdx with:
* Detailed privacy model
* Local-only configuration examples
* Audit log configuration
* Enterprise controls & RBAC
* Create docs/ide/ai/text-threads.mdx with:
* UX flows, keyboard shortcuts
* Thread lifecycle and retention
* Integration with Agent Panel and PRs
* Keep model docs up to date with provider changes and recommended model names.
***
If you'd like, I can also produce the two separate stub files (privacy-and-security.mdx and text-threads.mdx) content next.
# AI Overview
Source: https://docs.oppla.ai/ide/ai/overview
Oppla's revolutionary AI-first development experience
Oppla isn't just an editor with AI features—it's an AI-first development platform that fundamentally reimagines how developers write, understand, and maintain code. Every aspect of Oppla is designed to amplify your intelligence and accelerate your workflow.
## Why Oppla's AI is Different
While other editors add AI as an afterthought, Oppla is architected from the ground up for seamless AI integration:
* **Context-Aware Intelligence**: Our AI understands your entire codebase, not just the current file
* **Predictive Development**: Anticipates your next actions based on patterns and intent
* **Adaptive Learning**: Personalizes to your coding style and preferences over time
* **Multi-Model Flexibility**: Choose from various AI providers or run models locally
* **Privacy-First Design**: Your code stays secure with granular privacy controls
## Getting Started with AI in Oppla
### Quick Setup (2 minutes)
1. **Open AI Settings**: Press `Cmd-,` (macOS) or `Ctrl-,` (Linux) and navigate to AI
2. **Choose Your Provider**: Select from Anthropic, OpenAI, Google AI, or local models
3. **Enter API Key**: Add your API key (or skip for local models)
4. **Start Coding**: AI features activate automatically!
### Configuration Options
* **[AI Configuration](../configuration/index.mdx)**: Set up different language model providers including Anthropic, OpenAI, Ollama, Google AI, and more
* **[Available Models](./models.mdx)**: Explore the vast selection of language models optimized for different tasks
* **[Subscription Plans](./subscription.mdx)**: Learn about Oppla's flexible subscription options and usage-based billing
* **[Privacy & Security](./privacy-and-security.mdx)**: Understand our industry-leading approach to protecting your code and data
## Core AI Capabilities
### 🤖 Agentic Editing
Transform how you interact with code through intelligent agents that can understand, modify, and create code autonomously:
* **[Agent Panel](./agent-panel.mdx)**: Your AI coding partner that can handle complex, multi-file tasks
* **[AI Rules](./rules.mdx)**: Define custom rules to guide AI behavior for your project
* **[AI Tools](./tools.mdx)**: Powerful tools that give AI agents the ability to search, analyze, and modify your codebase
* **[Model Context Protocol](./mcp.mdx)**: Connect to external tools and services for enhanced AI capabilities
* **[Inline Assistant](./inline-assistant.mdx)**: Get AI help directly in your code without leaving the editor
### ✨ Predictive Intelligence
Experience the future of coding with AI that anticipates your needs:
* **[Edit Prediction](./edit-prediction.mdx)**: Revolutionary AI that predicts and suggests your next edits in real-time
* **Smart Completions**: Context-aware code completion that understands your intent
* **Pattern Recognition**: AI learns your coding patterns and suggests consistent implementations
* **Refactoring Suggestions**: Proactive recommendations for code improvements
### 💬 Conversational Development
Engage with AI through natural language interfaces:
* **[Text Threads](./text-threads.mdx)**: Persistent, context-aware conversations about your code
* **Code Explanations**: Get instant, detailed explanations of complex code
* **Documentation Generation**: AI creates comprehensive docs from your code
* **Learning Assistant**: Ask questions and learn new concepts without leaving Oppla
## Unique Oppla AI Features
### 🎯 Project-Wide Intelligence
Unlike traditional AI assistants that only see the current file, Oppla's AI understands your entire project:
* **Cross-file refactoring** with consistency guarantees
* **Architecture-aware suggestions** that respect your design patterns
* **Dependency tracking** for safe code modifications
* **Test generation** that understands your testing strategy
### 🔮 Predictive Development Flow
Oppla's AI doesn't just respond—it anticipates:
* **Next-step predictions** based on your current task
* **Automatic imports** when you need them
* **Error prevention** before you make mistakes
* **Smart file creation** based on project structure
### 🛡️ Enterprise-Grade Security
Your code is your business. Oppla protects it:
* **Local model support** for air-gapped environments
* **End-to-end encryption** for cloud AI requests
* **Audit logging** for compliance requirements
* **Granular permissions** for team environments
## Real-World Use Cases
### For Individual Developers
* **Learn new languages** with AI guidance
* **Debug complex issues** with AI analysis
* **Refactor legacy code** safely and quickly
* **Generate boilerplate** instantly
* **Write tests** with comprehensive coverage
### For Teams
* **Enforce coding standards** with AI rules
* **Onboard new developers** with AI explanations
* **Review code** with AI-powered insights
* **Document systems** automatically
* **Maintain consistency** across large codebases
### For Enterprises
* **Secure AI deployment** with on-premise options
* **Compliance-ready** with audit trails
* **Custom model training** on your codebase
* **Integration** with existing tools via MCP
* **Scalable** across thousands of developers
## Performance & Efficiency
Oppla's AI is optimized for speed and efficiency:
| Feature | Response Time | Accuracy |
| ------------------ | --------------- | -------- |
| Code Completion | Less than 50ms | 95%+ |
| Inline Suggestions | Less than 100ms | 92%+ |
| Refactoring | Less than 2s | 98%+ |
| Code Explanation | Less than 3s | 96%+ |
| Test Generation | Less than 5s | 90%+ |
## Getting the Most from Oppla AI
### Best Practices
1. **Be specific** in your requests for better results
2. **Use AI rules** to customize behavior for your project
3. **Review suggestions** before accepting—AI is a tool, not a replacement
4. **Provide feedback** to help Oppla's AI improve
5. **Experiment** with different models for different tasks
### Pro Tips
* **Multi-model strategy**: Use fast models for completion, powerful models for complex tasks
* **Context windows**: Keep relevant files open for better AI understanding
* **Custom rules**: Define project-specific AI behaviors
* **Keyboard shortcuts**: Master AI shortcuts for maximum efficiency
* **Local models**: Run models locally for privacy-sensitive projects
## Available AI Providers
Oppla supports a wide range of AI providers to suit every need:
### Cloud Providers
* **Anthropic** (Claude) - Best for complex reasoning
* **OpenAI** (GPT-4) - Versatile and powerful
* **Google AI** (Gemini) - Fast and efficient
* **Azure OpenAI** - Enterprise-ready
* **AWS Bedrock** - Scalable and secure
### Local Options
* **Ollama** - Run models on your machine
* **LM Studio** - User-friendly local models
* **llama.cpp** - Lightweight and fast
* **Custom endpoints** - BYO model deployment
## What's Next?
### Immediate Actions
1. **[Configure your AI provider](../configuration/index.mdx)** - Get started in 2 minutes
2. **[Try the Agent Panel](./agent-panel.mdx)** - Experience autonomous coding
3. **[Enable Edit Prediction](./edit-prediction.mdx)** - Feel the future of development
4. **[Set up AI Rules](./rules.mdx)** - Customize AI for your workflow
### Learn More
* **[Video Tutorials](https://oppla.ai/tutorials)** - See AI features in action
* **[Community Examples](https://community.oppla.ai/ai)** - Learn from other developers
* **[API Documentation](https://docs.oppla.ai/api)** - Build on top of Oppla
* **[Support](mailto:ai@oppla.ai)** - Get help from our AI experts
***
**Join the AI Revolution**
Oppla is more than a tool—it's a paradigm shift in how we write software. Join thousands of developers who are already experiencing the future of AI-powered development.
[Start your free trial →](https://app.oppla.ai/home?tab=download)
# Privacy & Security
Source: https://docs.oppla.ai/ide/ai/privacy-and-security
How Oppla handles AI data, secrets, local models, audit logging, and enterprise controls
This page explains Oppla's privacy and security model for AI features. It covers what context may be shared with AI providers, how to run models locally (local-only mode), secret-management best practices, audit logging, AI Rules for redaction and approvals, and enterprise controls (RBAC, retention, compliance).
If you're evaluating Oppla for sensitive codebases, read this page first and consult your security team. For configuration basics, see: [AI Configuration](./configuration.mdx). For rules and enforcement, see: [AI Rules](./rules.mdx).
## Data flow overview
* Local context collection: Oppla constructs a context window from the active file, open buffers, and an optional set of relevant repository files.
* Local vs. remote decision: Based on your AI settings and AI Rules, Oppla chooses between local runtimes or cloud providers.
* Outbound requests: When using cloud providers, Oppla sends a minimized context payload unless a broader context is explicitly enabled.
* Tool invocations: Agents or tools (linters, test runners) run inside a sandboxed environment; results are kept local unless explicitly uploaded.
Design goals:
* Least privilege: send the minimum required context to providers.
* Auditability: log model requests and agent actions for traceability.
* Configurability: allow per-project and per-user privacy settings.
* Local-first support: prefer local models when policy requires it.
## What Oppla may send to AI providers
By default Oppla aims to minimize exposure. Typical payloads include:
* Short snippets from the active buffer (line range configurable)
* Filenames and contextual metadata (not full repository by default)
* Explicitly included files or folders when agents are asked to run project-wide tasks (only after user confirmation or via approved AI Rules)
Sensitive data that should not be sent without explicit opt-in:
* Secrets (API keys, private keys, tokens, passwords)
* Ever-changing credentials files (e.g., .env)
* Personal data or PII unless explicitly authorized and logged
## Local-only & local-first modes
Local-first: prefer a configured local runtime; fall back to cloud when local is unavailable.
Local-only mode: disallow any outbound requests. Use this mode for air-gapped or highly regulated environments.
Enable local-only via settings (example):
```docs/ide/ai/privacy-and-security.mdx#L1-20
{
"ai": {
"privacy": {
"mode": "local_only", // options: local_only | local_first | cloud_allowed
"send_code": "never" // never | opt_in | opt_out
}
}
}
```
Notes:
* local\_only prevents outbound network calls to cloud providers and mutes automatic fallback behavior.
* In local\_only mode, you must configure and run a local runtime (Ollama, llama.cpp server, etc.) and point Oppla at the endpoint.
## Secret management best practices
* Never check API keys or secrets into source code repositories.
* Use OS-native secret storage:
* macOS: Keychain
* Linux: Secret Service / GNOME Keyring / pass
* Windows: Credential Manager (when supported)
* For CI or automated systems use short-lived tokens and environment variables (OPPLA\_AI\_API\_KEY, etc.)
* When configuring custom endpoints, prefer token-based auth with limited scope.
Example: prefer env vars over inline keys:
```docs/ide/ai/privacy-and-security.mdx#L21-60
{
"ai": {
"providers": {
"openai": {
"api_key_env": "OPENAI_API_KEY"
}
}
}
}
```
## Redaction and AI Rules
Use AI Rules to prevent sensitive files or patterns from being sent to providers. Typical patterns:
* Block files by path globs (e.g., **/\*.env, secret/**)
* Block by regex on content (api\_key|secret|password|token)
* Redact matched content before any outbound request
Example AI Rule for redaction (author as `.oppla/ai-rules.json`):
```docs/ide/ai/rules.mdx#L1-60
{
"version": "1.0",
"rules": [
{
"id": "no-secret-exfiltration",
"type": "privacy",
"match": {
"paths": ["**/*.env", "**/secrets/**"],
"content_regex": "(?i)(api_key|secret|password|token)"
},
"action": {
"on_violation": "redact_and_warn",
"redaction_placeholder": "[REDACTED_SECRET]"
}
}
]
}
```
Behavior:
* Matches trigger redaction before any outbound request.
* Violations are logged; admins can configure whether to block or require approval.
## Audit logging & retention
Oppla supports configurable audit logs for AI requests and agent actions. Logs typically include:
* Who triggered the action (user identity)
* When it occurred (timestamp)
* Which model/provider and model name were used
* What files or ranges were included (redacted as necessary)
* Diffs proposed and applied (if any)
* Approval decisions and approver identity
Retention and export:
* Configure retention policy per-organization (e.g., 90 days, 365 days)
* Support for export to SIEM or centralized logging (S3, Elasticsearch, or similar)
* Secure access control to logs (RBAC)
Example audit settings (high level):
```docs/ide/ai/privacy-and-security.mdx#L61-110
{
"audit": {
"enabled": true,
"retention_days": 365,
"export": {
"type": "s3",
"bucket": "oppla-audit-logs",
"path_prefix": "org-123/"
}
}
}
```
## Enterprise controls (RBAC, approvals, quotas)
* Role-based access control: define roles (owner, maintainer, developer, auditor) and map actions to roles (run agents, approve high-risk changes).
* Approval gates: require human approval for high-risk changes (paths matching infra, auth, deploy).
* Quotas: per-user and per-project quotas for model usage and agent runs to control cost and risk.
* Organization policies: enforce project-wide rules (e.g., local\_only for certain repositories).
## Compliance & regulatory considerations
* GDPR / Data residency: For EU data residency concerns, prefer local-only or region-scoped cloud endpoints. Document what data is transmitted and retention windows.
* SOC2 / ISO: Provide audit trails and access controls to help meet compliance needs.
* Export controls: If operating in jurisdictions with export restrictions, use local-only deployments or approved cloud regions.
Always consult legal/compliance teams before enabling cloud model usage on regulated datasets.
## Tooling & Model Context Protocol (MCP) security
* Tools invoked by agents run in sandboxed environments with limited filesystem access.
* MCP should validate all tool inputs to prevent command injection.
* Tools should run with least privilege and provide dry-run modes.
* Restrict network access for tool containers unless explicitly required and authorized.
## Incident response & breach handling
* If accidental exfiltration is detected:
1. Rotate compromised keys immediately.
2. Revoke tokens and update AI Rules to block the offending patterns.
3. Review audit logs to identify scope of exposure.
4. Notify affected stakeholders per your incident response policy.
* Maintain runbooks for handling model-provider incidents (provider key compromise, unexpected data retention behavior).
## Developer guidance (for extension & tool authors)
* Return structured, non-sensitive outputs where possible.
* Avoid tooling that requires sending full repository contents to external services.
* Respect AI Rules and follow secure defaults (dry-run, audit-only modes).
* Document what data your extension/tool needs and why.
## Troubleshooting & FAQs
Q: How do I ensure nothing leaves my network?
A: Enable `local_only` mode and configure a local runtime or internal model server. Disable cloud providers and verify no fallback is configured.
Q: My agent needs to run tests — will it send test output to the cloud?
A: Only if the agent's workflow or AI Rules allow that. Use project-level rules to disallow outbound sends for test artifacts.
Q: How are audit logs protected?
A: Audit logs are secured by access control and encryption at rest. Configure S3/remote stores behind VPCs or private network access where required.
Q: Can I redact files automatically?
A: Yes — define redaction rules in AI Rules. Oppla will redact before sending context to providers and log the redaction.
## Links & next steps
* AI Configuration: ./configuration.mdx
* AI Rules: ./rules.mdx
* Agent Panel: ./agent-panel.mdx
* Edit Prediction: ./edit-prediction.mdx
* Available Models: ./models.mdx
* Text Threads: ./text-threads.mdx
## Want help?
If you'd like, I can:
* Add UI screenshots for privacy settings and audit-log configuration
* Create a step-by-step onboarding doc for enterprise security teams
* Produce a sample `.oppla/ai-rules.json` set tuned for strict privacy (audit-only, then block)
Please indicate which you'd like me to add next.
# AI Rules
Source: https://docs.oppla.ai/ide/ai/rules
Define project-specific rules that guide Oppla's AI behavior (safety, style, privacy, and automation)
This page is a stub for Oppla's AI Rules feature. AI Rules let teams codify constraints and best practices so Oppla's AI agents, Edit Prediction, and other AI features behave predictably and safely across a codebase.
Use this page to:
* Understand the purpose and types of AI Rules
* See the canonical rule schema and examples
* Learn how rules interact with agents, tools, and models
* Find links to related stubs (Tools, Models, Privacy, Text Threads)
Note: This is an initial technical stub. Full UX screenshots, policy templates, and enforcement guides will be added in subsequent iterations.
## Why AI Rules?
AI Rules provide an auditable, machine-readable way to:
* Prevent the AI from performing unsafe transformations
* Enforce coding standards and style consistency
* Restrict what code and data can be sent to remote providers
* Define approval gates and human-in-the-loop behavior
* Integrate with CI and audit logging for compliance
AI Rules are intended for projects, teams, and enterprises that want deterministic AI-assisted workflows.
## Rule Types
Common rule categories:
* Safety & Security: Disallow edits that remove authentication checks, leak secrets, or expose credentials.
* Privacy & Data Handling: Block or redact code snippets or files from being sent to cloud providers.
* Style & Linting: Enforce formatting, naming, or architectural patterns (e.g., "no var", "use async/await").
* Behavioral Constraints: Limit actions an agent can take (e.g., "no automated commits without approval").
* Resource & Cost Controls: Limit model choices or token usage for specific tasks.
* Approval & Workflow: Require human sign-off for high-risk changes.
## Rule Schema (example)
Rules are authored as structured JSON or YAML in the repository under `.oppla/ai-rules.json` or configured via project settings. Below is a minimal example illustrating safety, privacy, and approval rules.
```docs/ide/ai/rules.mdx#L1-60
{
"version": "1.0",
"metadata": {
"name": "default-project-rules",
"description": "Baseline rules for CI and agent operations",
"created_by": "team-name",
"created_at": "2025-08-01T00:00:00Z"
},
"rules": [
{
"id": "no-secret-exfiltration",
"type": "privacy",
"description": "Prevent sending files that match secret patterns to remote providers",
"match": {
"paths": ["**/*.env", "**/secrets/**", "config/*.yml"],
"content_regex": "(?i)(api_key|secret|password|token)"
},
"action": {
"on_violation": "redact_and_warn",
"redaction_placeholder": "[REDACTED_SECRET]"
}
},
{
"id": "require-human-approval-high-risk",
"type": "approval",
"description": "Require explicit human approval for changes touching infra or auth",
"match": {
"paths": ["infra/**", "auth/**", "deploy/**"]
},
"action": {
"on_violation": "require_approval",
"approval_roles": ["owner", "security_lead"]
}
},
{
"id": "restrict-models-to-local",
"type": "privacy",
"description": "Force local model usage for private monorepo",
"match": {
"projects": ["internal/monorepo"]
},
"action": {
"on_violation": "override_provider",
"allowed_providers": ["ollama", "local_llama"]
}
}
]
}
```
Notes:
* "match" supports glob paths, file-type filters, regex on content, or project-scoped matching.
* "action" defines what the AI system should do when a rule matches: ignore, warn, redact, block, require approval, or override provider/settings.
## Enforcement & Precedence
Rules may exist at multiple scopes:
1. Global defaults (system/organization)
2. Project-level rules (repo `.oppla/ai-rules.json`)
3. User overrides (local settings - for non-binding suggestions)
Precedence:
* More specific scope wins (project-level overrides global).
* Explicit enforcement actions (block, require\_approval) cannot be overridden by users without admin permission.
* Rules marked as "audit-only" will not change behavior but will log violations for review.
## How Rules Interact with Agents, Tools & Models
* Agent Panel: Agents evaluate rules before planning and before applying edits. If a proposed change violates a rule, the agent will either stop, redact, or require approval depending on the rule action.
* Tools (linters, formatters, test runners): Rules can mandate running certain tools as part of an agent workflow (for example, run `eslint` and require zero errors before applying JS changes).
* Model selection: Rules can constrain which models/providers are allowed for a given project or task (e.g., force local models for sensitive projects).
* Model Context Protocol (MCP): Rules can control which external services the MCP can call during an agent run.
## Example: Deny sending PII to cloud providers
An enterprise can create a rule that inspects buffer content for PII patterns and redacts those segments before any outbound request is made. Violations can be logged and flagged for security review.
## Admin Features & Auditability
* Rule authoring UI (planned): A visual editor with test harness to evaluate rules against sample files.
* Audit logs: Every rule match should be logged with context, who triggered the action, and timestamp.
* Approvals: Integrate with SSO / IAM to map approvers to roles.
* Dry-run mode: Validate how rules affect agents without enforcing actions (useful during onboarding).
## Best Practices
* Start with audit-only mode for new rules to measure false positives.
* Use narrow matches before broad regexes; tune incrementally.
* Combine rules: use a privacy rule to redact secrets and a separate approval rule for infra changes.
* Include test fixtures in repo to verify rule behavior as part of CI.
* Document rules in a repository README so contributors understand constraints.
## Troubleshooting
* Rule not firing:
* Check glob/path scope and ensure files match.
* Ensure the project config file is in the repository root or configured project root.
* False positives:
* Narrow the regex or add an allowlist path.
* Switch to audit-only while tuning.
* Overly permissive:
* Use "require\_approval" for high-risk paths until confidence is high.
## Related pages & next steps
Create or consult these stubs for full integration details:
* AI Tools (stub): ./tools.mdx
* Available Models (stub): ./models.mdx
* Privacy & Security (stub): ./privacy-and-security.mdx
* Text Threads (stub): ./text-threads.mdx
* Agent Panel (already stubbed): ./agent-panel.mdx
* AI Configuration (already present): ./configuration.mdx
If you want, I can:
* Create the remaining stubs (tools, models, privacy-and-security, text-threads) so these links resolve.
* Add a rule authoring UI spec and test harness example.
* Add CI example that validates rules as part of PR checks.
***
# Subscription Plans
Source: https://docs.oppla.ai/ide/ai/subscription
Oppla subscription tiers, usage billing, and enterprise options for AI-enabled development
This page summarizes Oppla's subscription and billing model for individual developers, teams, and enterprises using AI features. It explains tiers, usage-based billing, quotas, trial options, and who to contact for enterprise plans.
## Overview
Oppla offers flexible plans to match different needs:
* Free — ideal for exploration, lightweight usage, and open-source contributors
* Individual (Pro) — for power users who want higher quotas, prioritized support, and advanced AI models
* Team — collaboration features, shared quotas, and centralized billing
* Enterprise — on-premise/local deployments, SSO & RBAC, audit logging, and dedicated support
AI features (completions, agents, edit prediction, model-hosting) are metered separately and may be subject to usage-based billing depending on provider and plan.
## Free Tier
* Access to core editor features and basic AI assistance
* Limited daily/monthly inference quota for cloud models
* Local models can be used without cloud billing (subject to hardware)
* Great for testing and onboarding — sign up to start a free trial of Pro features
## Individual (Pro)
* Higher model quotas and priority queuing for cloud requests
* Access to premium models and higher context windows (where available)
* Advanced agent features and extended audit history
* Monthly subscription billed via credit card or invoice (where supported)
Recommended for single developers who rely on AI for productivity and want predictable billing.
## Team
* Centralized team billing and quota pooling
* Role-based access controls and shared workspace limits
* Team admin console for monitoring usage, assigning seats, and policy controls
* Per-seat or pooled billing models (configurable)
Designed for small to medium engineering teams that need collaboration, governance, and cost control.
## Enterprise
* On-premise / air-gapped deployment options and local-only model support
* Enterprise-grade security: audit trails, encryption, SSO (SAML / OIDC), and RBAC
* Custom pricing, committed usage discounts, and dedicated onboarding
* SLA, priority engineering support, and professional services for migration/ops
Contact sales via [enterprise@oppla.ai](mailto:enterprise@oppla.ai) to discuss architecture, procurement, and compliance requirements.
## Usage-Based Billing & Quotas
* Cloud model usage is typically metered by input tokens, output tokens, or inference calls depending on the provider.
* Oppla surfaces usage in the team dashboard with per-user and per-project breakdowns.
* Quotas and soft limits are configurable at org and project level to prevent runaway costs.
* For local models, there is no cloud provider billing from Oppla — only operational costs for hosting models.
## Billing, Invoices & Payments
* Payment methods: Credit card (Stripe), invoicing for eligible teams, and purchase orders for enterprise customers.
* Invoices include line items for subscription seats and usage charges (if applicable).
* Billing portal available for admins to download invoices, update payment methods, and view usage history.
* Contact [billing@oppla.ai](mailto:billing@oppla.ai) for invoice support, tax documents, or billing disputes.
## Trial, Upgrade & Downgrade
* New accounts may be eligible for a free Pro trial for a limited period.
* Upgrades take effect immediately; prorated billing applies when switching plans mid-cycle.
* Downgrades are scheduled at the end of the current billing period to avoid data loss or abrupt quota changes.
* Admins can provision seats and set defaults for team onboarding.
## Enterprise Compliance & Procurement
* We support SOC2/ISO-ready practices for enterprise customers (deployment options and audit logs).
* For regulated environments, Oppla recommends local-only model deployments and review of the Privacy & Security documentation.
* Procurement and contract templates are available on request through [enterprise@oppla.ai](mailto:enterprise@oppla.ai).
## Cost Controls & Best Practices
* Use a multi-model strategy: route cheap, fast models for everyday completions and reserve powerful models for heavy reasoning tasks.
* Configure per-project AI Rules and quotas to prevent accidental data exfiltration and cost spikes.
* Monitor usage dashboards and set alerts for high spend or anomalous usage patterns.
* Prefer local-first or local-only modes for sensitive codebases to minimize cloud provider traffic.
## Support & Escalation
* Self-service: Docs, FAQs, and community forums (see links below)
* Billing & account: [billing@oppla.ai](mailto:billing@oppla.ai)
* Enterprise & sales: [enterprise@oppla.ai](mailto:enterprise@oppla.ai)
* Technical support: [support@oppla.ai](mailto:support@oppla.ai) (or use your team admin console to open tickets)
## Frequently Asked Questions
Q: Are AI model costs included in my subscription?
A: Subscription tiers include seat-level features and baseline quotas. Model inference costs may be usage-based depending on model/provider and plan. Check your plan's detailed pricing page or contact billing.
Q: Can I use my own cloud provider account for model billing?
A: In some enterprise setups, you can route calls through your provider accounts. Contact sales for configuration details and supported providers.
Q: How do I prevent unexpected AI usage?
A: Configure per-project quotas and AI Rules, enable alerts on usage dashboards, and use local-only mode for sensitive projects.
## Related Documentation
* AI Configuration: ./configuration.mdx
* Privacy & Security: ./privacy-and-security.mdx
* Agent Panel & AI Features: ./overview\.mdx, ./agent-panel.mdx
* Extensions & Marketplace: ../extensions/overview\.mdx
***
If you want, I can:
* Add a detailed pricing table with feature-by-feature comparisons for each plan
* Create sample invoices and billing portal screenshots
* Draft enterprise onboarding/checklist for procurement and security reviews
Which of those would you like next?
# Text Threads
Source: https://docs.oppla.ai/ide/ai/text-threads
Persistent, context-aware conversational threads tied to your project and code
Text Threads are persistent, project-scoped conversations that let developers, AI agents, and collaborators discuss code in context. Threads remain attached to specific files, ranges, PRs, or the repository as a whole so conversations stay useful and discoverable over time.
This page is a practical stub that explains core concepts, typical workflows, privacy considerations, keyboard shortcuts, and integration points with Agent Panel and AI features. Full UX screenshots and example GIFs will be added later.
## Key Concepts
* Thread: A persistent conversation that can include humans and AI participants.
* Context: Threads can be linked to files, line ranges, commits, or pull requests. Context provides the AI necessary project awareness.
* Visibility: Threads can be private (project-only), team-visible, or public (if your org allows it).
* Persistence: Threads are stored with configurable retention; audit logs track key events.
* Actions: Threads can trigger agent tasks, create issues, generate PRs, or be pinned to files.
## Typical Workflows
1. Quick code question
* Select a code range, open the Text Thread, ask a question (human or AI reply).
* Accept or apply AI suggestions from the thread into the editor.
2. Agent-driven work
* Start a thread to plan a multi-file refactor.
* Use the Agent Panel to run an agent with the thread as the instruction source.
* Review the agent's staged changes in the thread and approve them.
3. PR-linked discussion
* Link a thread to a PR to keep conversational context with code review comments and AI-suggested fixes.
* Threads can create suggested commits or CI-run requests.
## Creating and Managing Threads
* From the editor: Select code → Right-click → "Start Text Thread" (or use Command Palette).
* From Agent Panel: Create a planning thread to serve as an agent's instruction source.
* From the command line / CLI: use `oppla thread create` (CLI docs TBD).
Example thread creation payload (API/CLI payload example):
```docs/ide/ai/text-threads.mdx#L1-40
{
"title": "Migrate auth module to async",
"context": {
"repo": "my-org/my-repo",
"files": ["src/auth/*.py"],
"file_ranges": [
{ "path": "src/auth/session.py", "start_line": 1, "end_line": 240 }
],
"pr": null
},
"visibility": "team",
"participants": ["alice@example.com"],
"initial_message": "Plan incremental migration to async for auth flows. List steps and potential breaking changes."
}
```
## Linking Threads to Files and PRs
* Attach to a file or range so the thread surfaces when that file is opened.
* Link to a PR so comments and suggested fixes are visible in both places.
* Pin a thread to the Project Panel for high-importance discussions.
## AI Integration
* AI can join a thread as an assistant or be used to summarize long threads.
* Use threads to seed Agent Panel runs — the agent will reference the thread history and approvals.
* AI replies and suggested patches from threads follow AI Rules and privacy settings. See the Privacy & Security page: [Privacy & Security](./privacy-and-security.mdx).
## Permissions, Auditing & Retention
* Thread visibility respects repository and org permissions.
* Actions that apply code changes from a thread require explicit approval (configurable).
* All thread events (creation, edits, agent runs, approvals) are logged for auditability.
* Retention is configurable via org settings; consider compliance requirements when enabling public or long-lived threads.
## Keyboard Shortcuts
* Start thread for selection: Cmd/Ctrl-Shift-T
* Open thread panel: Cmd/Ctrl-Shift-Alt-T
* Reply in thread: Enter
* Pin/unpin thread: Cmd/Ctrl-P
(Shortcuts are configurable in Key Bindings: [Key Bindings](../configuration/key-bindings.mdx))
## Developer & Extension Integration
* Extensions can create, read, and update threads via the Oppla docs API (planned).
* Recommended pattern: expose a dry-run and structured JSON responses for any extension-provided actions that post or modify threads.
* Extensions should respect thread visibility and AI Rules; never post secrets into threads.
Thread message example showing an AI suggestion and a suggested patch:
```docs/ide/ai/text-threads.mdx#L41-80
{
"message_id": "msg-12345",
"author": "oppla-ai",
"type": "suggestion",
"content": "Replace sync function `get_user()` with `async def get_user_async()` and update callers.",
"suggested_patch": {
"file": "src/auth/session.py",
"edits": [
{ "start_line": 12, "end_line": 18, "replacement": "async def get_user_async(...):\n ..." }
]
}
}
```
## Privacy & Security Notes
* Threads may contain code context; use AI Rules to redact or block sensitive content before any outbound request.
* For highly sensitive projects, enable local-only mode: AI will not call cloud providers. See: [Privacy & Security](./privacy-and-security.mdx).
* Admins can configure thread retention and export rules for compliance.
## Troubleshooting
* Thread not visible in file: confirm thread is attached to the exact file path and range; check project visibility settings.
* AI suggestions not shown: verify AI provider configured in AI Configuration: [AI Configuration](./configuration.mdx) and that AI Rules permit the action.
* Thread actions failing to apply patches: ensure user has write permissions and required approvals are granted.
## Related Pages
* AI Overview: [AI Overview](./overview.mdx)
* Agent Panel: [Agent Panel](./agent-panel.mdx)
* AI Rules: [AI Rules](./rules.mdx)
* AI Configuration: [AI Configuration](./configuration.mdx)
* Privacy & Security: [Privacy & Security](./privacy-and-security.mdx)
* Key Bindings: [Key Bindings](../configuration/key-bindings.mdx)
***
This is a stub. Next steps:
* Add UI screenshots and GIFs for thread creation and agent-driven workflows
* Document API endpoints and CLI commands for thread operations
* Provide example workflows for teams and enterprise retention policies
If you'd like, I can create the CLI examples and the API reference pages next.
# AI Tools
Source: https://docs.oppla.ai/ide/ai/tools
How Oppla exposes and integrates external tools for AI agents and workflows
This page is a stub for Oppla's AI Tools documentation. It explains the high-level concepts, how tools are surfaced to AI agents (via the Model Context Protocol), and best practices for tool integration, security, and troubleshooting. Full developer guides and API references will be added soon.
## What are AI Tools?
AI Tools are external commands, services, or extension-provided capabilities that Oppla's AI agents and features can call to gather information, execute code analysis, run tests, or apply transformations. Examples include linters, formatters, test runners, language servers, and custom HTTP services.
Tools extend AI capabilities by providing deterministic operations (run tests, format code, run static analysis) that complement the probabilistic outputs of language models.
## How tools integrate with AI workflows
Oppla uses the Model Context Protocol (MCP) to let models request and receive structured data from external tools. MCP is an abstraction layer that:
* Defines how agents call tools (input/output schemas)
* Controls which tools are available to an agent run
* Enforces sandboxing, timeouts, and resource limits
* Logs tool usage for auditability
Typical flow:
1. Agent composes a plan and identifies required tool calls.
2. Oppla checks AI Rules and project permissions to determine allowed tools and scopes.
3. Requested tools run in a sandboxed environment (local or containerized) and return structured results.
4. The agent uses the results to produce a final proposal (patches, test reports, refactor plan).
## Common types of tools
* Linters and static analyzers (ESLint, Flake8, Clang-Tidy)
* Formatters (Prettier, Black, rustfmt)
* Test runners (pytest, jest, go test)
* Package managers & build tools (npm, pip, cargo)
* Language-specific analysis tools (type checkers, doc generators)
* Custom HTTP services (security scanners, dependency vulnerability APIs)
* CI hooks: create PRs, run CI pipelines, annotate failures
## Example tool usage
* "Run unit tests for module X and return failed tests with stack traces."
* "Run ESLint on changed files and return the top 10 issues grouped by severity."
* "Format the proposed patch with the project's formatter before presenting the diff."
## Security, permissions & privacy considerations
Because tools may access sensitive project data or run commands that modify code, Oppla enforces layered safety controls:
* Scope & permissions: Admins and project owners specify which tools are allowed and which users/roles can invoke them.
* Rule enforcement: AI Rules can block calls to specific tools for certain paths (for example, disallow running network scanners on private code).
* Sandboxing: Tools run in isolated environments with limited file-system access and resource constraints.
* Least privilege: Prefer read-only tool modes when possible (e.g., test-run-only vs. allow-write).
* Audit logging: All tool invocations (who, when, arguments, results) are logged for traceability.
* Secrets handling: Tools should never receive raw secrets unless explicitly allowed and handled through secure channels (secret stores, short-lived tokens).
* Rate limiting & quotas: Prevent runaway tool usage via per-user or per-project quotas.
## Developer integration (for extension authors)
Oppla will provide an API for extensions and internal components to register tools for use by agents and other AI features. Integration points will include:
* Tool registration metadata (name, description, input schema, output schema, recommended timeout)
* Run-time hooks for validation, pre-processing and post-processing of results
* Permission declarations (what scopes the tool requires)
* Test harnesses to validate tool behavior against sample repositories
* Examples: register a `python-test-runner` tool that runs pytest in a temp environment and returns structured JSON of test results
Developer guidance (preview):
* Author tools to return structured JSON rather than free-form text.
* Always include meaningful error codes and messages.
* Provide a dry-run mode to validate behavior without state changes.
* Validate inputs from the MCP layer to avoid command injection.
## Best practices
* Prefer deterministic tools for validation steps (linters, tests) rather than relying solely on model outputs.
* Combine tools with AI reasoning: use the model to generate a patch and tools to verify or refine it.
* Keep tool outputs small and structured for reliable downstream processing.
* Start with audit-only runs for new tools before enabling automatic application of tool-assisted changes.
* Document tool expectations (required binaries, versions, environment variables) in repository docs.
## Troubleshooting
* Tool not available to agent:
* Check project/tool permissions and AI Rules.
* Ensure the tool registration metadata is correct and the tool binary/service is installed.
* Tool runs but fails with environment errors:
* Verify runtime environment (PATH, node/python versions) and containerization settings.
* Ensure necessary project dependencies are installed in the tool's execution environment.
* Unexpected or malformed results:
* Confirm the tool returns the expected schema. Add a post-processing validation step.
* Run the tool manually in the configured environment to replicate the issue.
* Excessive latency:
* Increase tool timeouts with care or pre-run expensive analyses as part of CI and surface results to agents.
## Related pages (stubs & next steps)
* AI Configuration: ./configuration.mdx
* Agent Panel: ./agent-panel.mdx
* AI Rules: ./rules.mdx
* Edit Prediction: ./edit-prediction.mdx
* Models: ./models.mdx
* Privacy & Security: ./privacy-and-security.mdx
* Text Threads: ./text-threads.mdx
* Model Context Protocol (MCP): ./mcp.mdx (planned)
***
If you'd like, I can:
* Create example tool registration JSON and a sample extension that registers a `jest-runner` tool.
* Draft the MCP API spec to show request/response schemas.
* Add a security checklist for tool authors and ops teams.
# Configuration
Source: https://docs.oppla.ai/ide/configuration/index
Central guide to configure Oppla: AI providers, key bindings, themes, and best practices
Welcome to the Configuration hub for Oppla. This page collects the most important configuration topics so you can quickly set up AI providers, customize key bindings, and choose or create themes. Use the quick links below to jump to detailed pages or follow the short walkthrough to get configured in minutes.
Quick links
* Key Bindings: ./key-bindings.mdx
* Themes: ./themes.mdx
* AI Configuration (providers, local models): ../ai/configuration.mdx
* AI Rules, Agent and other AI features: ../ai/overview\.mdx
Getting started (2–5 minutes)
1. Open Preferences → Configuration (or Command Palette → `oppla: Open Settings`).
2. Configure AI provider: choose cloud provider or local runtime. See: ../ai/configuration.mdx
3. Set up key bindings: open ./key-bindings.mdx and pick a base keymap or enable AI-optimized keymap learning.
4. Pick a theme: open ./themes.mdx and enable ai\_adaptive mode if you want automatic theme adjustments.
5. Test: open a file and try an AI action (inline assist / completion) to validate settings.
Where settings live
* GUI: Preferences → Settings → Search for `ai`, `keymap`, or `theme`
* User config file:
* macOS / Linux: \~/.config/oppla/settings.json
* Windows (when supported): %APPDATA%\Oppla\settings.json
Example settings (user-level)
Use environment variables for secrets and prefer OS secret stores. Example snippet (adapt to your environment):
```docs/ide/configuration/index.mdx#L1-60
{
"ai": {
"provider": "openai",
"providers": {
"openai": { "api_key_env": "OPENAI_API_KEY", "default_model": "gpt-4o-mini" },
"ollama": { "endpoint": "http://localhost:11434", "default_model": "llama2-13b" }
},
"privacy": {
"send_code": "opt_in",
"local_model_preferred": true,
"telemetry": false
},
"edit_prediction": { "enabled": true, "local_first": true }
},
"keymap": {
"base_keymap": "VSCode",
"vim_mode": false
},
"theme": {
"mode": "ai_adaptive",
"dark": "Oppla AI Dark",
"light": "Oppla AI Light"
}
}
```
Best practices
* Secrets: Do not embed API keys in repository files. Use OS secret stores or environment variables.
* Local-first: For sensitive codebases enable `local_model_preferred` to avoid outbound context.
* Learning period: Let AI keymap learning run for \~7 days before applying automatic optimizations.
* Multi-model strategy: Use small, fast models for inline completions and larger models for heavy reasoning/agents.
* Audit & rules: Use AI Rules to enforce privacy, approvals, and constraints in team or enterprise repos.
Troubleshooting (quick)
* AI actions failing: Check provider credentials, network connectivity, and OS secret store permissions.
* Slow completions: Toggle `local_first` or switch to a lower-latency local model; reduce context window size.
* Keymap conflicts: Use `dev: Open Key Context View` and run "AI: Analyze Keymap Usage" to surface conflicts.
* Theme readability issues: Use theme overrides to adjust `ai.suggestion.background` and increase contrast for accessibility.
Missing or additional configuration pages
We recommend adding or reviewing these pages (if you maintain docs):
* Advanced keybinding guide: ../advanced/keybindings.mdx
* Visual customization and theme authoring: ../extensions/themes.mdx
* Platform-specific configuration (Linux / Windows guides)
If a referenced page is missing, please create a stub at that path and mark it as "coming soon" so cross-links don't 404.
Security & compliance notes
* Document your data exfiltration policy for cloud providers (what gets sent, retention).
* For enterprise installs, configure audit logging and role-based approval for high-risk agent operations.
* Prefer short-lived credentials or token-based access for custom endpoints.
Want me to fix links automatically?
I can:
* Create a configuration index (this page) and stubs for any missing referenced pages so internal links resolve.
* Run a link audit and list remaining 404s and recommended fixes.
Choose next: create missing stubs, run a link audit, or draft full step-by-step how-tos for AI provider setup.
# Key Bindings
Source: https://docs.oppla.ai/ide/configuration/key-bindings
Customize Oppla's keyboard shortcuts with AI-powered optimization
Oppla features an incredibly flexible key binding system enhanced with AI that learns your habits and suggests optimal configurations. Customize everything to match your muscle memory while discovering new efficiency patterns!
## AI-Optimized Predefined Keymaps
If you're transitioning from another editor, Oppla's AI can help you adapt. Set a `base_keymap` in your [settings file](../configuring-oppla.mdx) and let our AI smooth the transition:
* **VSCode** (default) - Most popular choice with AI enhancements
* **Atom** - Classic bindings with modern AI features
* **Emacs** (Beta) - Power user bindings with AI assistance
* **JetBrains** - IntelliJ-style with predictive shortcuts
* **SublimeText** - Lightweight and fast
* **TextMate** - Mac-native feel
* **AI-Optimized** - Let Oppla's AI create a custom keymap for you
* **None** - Start fresh (disables all default key bindings)
You can also enable `vim_mode` for vim bindings enhanced with AI predictions.
**AI Keymap Learning**: When you select a base keymap, Oppla's AI observes your usage patterns and suggests optimizations. After a week of use, check the command palette for "AI: Suggest Keymap Improvements".
## User Keymaps with AI Assistance
Oppla reads your keymap from `~/.config/oppla/keymap.json`. Open it within Oppla using the keybinding for opening keymaps, or via `oppla: Open Keymap` in the command palette.
The file contains a JSON array of objects with `"bindings"`. Our AI assistant can help you create and optimize these bindings based on your workflow.
### AI-Enhanced Example
```json
[
{
"bindings": {
"ctrl-right": "editor::SelectLargerSyntaxNode",
"ctrl-left": "editor::SelectSmallerSyntaxNode",
"cmd-shift-a": "ai::InlineAssist",
"cmd-enter": "ai::AcceptSuggestion"
}
},
{
"context": "ProjectPanel && not_editing",
"bindings": {
"o": "project_panel::Open",
"a": "ai::AnalyzeFile"
}
},
{
"context": "ai_suggestion_active",
"bindings": {
"tab": "ai::AcceptSuggestion",
"escape": "ai::DismissSuggestion",
"cmd-right": "ai::NextSuggestion",
"cmd-left": "ai::PreviousSuggestion"
}
}
]
```
You can see all of Oppla's default bindings in the default keymaps for [macOS](https://github.com/oppla/oppla/blob/main/assets/keymaps/default-macos.json) or [Linux](https://github.com/oppla/oppla/blob/main/assets/keymaps/default-linux.json).
For debugging custom keymaps, use `dev: Open Key Context View` from the command palette. Our AI will analyze conflicts and suggest resolutions.
### Keybinding Syntax
Oppla matches against sequences of keys typed in order. Each key in the `"bindings"` map is a sequence of keypresses separated with a space.
#### Modifiers
* `ctrl-` The control key
* `cmd-`, `win-` or `super-` Platform modifier (Command on macOS, Windows key on Windows, Super on Linux)
* `alt-` Alt key (Option on macOS)
* `shift-` The shift key
* `fn-` The function key
* `secondary-` Platform-adaptive (cmd on macOS, ctrl on Windows/Linux)
* `ai-` Special modifier for AI commands (maps to cmd-shift by default)
#### AI-Powered Examples
```json
{
"bindings": {
"cmd-k cmd-s": "oppla::OpenKeymap", // Sequential: ⌘-k then ⌘-s
"space e": "editor::Complete", // Type space then e
"ai-space": "ai::SmartComplete", // AI-enhanced completion
"shift shift": "ai::QuickSearch", // Double-tap shift for AI search
"cmd-shift-a": "ai::ExplainCode", // AI code explanation
"alt-enter": "ai::RefactorSelection" // AI-powered refactoring
}
}
```
### Contexts with AI Enhancement
Contexts determine when bindings are active. Oppla's AI can suggest context-specific bindings based on your workflow patterns.
The context tree structure with AI-specific contexts:
```
Workspace os=macos keyboard_layout=com.apple.keylayout.QWERTY ai_active=true
Pane
Editor mode=full extension=py ai_suggestion_active=true
AIPanel mode=chat
Dock
ProjectPanel not_editing
```
#### AI-Specific Contexts
* `ai_suggestion_active` - When AI is showing suggestions
* `ai_panel_focused` - When the AI assistant panel is active
* `ai_refactoring` - During AI-powered refactoring
* `ai_explaining` - While AI is explaining code
* `ai_generating` - During AI code generation
#### Context Expression Examples
```json
{
"context": "Editor && ai_suggestion_active",
"bindings": {
"tab": "ai::AcceptSuggestion",
"cmd-]": "ai::NextSuggestion"
}
},
{
"context": "Editor && mode=full && !ai_suggestion_active",
"bindings": {
"cmd-i": "ai::TriggerInlineAssist"
}
}
```
### AI-Powered Actions
Oppla exposes all functionality as actions, with special AI-enhanced actions:
#### Core AI Actions
* `ai::InlineAssist` - Trigger inline AI assistance
* `ai::AcceptSuggestion` - Accept current AI suggestion
* `ai::ExplainCode` - Explain selected code
* `ai::RefactorSelection` - AI-powered refactoring
* `ai::GenerateTests` - Generate tests for selection
* `ai::OptimizeCode` - Optimize selected code
* `ai::FixErrors` - AI-powered error resolution
* `ai::SmartRename` - Context-aware renaming
#### Action Arguments
Some AI actions accept arguments for customization:
```json
{
"cmd-shift-r": ["ai::Refactor", { "style": "functional" }],
"cmd-shift-t": ["ai::GenerateTests", { "framework": "jest" }],
"cmd-shift-o": ["ai::Optimize", { "focus": "performance" }]
}
```
### Precedence and Conflict Resolution
Oppla's AI intelligently resolves binding conflicts:
1. **Context Specificity**: More specific contexts win
2. **User Priority**: User bindings override defaults
3. **AI Suggestions**: AI detects conflicts and suggests alternatives
4. **Smart Delays**: AI-optimized timing for key sequences
When you have prefix conflicts (e.g., `ctrl-w` and `ctrl-w left`), Oppla's AI learns your typing speed and adjusts the wait time dynamically.
### Non-QWERTY Keyboards with AI Adaptation
Oppla's AI automatically adapts to non-QWERTY layouts:
* **Auto-detection** of keyboard layout
* **Smart remapping** to maintain muscle memory
* **Layout-specific suggestions** for optimal efficiency
* **Cross-layout compatibility** when switching keyboards
Set `use_key_equivalents` to `true` for automatic layout adaptation:
```json
{
"use_key_equivalents": true,
"ai_keyboard_optimization": true
}
```
## AI Keymap Optimization
### Learning Mode
Enable AI learning to get personalized suggestions:
```json
{
"ai_keymap_learning": {
"enabled": true,
"suggest_after_days": 7,
"track_patterns": true,
"optimize_for": ["speed", "ergonomics", "memorability"]
}
}
```
### AI Recommendations
After using Oppla, check for AI recommendations:
1. Open command palette
2. Run "AI: Analyze Keymap Usage"
3. Review suggested optimizations
4. Apply changes with one click
The AI considers:
* **Frequency** of command usage
* **Finger travel** distance
* **Timing patterns** in your workflow
* **Conflict avoidance** with existing bindings
* **Ergonomic factors** for reduced strain
## Quick Tips
1. **Let AI learn**: Use Oppla normally for a week before optimizing
2. **Review suggestions**: Check AI keymap suggestions weekly
3. **Context awareness**: Use context-specific bindings for efficiency
4. **AI shortcuts**: Prioritize AI command bindings for maximum productivity
5. **Experiment**: Try AI-suggested bindings for 48 hours before reverting
For advanced keymap customization and AI training, see our [Advanced Keybinding Guide](../advanced/keybindings.mdx).
# Themes
Source: https://docs.oppla.ai/ide/configuration/themes
Customize Oppla's appearance with AI-optimized themes
Oppla comes with a collection of professionally designed themes, each optimized for AI-assisted coding with enhanced syntax highlighting that makes AI suggestions stand out clearly. Additional themes are available through our extension marketplace.
## Selecting a Theme with AI Recommendations
Access Oppla's intelligent Theme Selector via the command palette with "theme selector: Toggle" (bound to `Cmd-K Cmd-T` on macOS and `Ctrl-K Ctrl-T` on Linux).
As you navigate through the theme list, Oppla applies themes in real-time, and our AI learns your preferences to suggest themes based on:
* Your coding hours (day/night preferences)
* Language-specific optimal themes
* Eye strain reduction patterns
* Personal selection history
## Installing More Themes
Discover additional themes through the Extensions page, accessible via the command palette with "oppla: Extensions" or visit the [Oppla marketplace](https://oppla.ai/extensions).
Many popular themes have been intelligently adapted for Oppla, with AI-enhanced color schemes that improve code readability and reduce cognitive load. Visit [oppla-themes.com](https://oppla-themes.com) for a curated gallery with live previews and AI compatibility ratings.
## Configuring a Theme
Your selected theme preferences are stored in your settings file. Open your settings from the command palette with "oppla: Open Settings" (bound to `Cmd-,` on macOS and `Ctrl-,` on Linux).
Oppla's AI can maintain adaptive themes that automatically adjust based on ambient light, time of day, and your activity patterns:
```json
{
"theme": {
"mode": "ai_adaptive",
"light": "Oppla Light",
"dark": "Oppla Dark",
"ai_optimization": {
"auto_adjust": true,
"eye_strain_reduction": true,
"context_aware_highlighting": true
}
}
}
```
### Theme Modes
* **`"system"`**: Follow system appearance
* **`"dark"`**: Always use dark theme
* **`"light"`**: Always use light theme
* **`"ai_adaptive"`**: Let Oppla's AI optimize theme selection
## Theme Overrides with AI Assistance
Oppla's AI can suggest theme overrides based on your coding patterns. Use the `experimental.theme_overrides` setting to customize specific attributes:
```json
{
"experimental.theme_overrides": {
"editor.background": "#1a1a2e",
"ai.suggestion.background": "#16213e",
"ai.suggestion.border": "#F5A742",
"syntax": {
"comment": {
"font_style": "italic",
"foreground": "#6c757d"
},
"ai_generated": {
"font_style": "bold",
"foreground": "#F5A742"
}
}
}
}
```
### AI-Specific Theme Attributes
Oppla introduces special theme attributes for AI features:
* `ai.suggestion.background` - Background for AI code suggestions
* `ai.suggestion.border` - Border color for AI suggestions
* `ai.inline.hint` - Inline AI hint styling
* `ai.completion.highlight` - AI completion highlighting
## Local Themes
Store custom themes locally by placing them in the `~/.config/oppla/themes` directory. Oppla's AI will analyze your custom themes and suggest improvements for better readability and reduced eye strain.
For example, to create a theme called `my-ai-theme`, create `my-ai-theme.json` in that directory. Oppla will validate the theme and provide AI-powered suggestions for color improvements.
**AI Theme Validation**: When you add a local theme, Oppla's AI automatically analyzes it for:
* Contrast ratios for accessibility
* Color harmony
* Syntax highlighting effectiveness
* Eye strain factors
## AI-Optimized Theme Features
### Intelligent Syntax Highlighting
Oppla's themes include AI-enhanced syntax highlighting that:
* **Emphasizes important code patterns** based on context
* **Dims less relevant code** during focused work
* **Highlights potential issues** before they become errors
* **Adapts colors** based on file type and framework
### Adaptive Brightness
When enabled, Oppla adjusts theme brightness based on:
* Ambient light sensors (on supported hardware)
* Time of day
* Duration of coding session
* Eye strain indicators
### Context-Aware Coloring
Themes can dynamically adjust based on:
* Current programming language
* Project type (web, mobile, backend, etc.)
* Active AI assistance level
* Debugging vs. normal editing mode
## Theme Development
Want to create your own AI-optimized theme? See [Developing Oppla Themes](../extensions/themes.mdx) for comprehensive guidelines on building themes that work seamlessly with Oppla's AI features.
## Recommended Themes for AI Development
Based on user feedback and AI analysis, these themes provide optimal experience for AI-assisted coding:
1. **Oppla AI Dark** - Designed specifically for long AI pair-programming sessions
2. **Oppla AI Light** - High contrast theme for daytime AI collaboration
3. **Neural Network** - Inspired by AI visualization, optimized for ML development
4. **Quantum Code** - Futuristic theme with enhanced AI suggestion visibility
5. **Adaptive Pro** - Fully AI-controlled adaptive theme
Find more AI-optimized themes at [oppla-themes.com](https://oppla-themes.com).
# Configuring Oppla
Source: https://docs.oppla.ai/ide/configuring-oppla
How to configure Oppla: settings file locations, AI providers, keymaps, themes, and CLI configuration
This page explains where Oppla stores its configuration, how to edit settings (GUI and file-based), and provides practical examples for common tasks referenced elsewhere in the docs (key bindings, themes, AI provider setup).
If you're coming from the Getting Started or Key Bindings guide, this is the canonical reference for configuring Oppla.
## Where settings live
Oppla stores configuration at user and project scope. Use the GUI preferences for most tasks or the settings files for automation and reproducibility.
* User settings (per-user)
* macOS / Linux: `~/.config/oppla/settings.json`
* Windows (planned): `%APPDATA%\Oppla\settings.json`
* Project settings (per-repository)
* Repository root: `.oppla/settings.json`
* Project settings override user settings for that repository.
Oppla also uses OS-native secret storage for API keys and sensitive tokens (Keychain, Secret Service, etc.). See the Privacy & Security page for details.
## Open settings
* GUI: Preferences → Settings (or Command Palette → `oppla: Open Settings`)
* File: Open `~/.config/oppla/settings.json` (or project `.oppla/settings.json`) in the editor
Note: Settings can be provisioned by dotfiles or CI when onboarding developers.
## Common configuration areas
### AI providers and models
Configure cloud or local AI providers, preferred models, and privacy options. Use environment variables for secrets (recommended).
Example (user settings snippet):
```json
{
"ai": {
"provider": "openai",
"providers": {
"openai": {
"api_key_env": "OPENAI_API_KEY",
"default_model": "gpt-4o-mini",
"timeout_ms": 30000
},
"ollama": {
"endpoint": "http://localhost:11434",
"default_model": "llama2-13b-q4"
}
},
"privacy": {
"mode": "local_first",
"send_code": "opt_in"
}
}
}
```
Key notes:
* Use `api_key_env` to point to env vars rather than storing keys in files.
* `privacy.mode` can be `local_only`, `local_first`, or `cloud_allowed`.
* Configure task-specific models in `task_model_overrides` (see Available Models page).
### Key bindings / keymaps
Oppla reads user keymaps from `~/.config/oppla/keymap.json`. You can set a `base_keymap` in settings to adopt a familiar layout (VSCode, Emacs, Vim, etc.).
Example:
```json
{
"keymap": {
"base_keymap": "VSCode",
"vim_mode": false,
"ai_keymap_learning": {
"enabled": true,
"suggest_after_days": 7
}
}
}
```
* Open default keymap: Command Palette → `oppla: open default keymap`
* For debugging: run `dev: Open Key Context View`
* To enable AI-optimized learning, allow `ai_keymap_learning.enabled`.
See the Key Bindings guide for syntax and examples.
### Themes & visual customization
Theme preferences live in settings; Oppla supports `ai_adaptive` mode that auto-adjusts based on time of day and activity.
Example:
```json
{
"theme": {
"mode": "ai_adaptive",
"light": "Oppla Light",
"dark": "Oppla Dark",
"experimental.theme_overrides": {
"editor.background": "#0f1724",
"ai.suggestion.background": "#10203a"
}
}
}
```
To load local themes, place theme JSON files under `~/.config/oppla/themes/`.
### CLI settings & installation
* CLI binary (when installed) integrates with your system shell.
* To install CLI on macOS: `oppla: cli install` (creates a symlink to `/usr/local/bin/oppla`)
* For automated installs, prefer signed release assets and verify checksums.
Security note: Avoid piping remote install scripts directly (`curl | sh`) without verifying signatures in production environments.
## Secret management & environment variables
Preferred approaches:
* Local dev: store secrets in OS secret stores (Oppla prompts to save keys securely).
* CI: set provider keys as environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.).
* Project automation: use a secrets manager and reference tokens with `api_key_env`.
Example environment variable reference in settings:
```json
"providers": {
"openai": { "api_key_env": "OPENAI_API_KEY" }
}
```
## Project-level configuration and AI Rules
Project-level AI behavior and enforcement (AI Rules) should live in `.oppla/ai-rules.json` in the repository root. Use project rules to:
* Prevent sending sensitive files to cloud providers
* Require approvals for high-risk paths
* Restrict allowed providers or models
Rules are applied before agent runs or outbound model requests.
## Troubleshooting
* Settings not applied:
* Confirm you're editing the correct scope (user vs. project).
* Restart Oppla or reload the window after manual edits.
* API key errors:
* Verify env var is set and contains a valid key.
* Check OS secret store permissions and that Oppla can read the secret.
* Keymap conflicts:
* Use `dev: Open Key Context View` and run "AI: Analyze Keymap Usage".
* Slow AI responses:
* Switch to `local_first`, reduce context window size, or pick a lower-latency local model.
## Best practices checklist
* Use OS secret stores or environment variables for API keys.
* Start AI keymap learning with a default period (7 days) before applying suggestions.
* Prefer local-first or local-only mode for sensitive codebases.
* Keep project-level rules under source control for reproducibility.
* Document any non-standard settings in the repository README for contributors.
## Related documentation
* Key Bindings: docs/ide/configuration/key-bindings.mdx
* Themes: docs/ide/configuration/themes.mdx
* AI Overview & configuration: docs/ide/ai/overview\.mdx, docs/ide/ai/configuration.mdx
* Privacy & Security: docs/ide/ai/privacy-and-security.mdx
* Agent Panel, Rules, Tools: docs/ide/ai/agent-panel.mdx, docs/ide/ai/rules.mdx, docs/ide/ai/tools.mdx
***
If you want, I can:
* Add step-by-step screenshots for common configuration flows.
* Provide example automation scripts to provision settings for teams.
* Add validation rules and a sample `oppla: validate-config` CLI snippet to check config health.
# Developing Extensions
Source: https://docs.oppla.ai/ide/extensions/developing-extensions
Guidelines for building Oppla-ready extensions and preparing for Oppla-native marketplace
This is a practical starter guide for extension authors who want to build or adapt extensions for Oppla. It covers the extension manifest, recommended outputs and schemas for AI consumption, security and permission guidance, testing tips, and the migration path from Zed-compatible extensions to Oppla-native extensions.
If you're already familiar with Zed's extension APIs, you can continue using the same APIs today. This document focuses on what to do differently to make your extension "AI-ready" and future-proof for Oppla's native marketplace.
Why this matters
* Oppla enables AI agents, rules, and tools to call extensions programmatically. Extensions that expose structured outputs, clear capabilities, and safe execution models will unlock more powerful integrations.
* Building with AI in mind improves automation, testability, and discoverability in Oppla's upcoming native marketplace.
Quick checklist
* [ ] Provide a clear manifest with metadata and capabilities
* [ ] Return structured JSON for programmatic calls (avoid plain text where possible)
* [ ] Declare required permissions and scopes explicitly
* [ ] Add a dry-run mode and idempotent operations for safety
* [ ] Add tests that run in CI and in a sandboxed environment
* [ ] Provide documentation and examples for AI workflows
Extension manifest (example)
Use a concise manifest that declares commands, contributions, and any tool endpoints your extension exposes. Provide a human-readable description and structured capability flags.
```docs/ide/extensions/developing-extensions.mdx#L1-40
{
"name": "oppla-example-extension",
"displayName": "Oppla Example Extension",
"version": "0.1.0",
"publisher": "your-org",
"description": "Adds an example AI-aware code analysis tool and a testable CLI endpoint.",
"capabilities": {
"aiTool": true,
"allowsTooling": ["lint", "format", "test-run"],
"mcpCompatible": true
},
"commands": [
{
"id": "example.runLinter",
"title": "Run Example Linter",
"description": "Runs the linter and returns structured JSON results."
}
],
"permissions": ["read_workspace", "run_commands"]
}
```
Design for structured outputs
* When exposing programmatic tooling (linters, test runners, analyzers), return JSON with a stable schema:
* Use arrays for issues with fields: file, line, col, severity, code, message, suggestion
* Include a machine-friendly `exit_code` and `metadata` block (runtime version, execution time)
* Agents and AI tools can parse these outputs reliably to surface fixes, create PRs, or provide code actions.
Example structured linter output
```docs/ide/extensions/developing-extensions.mdx#L41-80
{
"exit_code": 0,
"metadata": { "tool": "example-linter", "version": "1.2.0", "duration_ms": 340 },
"issues": [
{
"file": "src/foo.js",
"line": 12,
"col": 8,
"severity": "warning",
"code": "EX100",
"message": "Prefer const over var",
"suggestion": { "type": "edit", "range": [12, 8, 12, 11], "replacement": "const" }
}
]
}
```
AI integration patterns
* Provide idempotent, dry-run APIs. Agents should be able to request a preview patch without applying changes.
* Expose a `--dry-run --format=json` mode for CLI tools that returns the same structured schema.
* Provide a short "capability" endpoint (or metadata field) so Oppla can discover what your extension can do without running heavy commands.
Command & tool registration recommendations
* Register commands with explicit schema for arguments and return values.
* If your extension spawns jobs (tests, builds), return job ids and provide a `status` endpoint with structured events (started, progress, finished, artifacts).
Security & permissions
* Declare minimal required permissions. Avoid broad "write" or network scopes unless strictly necessary.
* For tools that run arbitrary code (formatters, test runners), run them sandboxed (container, restricted user) and provide options for admins to restrict what tools can be invoked via agents.
* Document any network calls your extension makes and allow enterprise installs to opt-out or proxy traffic.
Testing & CI
* Provide unit tests for logic and end-to-end tests that run in a sandbox environment.
* Add sample fixtures and a reproducible environment (Dockerfile or setup script).
* Add an "acceptance" test that simulates an agent calling your extension's dry-run endpoint and verifies schema compliance.
Migration & compatibility notes
* Today: Support Zed extension APIs so your extension works in Oppla's integration layer.
* Prepare: Add manifest `capabilities` and structured endpoints as shown above to enable richer Oppla integrations.
* Future: When Oppla native marketplace and SDK are available, you'll be able to register AI-specific hooks, richer MCP integrations, and monetization metadata. Design with a clear separation between UI-only commands and machine-callable tool endpoints.
Publishing & discoverability
* Provide rich metadata (tags, languages, capability flags) so Oppla can recommend extensions based on developer workflows.
* Include examples and "AI-ready" badges in your README showing supported commands and schemas.
Accessibility & UX
* Keep command names clear and brief.
* Provide helpful error messages and fallback guidance for missing dependencies.
* Ensure keyboard navigability and localized strings where applicable.
Resources & next steps
* Create a `README.md` that documents the dry-run JSON schema, CLI examples, and sample invocation patterns.
* Add a `/examples` folder with a minimal repo demonstrating extension usage with Oppla agents and AI workflows.
* If you'd like, we can produce a sample extension scaffold, a test harness for schema validation, and an MCP draft for tool registration.
Feedback & contact
* File issues or feature requests in the docs repo or contact [extensions@oppla.ai](mailto:extensions@oppla.ai) for SDK access and roadmap questions.
# Extensions
Source: https://docs.oppla.ai/ide/extensions/index
Discover, install, and build extensions for Oppla
Oppla ships with deep extension support so you can customize language features, UI themes, developer tools, and AI integrations. This index collects the essential info for users and extension authors: where to find extensions today, how to install and manage them, and how to prepare extensions to be Oppla-native and AI-ready.
Quick links
* Overview & marketplace: [Extensions Overview](./overview.mdx)
* Dev guide: [Developing Extensions](./developing-extensions.mdx)
* Browse online: [https://oppla.ai/extensions](https://oppla.ai/extensions)
* Support: mailto:[extensions@oppla.ai](mailto:extensions@oppla.ai)
Current state: where to get extensions
* Today: Oppla integrates with the Zed extension marketplace and supports installing Zed-compatible extensions out of the box. See the Extensions Overview for details on compatibility and the migration plan.
* Marketplace: The public Oppla extensions gallery (linked above) provides curated, AI-aware extensions, themes, and tools.
* Local & private: You can install extensions from local packages for private or experimental workflows.
Install & manage extensions (quick start)
1. Open the Command Palette (Cmd/Ctrl+Shift+P) → `oppla: Extensions` or open the Extensions view.
2. Install an extension:
```docs/ide/extensions/index.mdx#L1-6
# Install an extension from the CLI (example)
oppla extensions install
```
3. Manage installed extensions: enable/disable per project, view logs, and configure settings from the Extensions view.
4. Debugging: use the extension logs and `dev: Open Key Context View` for keybinding-related extension issues.
Recommended extension categories
* Languages: syntax highlighting, LSP adapters, and language-specific tooling (Python, TypeScript, Rust)
* Themes: AI-aware themes that improve suggestion contrast and readability
* Tools: linters, formatters, test runners (provide structured JSON outputs for MCP)
* Debuggers & runtimes: enhanced debugging integration for complex stacks
* Productivity: file explorers, todo managers, and snippet tools
* AI: tools that expose structured outputs (lint results, test summaries) so Oppla's agents and AI features can consume them
Best practices for extension authors
* Structured outputs: return JSON schemas for any programmatic tool (linters, test runners, formatters). Agents and MCP rely on structured results for deterministic behavior.
* Dry-run & idempotence: provide a dry-run mode so agents can preview proposed patches safely.
* Explicit capabilities: declare capabilities and required scopes in your manifest (see the Developing Extensions guide).
* Security & permissions: minimize permissions by design, document network calls, and support sandboxed execution or dry-run modes.
* Accessibility: ensure UI contributions are keyboard navigable and have proper ARIA labels.
Manifest & output example (see the developer guide for full details)
```docs/ide/extensions/developing-extensions.mdx#L1-40
{
"name": "oppla-example-extension",
"displayName": "Oppla Example Extension",
"version": "0.1.0",
"capabilities": { "aiTool": true, "mcpCompatible": true }
}
```
Preparing for Oppla-native marketplace
* Compatibility: keep supporting Zed-style manifests today so your extension works in Oppla's compatibility layer.
* AI-ready: add machine-callable endpoints (dry-run JSON outputs), declare tool schemas, and register as MCP-compatible where appropriate.
* SDK & monetization: sign up for the developer preview to be first in the Oppla-native marketplace (see the Extensions Overview for preview timing and the waitlist).
Security, privacy & compliance
* Clearly document what data your extension sends externally.
* Respect AI Rules and the project's privacy settings (don't exfiltrate secrets).
* Provide configuration options to disable network calls or run in dry-run-only mode for sensitive projects.
* Follow guidance in the Developing Extensions doc for secure, auditable integrations.
Contribute & support
* Want to get listed or request features for the Oppla marketplace? Contact [extensions@oppla.ai](mailto:extensions@oppla.ai).
* Community: join the forum and share extension ideas or examples (see the Overview for community links).
* Feedback: file docs or feature issues in the docs repository when a cross-link or guide needs improvement.
Next steps for teams
* Users: Explore the Extensions Overview, install popular extensions, and enable per-project settings.
* Authors: Read the Developing Extensions guide and update your manifests to include structured outputs and dry-run modes.
* Ops & security: Review the privacy & AI Rules pages before enabling cloud-model-based extension functionality in sensitive projects.
If you want, I can:
* Generate a sample extension scaffold (manifest + dry-run tool) for Oppla,
* Create example MCP tool manifests for common tools (eslint/jest/prettier),
* Or run a link-check across the IDE docs and produce a report of any remaining references to missing pages.
Which would you like next?
# Extensions & Plugins
Source: https://docs.oppla.ai/ide/extensions/overview
How Oppla leverages Zed's extension ecosystem and future roadmap
## Current: Leveraging Zed's Extension Marketplace
**Right now, Oppla seamlessly integrates with Zed's extensive extension marketplace.** This strategic integration gives you immediate access to:
* **500+ existing extensions** covering languages, themes, and development tools
* **Mature, battle-tested ecosystem** with proven extension quality
* **Full compatibility** with Zed's extension APIs and development patterns
* **Automatic updates** and management through Zed's robust extension system
### How Extensions Work in Oppla
Since Oppla is built on Zed's high-performance foundation, you get:
```bash
# Install extensions exactly as you would expect
oppla extensions install
# Or through Oppla's intuitive settings interface
```
**Key Benefits:**
* **No learning curve** - if you know Zed extensions, you know Oppla
* **Immediate productivity** - access to extensions from day one
* **Quality assurance** - leverage Zed's extension review and testing
* **Future-proof** - seamless path to Oppla's native marketplace
### Popular Extensions Categories
| Category | Examples | Oppla Enhancement |
| ---------- | ------------------------ | --------------------------------------- |
| Languages | Python, Rust, JavaScript | AI-powered code completion and analysis |
| Themes | Dracula, Solarized, Nord | AI-aware syntax highlighting |
| Tools | Git, Docker, Testing | Predictive tool integration |
| Debuggers | GDB, LLDB, Node Debug | AI-assisted debugging |
| Formatters | Prettier, Black, Rustfmt | Smart formatting with AI suggestions |
***
## Future: Oppla Native Extension Marketplace
**We're actively developing Oppla's native extension marketplace** to unlock the full potential of AI-powered development tools.
### 🚀 Coming Soon: Oppla-Native Extension Features
* **AI-Powered Extensions** that leverage Oppla's core AI capabilities
* **Intelligent Extension Recommendations** based on your development patterns
* **Unified Extension Management** across Zed and Oppla ecosystems
* **Performance-Optimized Extensions** designed specifically for Oppla's architecture
* **AI-Assisted Extension Development** tools for extension creators
### 🔄 Our Migration Commitment
When Oppla's native marketplace launches (target Q1 2026):
* **Zero Breaking Changes**: All existing Zed extensions continue working
* **Automatic Compatibility Layer**: Seamless integration of both extension types
* **Gradual Enhancement Path**: Clear upgrade path for extension developers
* **Unified Discovery Experience**: Single interface to find and manage all extensions
**Why This Approach?**
By leveraging Zed's mature extension ecosystem, we can focus on building revolutionary AI features while you enjoy a fully-featured development environment from day one. This isn't a limitation—it's a strategic advantage that ensures stability, quality, and immediate productivity.
### 📝 For Extension Developers
**Current Status (Now)**:
* Develop using Zed's established extension APIs
* Test extensions with Oppla's Zed integration layer
* Join our developer preview program for early access
**Future Roadmap (2025-2026)**:
* Oppla Extension SDK with AI integration capabilities
* Enhanced development tools and templates
* Monetization opportunities through Oppla marketplace
* Priority support and featured placement
### 📈 Timeline & Milestones
* **Q4 2025**: Developer preview of Oppla Extension SDK
* **Q1 2026**: Beta launch of Oppla Extension Marketplace
* **Q2 2026**: Full marketplace launch with migration tools
* **Q3 2026+**: Gradual rollout of AI-powered extension features
## Working with Extensions Today
### Installing Extensions
Access the extension marketplace through:
1. Command Palette: `oppla: Extensions`
2. Menu: Oppla → Extensions
3. Keyboard: `Cmd-Shift-X` (macOS) / `Ctrl-Shift-X` (Linux)
### Managing Extensions
View and manage installed extensions:
* Enable/disable extensions per project
* Configure extension settings
* Update extensions automatically or manually
* View extension logs and diagnostics
### Recommended Extensions for AI Development
These extensions work exceptionally well with Oppla's AI features:
1. **GitHub Copilot** - Complements Oppla's AI with additional suggestions
2. **Error Lens** - Highlights errors that AI can help fix
3. **Todo Tree** - AI can help prioritize and complete TODOs
4. **GitLens** - Enhanced git integration with AI insights
5. **Docker** - AI-assisted container management
## Extension Development
Want to create extensions that work with Oppla today and are ready for our AI-powered future?
### Getting Started
1. Use Zed's extension development framework
2. Follow Oppla's AI-ready guidelines
3. Test with both Zed and Oppla
4. Prepare for AI integration capabilities
### AI-Ready Extension Guidelines
When developing extensions today, consider:
* **Structured data outputs** that AI can interpret
* **Clear command naming** for AI discovery
* **Comprehensive APIs** that future AI can leverage
* **Performance optimization** for AI processing
See [Developing Extensions](developing-extensions.mdx) for detailed guidelines.
## Frequently Asked Questions
### Why use Zed's marketplace instead of building your own?
**Strategic Focus**: By leveraging Zed's proven infrastructure, we can concentrate our resources on revolutionary AI features rather than rebuilding existing functionality. You get the best of both worlds: immediate access to hundreds of extensions plus cutting-edge AI capabilities.
### Will my Zed extensions always work in Oppla?
**Yes!** We're committed to maintaining compatibility. When we launch our native marketplace, it will include a compatibility layer ensuring all Zed extensions continue to function seamlessly.
### Can I develop Oppla-specific extensions now?
**Coming Soon!** While you currently develop using Zed's APIs, we're launching a developer preview program in Q4 2025. Join our waitlist to get early access to Oppla's AI-powered extension SDK.
### How will AI enhance extensions?
Future Oppla extensions will be able to:
* Leverage AI for intelligent code analysis
* Provide context-aware suggestions
* Auto-configure based on project patterns
* Learn from user behavior
* Integrate with Oppla's AI assistant
## Support and Resources
* **Extension Gallery**: [Browse all available extensions](https://oppla.ai/extensions)
* **Developer Docs**: [Extension development guide](developing-extensions.mdx)
* **Community Forum**: [Discuss extensions](https://community.oppla.ai/extensions)
* **Support**: [Get help with extensions](mailto:extensions@oppla.ai)
***
**Join the Future of AI-Powered Extensions**
Sign up for our developer preview program to be among the first to create AI-enhanced extensions for Oppla. [Join the waitlist →](https://oppla.ai/extensions/developer-preview)
# Getting Started
Source: https://docs.oppla.ai/ide/general/getting-started
Welcome to Oppla - Your AI-powered development platform
Welcome to Oppla! We're excited to have you join the future of AI-powered development. This guide will help you get up and running with Oppla's intelligent development environment.
## Download Oppla
### macOS
Download the latest Oppla IDE for macOS from our download page: [https://app.oppla.ai/home?tab=download](https://app.oppla.ai/home?tab=download)
Oppla's AI-enhanced features are optimized for modern macOS systems, providing seamless integration with your development workflow. After downloading and installing, Oppla will intelligently check for updates and notify you when enhancements are available.
### Linux
Download the latest Oppla IDE for Linux from our download page: [https://app.oppla.ai/home?tab=download](https://app.oppla.ai/home?tab=download)
The download page provides packages for various Linux distributions including:
* `.deb` packages for Ubuntu, Debian, and derivatives
* `.rpm` packages for Fedora, RedHat, CentOS, and derivatives
* `.tar.gz` archives for manual installation on any distribution
* AppImage for portable usage
Oppla supports `x86_64` and `AArch64` architectures on common Linux distributions: Ubuntu, Arch, Debian, RedHat, CentOS, Fedora, and more. Our packages automatically configure optimal settings for your specific distribution.
If this script is insufficient for your use case, you run into problems running Oppla, or there are errors in uninstalling Oppla, please see our [Linux-specific documentation](./linux.mdx).
## Command Palette with AI Intelligence
The Command Palette is your gateway to Oppla's AI-powered functionality. It's not just a command runner - it's an intelligent assistant that learns your patterns and suggests actions based on your context. The keybinding is the first one you should familiarize yourself with. To open it, hit: `Cmd+Shift+P` (macOS) or `Ctrl+Shift+P` (Linux).
Try it! Open the Command Palette and type in `new file`. Watch as Oppla's AI not only filters commands but also suggests file types based on your recent work patterns. You should see the list of commands being intelligently filtered to `workspace: new file` along with AI-suggested templates. Hit return and you'll get a new buffer with smart defaults based on your project context.
Any time you see instructions that include commands of the form `oppla: ...` or `editor: ...` and so on, that means you need to execute them in the Command Palette. Our AI assistant will help you discover related commands and workflows.
## CLI with Intelligent Automation
Oppla has a powerful CLI that leverages AI to understand your intent and automate repetitive tasks. On Linux, this comes with the distribution's Oppla package. For macOS, the CLI comes in the same package with the editor binary, and can be installed into the system with the `cli: install` Oppla command which will create a symlink to `/usr/local/bin/oppla`.
Use `oppla --help` to see the full list of capabilities enhanced by AI.
General highlights:
* **Opening another Oppla window with AI context**: `oppla` - Opens with your most recent project context
* **Opening a file or directory with intelligent setup**: `oppla /path/to/entry` (use `-n` to open in a new window) - Oppla automatically configures the workspace based on project type
* **AI-powered stdin processing**: `ps axf | oppla -` - Oppla intelligently formats and highlights the input
* **Starting Oppla with diagnostic AI**: `oppla --foreground` - Runs with AI-powered performance monitoring
* **Clean uninstallation**: `oppla --uninstall` - Safely removes Oppla and optionally preserves your AI training data
## Configure Oppla with AI Assistance
To open your custom settings with AI-powered recommendations for fonts, formatting settings, per-language configurations, and more, use the `Cmd+,` (macOS) or `Ctrl+,` (Linux) keybinding.
Oppla's AI will analyze your coding patterns and suggest optimal settings. To see all available settings with intelligent descriptions, open the Command Palette with `Cmd+Shift+P` and search for `oppla: open default settings`.
You can also explore all configuration options in the [Configuring Oppla](../configuring-oppla.mdx) documentation, where our AI assistant provides personalized recommendations.
## Configure AI in Oppla
Oppla is built from the ground up as an AI-first development platform. Our intelligent features seamlessly integrate throughout the editor, from predictive code completion to context-aware refactoring.
Visit [the AI overview page](./ai/overview.mdx) to learn how to quickly get started with Oppla's advanced AI capabilities, including:
* **Intelligent Code Completion** - Context-aware suggestions that understand your entire project
* **AI Agent Panel** - Your coding assistant that can write, refactor, and explain code
* **Predictive Editing** - Anticipates your next changes based on patterns
* **Smart Refactoring** - AI-powered code improvements that maintain your style
## Set Up Your Key Bindings with AI Optimization
To open your custom keymap with AI-suggested bindings based on your workflow, use the keybinding for opening keymaps.
Oppla's AI can analyze your usage patterns and suggest optimal key binding configurations. To access the default key binding set with intelligent tooltips, open the Command Palette and search for "oppla: open default keymap". See [Key Bindings](./key-bindings.mdx) for more information about our AI-enhanced keyboard optimization.
## Next Steps
Now that you have Oppla installed and configured, here are some recommended next steps to unlock the full power of AI-assisted development:
1. **Set up AI providers** - Configure your preferred language models in [AI Configuration](./ai/configuration.mdx)
2. **Explore AI features** - Discover all the ways AI can accelerate your workflow in [AI Overview](./ai/overview.mdx)
3. **Install extensions** - Enhance Oppla with extensions from our marketplace in [Extensions](../extensions/overview.mdx)
4. **Customize your workspace** - Make Oppla yours with [Visual Customization](./visual-customization.mdx)
Welcome to the future of development with Oppla!
# Linux Installation & Configuration
Source: https://docs.oppla.ai/ide/general/linux
Install Oppla on Linux, system requirements, and safe-install guidance
This guide helps you install and configure Oppla on common Linux distributions, with a focus on AI features, security best practices, and troubleshooting. If you need platform-agnostic configuration, see [Configuring Oppla](../configuring-oppla.mdx).
Warning about commands that pipe to shell:
* Avoid running unverified `curl | sh` commands in production. Prefer downloading signed release artifacts, verifying checksums / signatures, or using distro packages.
Supported distributions
* Officially tested on:
* Ubuntu 20.04 LTS and newer
* Fedora 38 and newer
* Debian 11 and newer
* Arch Linux (rolling)
* openSUSE Tumbleweed
Recommended system baseline
* Architecture: x86\_64 (Intel/AMD) or aarch64 (ARM)
* RAM: 8GB minimum (16GB+ recommended for local models)
* Disk: 2GB for core install, +2–10GB for local models
* GPU: Optional but recommended for local AI inference (NVIDIA with CUDA, AMD with ROCm). Vulkan 1.3 drivers recommended for accelerated workloads.
Installation options
1. Recommended: Download from Official Page
* Download the appropriate package for your distribution from: [https://app.oppla.ai/home?tab=download](https://app.oppla.ai/home?tab=download)
* Available formats:
* `.deb` packages for Ubuntu, Debian, and derivatives
* `.rpm` packages for Fedora, RedHat, CentOS, and derivatives
* `.tar.gz` archives for manual installation
* AppImage for portable usage
* Example installation (deb):
* Download the .deb file from [https://app.oppla.ai/home?tab=download](https://app.oppla.ai/home?tab=download)
* Install: sudo apt install ./oppla-\*.deb
* Example installation (rpm):
* Download the .rpm file from [https://app.oppla.ai/home?tab=download](https://app.oppla.ai/home?tab=download)
* Install: sudo dnf install ./oppla-\*.rpm
2. Manual Installation (tar.gz)
* Download the tar.gz archive from [https://app.oppla.ai/home?tab=download](https://app.oppla.ai/home?tab=download)
* Extract: tar -xzf oppla-\*.tar.gz
* Move to installation directory: sudo mv oppla /opt/
* Create symlink: sudo ln -s /opt/oppla/bin/oppla /usr/local/bin/oppla
3. AppImage (Portable)
* Download the AppImage from [https://app.oppla.ai/home?tab=download](https://app.oppla.ai/home?tab=download)
* Make executable: chmod +x Oppla-\*.AppImage
* Run directly: ./Oppla-\*.AppImage
Uninstall
* If installed via package manager:
* Debian/Ubuntu: sudo apt remove oppla
* Fedora/RPM: sudo dnf remove oppla
* If installed manually (tar.gz):
* Remove installation directory: sudo rm -rf /opt/oppla
* Remove symlink: sudo rm /usr/local/bin/oppla
* Optional: Remove config: rm -rf \~/.config/oppla
Post-install: CLI and Desktop integration
* The install process attempts to add a symlink at /usr/local/bin/oppla for CLI usage.
* If the CLI is missing, run: sudo ln -s /opt/oppla/bin/oppla /usr/local/bin/oppla (adjust paths to your install).
* Desktop entries: the installer registers a .desktop file for GNOME/KDE to show Oppla in application menus.
Required desktop portals & runtime dependencies
* Oppla relies on standard desktop portals for full functionality:
* org.freedesktop.portal.FileChooser (file dialogs)
* org.freedesktop.portal.OpenURI (links)
* org.freedesktop.portal.Secret or org.freedesktop.Secrets (secure storage)
* Install xdg-desktop-portal and the appropriate backend for your environment:
* Ubuntu/Debian: sudo apt install xdg-desktop-portal xdg-desktop-portal-gtk
* Fedora: sudo dnf install xdg-desktop-portal xdg-desktop-portal-gtk
GPU & AI runtime notes
* NVIDIA: install CUDA toolkit and drivers; enable CUDA-enabled runtimes for local models.
* AMD: enable ROCm where supported; verify compatibility with your distribution.
* Apple-style hardware: not applicable on Linux; use aarch64 builds on compatible ARM machines.
* If you plan to run large local models, ensure swap or disk-based cache is configured and monitor memory usage.
Local model runtimes
* Local runtimes Oppla supports (examples):
* Ollama (local server)
* llama.cpp / GGML frontends
* Custom HTTP endpoints (self-hosted inference)
* To use a local runtime:
* Install and run your chosen runtime (see that runtime's docs)
* Point Oppla at the local endpoint in AI settings (Command Palette → `oppla: Open AI Settings`)
Security & verification
* Verify release signatures and checksums for any downloaded artifacts.
* For enterprise deployment, use private, signed package repositories.
* Avoid storing API keys in project files. Use OS secret stores or environment variables:
* Export: export OPENAI\_API\_KEY="sk\_xxx"
* Or store via Secret Service / GNOME Keyring integration.
Network & firewall considerations
* For cloud AI providers and extension updates, ensure outbound HTTPS (ports 443) to provider endpoints.
* For air-gapped environments, enable local-only mode in AI settings to prevent outbound requests.
Troubleshooting
* Install fails with missing libraries:
* Check distro-specific dependency packages (glibc, libgtk, libvulkan)
* Oppla won't start:
* Run the binary from terminal to capture logs: /opt/oppla/oppla --verbose
* Check \~/.config/oppla/logs/ for runtime errors
* AI features are slow:
* Use `local_first` in AI settings, or switch to a lower-latency local model
* Reduce context window or close unrelated buffers
* Local model not reachable:
* Verify the runtime is running and reachable (curl [http://localhost:PORT/health](http://localhost:PORT/health))
* Check firewall / localhost bindings
Developer & advanced usage
* Running Oppla in development or build-from-source mode is documented in the main development guide (see docs root).
* To build from source on Linux, ensure build dependencies are installed and consult docs/development.mdx.
Related documentation (stubs to create / review)
* Configuring Oppla: ../configuring-oppla.mdx
* Visual customization (create stub at ./visual-customization.mdx) — covers workspace layout, theming UX, and adaptive theme tips.
* Advanced keybindings (create stub at ../advanced/keybindings.mdx) — deep-dive into keymap syntax, debugging, and migration guides.
* AI Configuration & Privacy: ../ai/configuration.mdx and ../ai/privacy-and-security.mdx
Want me to create the missing stub pages (visual-customization and advanced keybindings) now? They will resolve several internal links and prevent 404s across the IDE docs.
# System Requirements
Source: https://docs.oppla.ai/ide/general/system-requirements
Hardware and software requirements for running Oppla's AI-powered development platform
## Apple
### macOS
Oppla's AI-powered features are optimized for modern macOS systems. We support the following macOS releases:
| Version | Codename | Apple Status | Oppla Status | AI Features |
| ------------- | -------- | -------------- | ------------------- | ----------- |
| macOS 15.x | Sequoia | Supported | Fully Supported | Full AI |
| macOS 14.x | Sonoma | Supported | Fully Supported | Full AI |
| macOS 13.x | Ventura | Supported | Fully Supported | Full AI |
| macOS 12.x | Monterey | EOL 2024-09-16 | Supported | Full AI |
| macOS 11.x | Big Sur | EOL 2023-09-26 | Partially Supported | Limited AI |
| macOS 10.15.x | Catalina | EOL 2022-09-12 | Partially Supported | Basic AI |
| macOS 10.14.x | Mojave | EOL 2021-10-25 | Unsupported | None |
> **Note:** The macOS releases labeled "Partially Supported" (Big Sur and Catalina) have limited AI collaboration features. Advanced screen sharing and real-time AI pair programming features require macOS 12 (Monterey) or newer for optimal performance.
### Mac Hardware
Oppla's intelligent features leverage modern hardware capabilities. We support machines with Intel (x86\_64) or Apple Silicon (aarch64) processors that meet the above macOS requirements:
* **MacBook Pro** (Early 2015 and newer) - AI features optimized for M-series chips
* **MacBook Air** (Early 2015 and newer) - Best AI performance on M1/M2/M3 models
* **MacBook** (Early 2016 and newer)
* **Mac Mini** (Late 2014 and newer) - Excellent for AI model processing
* **Mac Pro** (Late 2013 or newer) - Ideal for large-scale AI operations
* **iMac** (Late 2015 and newer)
* **iMac Pro** (all models) - Superior AI computation capabilities
* **Mac Studio** (all models) - Premium AI performance
> **AI Performance Note:** Apple Silicon (M1, M2, M3) processors provide significantly enhanced AI inference speeds, up to 3x faster than Intel-based Macs for certain AI operations.
## Linux
Oppla's AI engine supports 64-bit Intel/AMD (x86\_64) and 64-bit ARM (aarch64) processors, bringing intelligent development to Linux users.
### Requirements
Oppla requires:
* **Vulkan 1.3 driver** - For accelerated AI rendering and computation
* **8GB RAM minimum** (16GB recommended for optimal AI performance)
* **2GB available disk space** for core installation
* **Additional 2-4GB** for AI models (downloaded on first use)
### Required Desktop Portals
The following desktop portals are required for full functionality:
* `org.freedesktop.portal.FileChooser` - For intelligent file selection
* `org.freedesktop.portal.OpenURI` - For smart link handling
* `org.freedesktop.portal.Secret` or `org.freedesktop.Secrets` - For secure AI API key storage
### Recommended Distributions
Oppla's AI features are tested and optimized on:
* Ubuntu 20.04 LTS and newer
* Fedora 38 and newer
* Arch Linux (rolling release)
* Debian 11 and newer
* openSUSE Tumbleweed
## Windows
> **Coming Soon:** Native Windows support is under active development. Our AI-powered features are being optimized for Windows 11's advanced capabilities.
>
> For early access, you can [build from source](../development/windows.mdx).
## FreeBSD
Not yet available as an official download. Advanced users can [build from source](../development/freebsd.mdx).
## Web
> **Future Development:** We're exploring web-based access to Oppla's AI capabilities. This would allow you to use Oppla's intelligent features from any device with a modern browser.
>
> Track progress on our [Platform Support roadmap](https://github.com/oppla/oppla/issues/platform-support).
## AI Model Requirements
### Local AI Processing
For optimal local AI model performance:
* **RAM**: 16GB minimum, 32GB recommended
* **GPU**: Optional but recommended for faster inference
* NVIDIA GPUs with CUDA support
* Apple Silicon GPUs (automatic on M-series Macs)
* AMD GPUs with ROCm support (Linux)
* **Storage**: 10GB+ for larger language models
### Cloud AI Processing
For cloud-based AI features:
* **Internet**: Stable broadband connection (10 Mbps+)
* **Latency**: Less than 100ms to AI servers for best experience
* **API Keys**: Valid credentials for chosen AI providers
## Performance Recommendations
### For Best AI Experience
* **Apple Silicon Macs**: Native optimization provides fastest AI inference
* **NVIDIA GPU Systems**: Enable CUDA acceleration for 5-10x speed improvements
* **High-Speed SSD**: Reduces model loading times significantly
* **32GB+ RAM**: Allows running larger, more capable AI models locally
### Network Requirements
Oppla's AI features can work offline with local models, but for the full experience:
* Stable internet for cloud AI providers
* Low latency for real-time AI collaboration
* Sufficient bandwidth for model downloads (first-time setup)
# Visual Customization
Source: https://docs.oppla.ai/ide/general/visual-customization
Customize Oppla's appearance, themes, icons, fonts, and workspace layout for an optimal AI-assisted development experience
This guide helps you tailor Oppla's visual experience — from themes and syntax highlighting to panel layouts, icons, fonts, and accessibility options. It explains quick actions, configuration snippets, accessibility checks, and best practices so you and your team get a predictable, readable UI that works well with AI features.
Why this matters
* Visual clarity improves comprehension and reduces cognitive load when using AI suggestions.
* Consistent styling helps teams review AI-generated diffs and makes automated suggestions easier to validate.
* Accessibility ensures everyone can use Oppla effectively (contrast, font sizes, keyboard navigation).
Quick links
* Theme configuration: ../configuration/themes.mdx
* Key bindings (shortcuts): ../configuration/key-bindings.mdx
* AI styling & accessibility: ../ai/privacy-and-security.mdx
* Extensions & theme development: ../extensions/developing-extensions.mdx
## 1 — Getting started: Pick or enable an adaptive theme
Oppla ships with AI-aware themes and an adaptive mode that can switch themes based on time of day, ambient conditions, or your activity. To enable adaptive themes:
1. Open Preferences → Settings → Theme
2. Choose mode: `system`, `dark`, `light`, or `ai_adaptive`
3. Optionally set light/dark fallbacks
Example (user settings snippet)
```docs/ide/configuring-oppla.mdx#L1-60
{
"theme": {
"mode": "ai_adaptive",
"light": "Oppla Light",
"dark": "Oppla Dark",
"experimental.theme_overrides": {
"editor.background": "#0f1724",
"ai.suggestion.background": "#10203a",
"ai.suggestion.border": "#F5A742"
}
}
}
```
Tip: Use `ai_adaptive` on laptops to reduce eye strain during long sessions. The AI recommends theme adjustments when enabled.
## 2 — Theme overrides & AI-specific colors
Oppla supports custom theme attributes to highlight AI suggestions distinctly from user code. Use `experimental.theme_overrides` to tweak these attributes.
Common AI-specific tokens:
* `ai.suggestion.background` — background color for AI suggestion blocks
* `ai.suggestion.border` — border for suggestion previews
* `ai.inline.hint` — inline hint text color
* `ai.completion.highlight` — highlight for accepted AI completions
Example theme override (local theme file)
```docs/ide/configuration/themes.mdx#L1-40
{
"name": "my-ai-theme",
"colors": {
"editor.background": "#0b1220",
"editor.foreground": "#dbe7ff",
"ai.suggestion.background": "#122033",
"ai.suggestion.border": "#F5A742",
"ai.inline.hint": "#9fb2ff"
}
}
```
Store local themes in `~/.config/oppla/themes/` and restart Oppla (or reload themes from the command palette) to load them.
## 3 — Workspace layout & panels
Optimize panel layout for AI workflows:
* Recommended layout for agent-heavy workflows:
* Left: Project tree / Explorer
* Center: Editor (multi-tab)
* Right: Agent Panel / Text Threads
* Bottom: Terminal / Test Runner / Output
* Top: Command Palette (pop-up)
Use the View menu or drag panels to create and save workspace layouts. Save workspace presets for different tasks (development, code review, debugging).
Keyboard-driven layout changes
* Use the Command Palette (`Cmd/Ctrl+Shift+P`) and search "Layout: Save Workspace" or "Layout: Toggle Panel".
## 4 — Fonts, ligatures, and sizing
Choose fonts that maximize code readability at your preferred size. Recommended fonts:
* Inter / Inter UI (UI & variable fonts)
* JetBrains Mono (monospace, excellent for ligatures)
* Fira Code (popular with ligatures)
* Source Code Pro (classic, wide support)
Performance tip: When using Edit Prediction and inline AI hints, prefer a monospaced font with clear punctuation to avoid subtle glyph confusion in suggested edits.
Example font settings
```docs/ide/configuring-oppla.mdx#L61-120
{
"editor": {
"fontFamily": "JetBrains Mono, Menlo, monospace",
"fontSize": 14,
"fontLigatures": true,
"lineHeight": 1.5
}
}
```
## 5 — Icons & file decorations
File icons help quick visual parsing of repositories. You can:
* Enable built-in icon set (Preferences → Appearance → File Icons)
* Install or enable icon extensions via the marketplace (see ../extensions/overview\.mdx)
* Configure badge styles for AI-suggested edits, lint errors, and test status in the Tree view
## 6 — Accessibility checklist
Before shipping a theme or recommending a team-wide layout, validate these items:
* Contrast ratios: Ensure foreground/background pass WCAG AA (4.5:1 for normal text). Use automated checks on theme colors.
* Focus outlines: Keyboard focus must be visible for panels and interactive controls.
* Scalable UI: UI scales properly when font sizes or OS scaling changes.
* High-contrast mode: Provide a high-contrast variant or follow OS high-contrast settings.
* Screen reader labels: Panels and controls should expose accessible names.
Accessibility testing action items:
* Run an automated contrast checker on theme palette.
* Manually test keyboard-only navigation for common flows (open file, accept AI suggestion, run agent).
* Validate screen reader output on macOS VoiceOver and Linux Orca where possible.
## 7 — Visual treatment for AI content (guidelines)
Design recommendations when highlighting AI-generated content:
* Use a subtle background tint rather than saturated color.
* Provide a clear "suggested by AI" label with optional source model/provider metadata for transparency.
* Use borders and small icons (e.g., a robot spark) to distinguish AI suggestions from user edits.
* Provide dismiss and accept affordances inline (Tab = accept by default, Esc = dismiss), configurable in keybindings. See ../configuration/key-bindings.mdx.
## 8 — Themes for collaboration & reviews
When teams review AI-generated patches, prefer themes that:
* Keep diffs clear (strong color separation for additions/deletions).
* Highlight language-specific tokens (function names, types) consistently.
* Emphasize comments and TODOs (so reviewers can spot unsafe auto-changes quickly).
## 9 — Creating a theme for Oppla marketplace
If you plan to publish themes, follow these best practices:
* Provide a README with accessibility notes (contrast checks & font guidance).
* Include a "Preview" image and alt text.
* Expose `ai.*` token overrides to make your theme AI-friendly.
* Test your theme with common languages in Oppla and show before/after screenshots.
## 10 — Troubleshooting & tips
* Theme not applying? Restart Oppla or reload the window.
* Inline hints overlap code? Adjust `editor.lineHeight` and `ai.inline.hint` spacing in theme overrides.
* Suggestions hard to see on your monitor: tweak `ai.suggestion.border` and `ai.suggestion.background` for stronger separation.
* Want team consistency? Store a recommended theme file in your repo under `.oppla/theme.json` and document a "Use this theme" step in your CONTRIBUTING.md.
Related pages & next steps
* Themes: ../configuration/themes.mdx
* Key bindings & shortcuts: ../configuration/key-bindings.mdx
* AI Configuration: ../ai/configuration.mdx
* Extensions & theme development: ../extensions/developing-extensions.mdx
* Accessibility & privacy: ../ai/privacy-and-security.mdx
If you want, I can:
* Produce ready-to-use theme JSON files (dark/light/high-contrast).
* Generate screenshot assets and alt text for the theme gallery.
* Create a linter/checker that validates contrast ratios for custom themes.
# Introduction
Source: https://docs.oppla.ai/index
Welcome to Oppla Documentation
## What is Oppla?
Oppla is an all-in-one platform for businesses looking to track user behavior, optimize workflows, and make data-driven decisions. Whether you're a marketer, product manager, or part of a customer success team, Oppla provides the tools you need to succeed.
Track user behavior, analyze sessions, and make data-driven decisions
Create interactive user guides and onboarding experiences
## Key Features
Deep insights into how users interact with your product or campaigns
Automatically generate OKRs, tasks, and strategic documents
Create onboarding flows, product tours, and multi-step user journeys
Shared dashboards, whiteboards, and Kanban boards for team alignment
Create interactive user guides and onboarding experiences
Manage and control your tours
Set up and configure your tours
Identify and track users in your tours
## Getting Started
Follow these steps to begin using Oppla:
1. Install Oppla on your website
2. Identify your users
3. Track events and user behavior
4. Create your first tour
Learn how to add Oppla to your website
Set up user identification for better tracking
# Getting Started with Oppla
Source: https://docs.oppla.ai/quickstart
Learn how to get started with Oppla's analytics and journey features
# Getting Started with Oppla
Welcome to Oppla! This guide will help you get started with our platform's core features.
## Installation
To begin using Oppla, you'll need to:
1. Create an Oppla account
2. Add Oppla to your website
3. Set up user identification
4. Start tracking events
### Adding Oppla to Your Website
Add the following script to your website's `` section:
```html
```
### Identifying Users
To track user behavior effectively, identify your users:
```javascript
oppla('identify', {
userId: 'user_123',
traits: {
name: 'John Doe',
email: 'john@example.com',
plan: 'premium'
}
});
```
## Key Features
### Analytics
Oppla's analytics features help you understand user behavior:
* Track page views and events
* Analyze user sessions
* Compare metrics over time
* Set up custom data tags
### Journey
Create guided user experiences:
* Design onboarding flows
* Create product tours
* Set up multi-step user journeys
* Customize step types (tooltips, modals, banners)
## Next Steps
1. [Add your website](/analytics/add-website)
2. [Track your first event](/analytics/track-events)
3. [Create a tour](/tours/overview)
Learn how to track and analyze user behavior
Create interactive user guides and onboarding experiences
# Tour Analytics
Source: https://docs.oppla.ai/tours/analytics
Learn how to track and analyze tour performance in Oppla
# Tour Analytics
Learn how to track and analyze tour performance using Oppla's analytics features.
## Basic Usage
### Track Tour Events
```javascript
import { createTour } from '@oppla-ai/tours';
const tour = createTour({
id: 'feature-tour',
steps: [
{
type: 'tooltip',
target: '#feature-button',
content: 'Try our new feature!'
}
],
analytics: {
trackViews: true,
trackInteractions: true
}
});
tour.start();
```
### Track Custom Events
```javascript
{
type: 'tooltip',
target: '#feature-button',
content: 'Try our new feature!',
analytics: {
trackEvent: 'feature_tooltip_shown',
properties: {
feature_name: 'new-feature',
step_index: 0
}
}
}
```
## Advanced Features
### Track User Interactions
```javascript
{
type: 'tooltip',
target: '#feature-button',
content: 'Try our new feature!',
onShow: () => {
window.oppla.track('tooltip_shown', {
tour_id: 'feature-tour',
step_index: 0
});
},
onClick: () => {
window.oppla.track('tooltip_clicked', {
tour_id: 'feature-tour',
step_index: 0
});
}
}
```
### Track Tour Progress
```javascript
{
type: 'tooltip',
target: '#feature-button',
content: 'Try our new feature!',
onComplete: () => {
window.oppla.track('tour_step_completed', {
tour_id: 'feature-tour',
step_index: 0,
time_spent: 5000 // milliseconds
});
}
}
```
## Best Practices
1. **Be Consistent**: Use consistent event names and properties
2. **Be Specific**: Track meaningful user interactions
3. **Be Organized**: Group related events logically
4. **Be Clean**: Remove unused tracking code
## Common Issues
### Events Not Tracking
* Check event names
* Verify properties
* Check initialization
* Ensure proper timing
### Data Quality
* Validate event data
* Check for duplicates
* Monitor event volume
* Review property values
## Next Steps
Learn about tooltip steps
Learn about modal steps
# Banners
Source: https://docs.oppla.ai/tours/banner
Learn how to create and customize banners in Oppla tours
# Banners
Learn how to create and customize banners to display important announcements or notifications in your tours.
## Basic Usage
### Create a Banner
```javascript
import { createTour } from '@oppla-ai/tours';
const tour = createTour({
id: 'announcement-tour',
steps: [
{
type: 'banner',
content: 'New feature available!'
}
]
});
tour.start();
```
### Banner with Options
```javascript
{
type: 'banner',
content: 'New feature available!',
position: 'top',
duration: 5000,
closable: true,
type: 'info' // 'info', 'success', 'warning', 'error'
}
```
## Customization
### Styling
Customize banner appearance:
```javascript
{
type: 'banner',
content: 'New feature available!',
style: {
backgroundColor: '#ffffff',
color: '#000000',
padding: '12px 24px',
boxShadow: '0 2px 4px rgba(0,0,0,0.1)',
borderRadius: '4px'
}
}
```
### Content
Add rich content to banners:
```javascript
{
type: 'banner',
content: `
New Feature Available
Check out our latest update!
`,
allowHTML: true
}
```
## Advanced Features
### Interactive Banners
Add interactive elements to banners:
```javascript
{
type: 'banner',
content: `
Would you like to enable notifications?
`,
allowHTML: true,
onClose: () => {
// Handle banner close
}
}
```
### Conditional Banners
Show banners based on conditions:
```javascript
{
type: 'banner',
content: 'Welcome to our premium features!',
showIf: {
type: 'user-property',
property: 'plan',
value: 'premium'
}
}
```
## Best Practices
1. **Be Brief**: Keep banner content short and clear
2. **Be Visible**: Ensure banners are noticeable but not intrusive
3. **Be Timely**: Show banners at appropriate moments
4. **Be Dismissible**: Allow users to close banners
## Common Issues
### Banner Not Showing
* Check initialization
* Verify content is valid
* Check for z-index conflicts
* Ensure proper positioning
### Styling Issues
* Check CSS conflicts
* Verify responsive design
* Check for overflow issues
* Ensure proper positioning
## Next Steps
Learn about tooltip steps
Learn about modal steps
# Compare Tours
Source: https://docs.oppla.ai/tours/compare
Learn how to compare tour performance in Oppla
# Compare Tours
Learn how to compare tour performance and analyze metrics in Oppla.
## Basic Usage
### Compare Tour Metrics
```javascript
import { createTour, TourManager } from '@oppla-ai/tours';
// Create tour manager
const manager = new TourManager();
// Compare tour metrics
const comparison = manager.compare({
tours: ['feature-tour', 'onboarding-tour'],
metrics: ['completion_rate', 'average_time'],
timeRange: 'last_30_days'
});
```
### Compare Tour Steps
```javascript
// Compare specific steps
const stepComparison = manager.compare({
tours: ['feature-tour', 'onboarding-tour'],
steps: [0, 1],
metrics: ['view_count', 'interaction_rate']
});
```
## Advanced Features
### Compare with Filters
```javascript
// Compare with filters
const filteredComparison = manager.compare({
tours: ['feature-tour', 'onboarding-tour'],
metrics: ['completion_rate'],
filters: {
userSegment: 'premium',
deviceType: 'desktop',
timeRange: 'last_7_days'
}
});
```
### Compare with Custom Metrics
```javascript
// Compare with custom metrics
const customComparison = manager.compare({
tours: ['feature-tour', 'onboarding-tour'],
metrics: [
'completion_rate',
'average_time',
{
name: 'custom_metric',
calculation: (data) => {
return data.interactions / data.views;
}
}
]
});
```
## Best Practices
1. **Be Specific**: Compare relevant metrics
2. **Be Consistent**: Use consistent time ranges
3. **Be Clear**: Document comparison logic
4. **Be Accurate**: Validate comparison data
## Common Issues
### Comparison Not Working
* Check tour IDs
* Verify metrics
* Check time ranges
* Ensure proper data
### Data Quality
* Validate metrics
* Check for outliers
* Verify calculations
* Review time periods
## Next Steps
Learn about tooltip steps
Learn about modal steps
# Disable Tracking
Source: https://docs.oppla.ai/tours/disable-tracking
Learn how to disable tracking in Oppla tours
# Disable Tracking
Learn how to disable tracking in your tours for development or testing purposes.
## Basic Usage
### Disable Tracking Globally
```javascript
import { createTour, TourManager } from '@oppla-ai/tours';
// Create tour manager
const manager = new TourManager();
// Configure to disable tracking
manager.configure({
tracking: {
enabled: false
}
});
```
### Disable Tracking for Specific Tour
```javascript
// Create a tour with tracking disabled
const tour = createTour({
id: 'feature-tour',
steps: [
{
type: 'tooltip',
target: '#feature-button',
content: 'Try our new feature!'
}
],
tracking: {
enabled: false
}
});
```
## Advanced Features
### Conditional Tracking
```javascript
// Create a tour with conditional tracking
const tour = createTour({
id: 'feature-tour',
steps: [
{
type: 'tooltip',
target: '#feature-button',
content: 'Try our new feature!'
}
],
tracking: {
enabled: process.env.NODE_ENV === 'production'
}
});
```
### Selective Tracking
```javascript
// Create a tour with selective tracking
const tour = createTour({
id: 'feature-tour',
steps: [
{
type: 'tooltip',
target: '#feature-button',
content: 'Try our new feature!',
tracking: {
enabled: false
}
},
{
type: 'modal',
content: 'Welcome to our app!',
tracking: {
enabled: true
}
}
]
});
```
## Best Practices
1. **Be Consistent**: Use consistent tracking settings
2. **Be Clear**: Document tracking configuration
3. **Be Secure**: Protect sensitive data
4. **Be Efficient**: Only track necessary events
## Common Issues
### Tracking Not Disabled
* Check configuration
* Verify environment
* Check for overrides
* Ensure proper initialization
### Data Privacy
* Review tracked data
* Check for sensitive information
* Verify compliance
* Monitor data usage
## Next Steps
Learn about tooltip steps
Learn about modal steps
# Fork Steps
Source: https://docs.oppla.ai/tours/fork
Learn how to create and customize fork steps in Oppla tours
# Fork Steps
Learn how to create and customize fork steps to create branching paths in your tours based on user actions or conditions.
## Basic Usage
### Create a Fork Step
```javascript
import { createTour } from '@oppla-ai/tours';
const tour = createTour({
id: 'feature-tour',
steps: [
{
type: 'fork',
conditions: [
{
condition: () => document.querySelector('#premium-feature') !== null,
steps: [
{
type: 'tooltip',
target: '#premium-feature',
content: 'Try our premium feature!'
}
]
},
{
condition: () => true,
steps: [
{
type: 'tooltip',
target: '#basic-feature',
content: 'Try our basic feature!'
}
]
}
]
}
]
});
tour.start();
```
### Fork with Options
```javascript
{
type: 'fork',
conditions: [
{
condition: () => user.isPremium,
steps: [
{
type: 'tooltip',
target: '#premium-feature',
content: 'Premium feature available!'
}
]
},
{
condition: () => true,
steps: [
{
type: 'tooltip',
target: '#basic-feature',
content: 'Basic feature available!'
}
]
}
],
defaultSteps: [
{
type: 'tooltip',
target: '#default-feature',
content: 'Default feature available!'
}
]
}
```
## Advanced Features
### User Action Forks
Create forks based on user actions:
```javascript
{
type: 'fork',
conditions: [
{
condition: () => userAction === 'click',
target: '#upgrade-button',
steps: [
{
type: 'modal',
content: 'Would you like to upgrade?'
}
]
},
{
condition: () => userAction === 'click',
target: '#learn-more-button',
steps: [
{
type: 'modal',
content: 'Learn more about our features'
}
]
}
]
}
```
### Complex Conditions
Create forks with complex conditions:
```javascript
{
type: 'fork',
conditions: [
{
condition: () => {
return user.isPremium && user.hasCompletedOnboarding;
},
steps: [
{
type: 'tooltip',
target: '#advanced-feature',
content: 'Try our advanced feature!'
}
]
},
{
condition: () => user.isPremium,
steps: [
{
type: 'tooltip',
target: '#premium-feature',
content: 'Complete onboarding to unlock advanced features!'
}
]
}
]
}
```
## Best Practices
1. **Be Clear**: Make conditions easy to understand
2. **Be Logical**: Use clear branching logic
3. **Be Fallback**: Always provide a default path
4. **Be Maintainable**: Keep conditions simple and well-documented
## Common Issues
### Fork Not Working
* Check condition logic
* Verify target elements exist
* Check for timing issues
* Ensure proper event handling
### User Experience
* Avoid complex branching
* Provide clear feedback
* Handle edge cases
* Consider fallback options
## Next Steps
Learn about tooltip steps
Learn about modal steps
# Tour Management
Source: https://docs.oppla.ai/tours/management
Learn how to manage and control tours in Oppla
# Tour Management
Learn how to manage and control tours in your application using the Oppla tours package.
## Basic Usage
### Initialize Tours
```javascript
import { createTour, TourManager } from '@oppla-ai/tours';
// Create a tour
const tour = createTour({
id: 'feature-tour',
steps: [
{
type: 'tooltip',
target: '#feature-button',
content: 'Try our new feature!'
}
]
});
// Initialize tour manager
const manager = new TourManager();
// Register tour
manager.register(tour);
```
### Start and Stop Tours
```javascript
// Start a tour
manager.start('feature-tour');
// Stop a tour
manager.stop('feature-tour');
// Pause a tour
manager.pause('feature-tour');
// Resume a tour
manager.resume('feature-tour');
```
## Advanced Features
### Tour Events
Listen to tour events:
```javascript
manager.on('start', (tourId) => {
console.log(`Tour ${tourId} started`);
});
manager.on('stop', (tourId) => {
console.log(`Tour ${tourId} stopped`);
});
manager.on('step', (tourId, stepIndex) => {
console.log(`Tour ${tourId} moved to step ${stepIndex}`);
});
```
### Tour State
Get tour state:
```javascript
// Check if tour is running
const isRunning = manager.isRunning('feature-tour');
// Get current step
const currentStep = manager.getCurrentStep('feature-tour');
// Get tour progress
const progress = manager.getProgress('feature-tour');
```
### Multiple Tours
Manage multiple tours:
```javascript
// Register multiple tours
manager.register(tour1);
manager.register(tour2);
manager.register(tour3);
// Start all tours
manager.startAll();
// Stop all tours
manager.stopAll();
// Get all registered tours
const tours = manager.getTours();
```
## Best Practices
1. **Be Organized**: Keep tour IDs consistent and meaningful
2. **Be Efficient**: Only register tours when needed
3. **Be Responsive**: Handle tour events appropriately
4. **Be Clean**: Clean up tours when they're no longer needed
## Common Issues
### Tour Not Starting
* Check tour registration
* Verify tour ID
* Check for conflicts
* Ensure proper initialization
### Tour State Issues
* Check event handlers
* Verify state management
* Check for race conditions
* Ensure proper cleanup
## Next Steps
Learn about tooltip steps
Learn about modal steps
# Modals
Source: https://docs.oppla.ai/tours/modal
Learn how to create and customize modals in Oppla tours
# Modals
Learn how to create and customize modals to display important information or collect user input in your tours.
## Basic Usage
### Create a Modal
```javascript
import { createTour } from '@oppla-ai/tours';
const tour = createTour({
id: 'welcome-tour',
steps: [
{
type: 'modal',
content: 'Welcome to our application!'
}
]
});
tour.start();
```
### Modal with Options
```javascript
{
type: 'modal',
content: 'Welcome to our application!',
title: 'Welcome',
width: '500px',
height: 'auto',
closeButton: true,
overlay: true
}
```
## Customization
### Styling
Customize modal appearance:
```javascript
{
type: 'modal',
content: 'Welcome to our application!',
style: {
backgroundColor: '#ffffff',
color: '#000000',
borderRadius: '8px',
padding: '24px',
boxShadow: '0 4px 6px rgba(0,0,0,0.1)'
}
}
```
### Content
Add rich content to modals:
```javascript
{
type: 'modal',
content: `
Welcome to Our App
Get started by exploring our features.
`,
allowHTML: true
}
```
## Advanced Features
### Interactive Modals
Add interactive elements to modals:
```javascript
{
type: 'modal',
content: `
`,
allowHTML: true,
onClose: () => {
// Handle modal close
}
}
```
### Conditional Modals
Show modals based on conditions:
```javascript
{
type: 'modal',
content: 'Welcome to our premium features!',
showIf: {
type: 'user-property',
property: 'plan',
value: 'premium'
}
}
```
## Best Practices
1. **Be Clear**: Keep modal content focused and concise
2. **Be Responsive**: Ensure modals work well on all screen sizes
3. **Be Accessible**: Include proper keyboard navigation
4. **Be Consistent**: Use consistent styling and behavior
## Common Issues
### Modal Not Showing
* Check initialization
* Verify content is valid
* Check for z-index conflicts
* Ensure proper event handling
### Styling Issues
* Check CSS conflicts
* Verify responsive design
* Check for overflow issues
* Ensure proper positioning
## Next Steps
Learn about tooltip steps
Learn about banner steps
# Tours Overview
Source: https://docs.oppla.ai/tours/overview
Learn about Oppla's tour functionality for creating interactive user guides
# Tours Overview
Learn how to create interactive user guides and onboarding experiences using Oppla's tour functionality.
## What are Tours?
Tours are interactive guides that help users learn about your application's features. They can include:
* Tooltips highlighting specific elements
* Modal dialogs explaining features
* Banners for announcements
* Wait steps for user actions
* Fork steps for conditional paths
## Installation
Install the Oppla Tours package:
```bash
npm install @oppla-ai/tours
# or
yarn add @oppla-ai/tours
```
## Basic Usage
### Initialize Tours
```javascript
import { initTours } from '@oppla-ai/tours';
// Initialize tours
initTours({
projectId: 'YOUR_PROJECT_ID',
apiKey: 'YOUR_API_KEY'
});
```
### Create a Simple Tour
```javascript
import { createTour } from '@oppla-ai/tours';
// Create a tour
const tour = createTour({
id: 'welcome-tour',
name: 'Welcome Tour',
steps: [
{
type: 'tooltip',
target: '#signup-button',
content: 'Click here to create your account'
},
{
type: 'modal',
content: 'Welcome to our platform! Let us show you around.'
}
]
});
// Start the tour
tour.start();
```
## Tour Components
### Tooltips
Highlight specific elements with tooltips:
```javascript
{
type: 'tooltip',
target: '#feature-button',
content: 'This feature helps you...',
placement: 'right'
}
```
### Modals
Show modal dialogs for important information:
```javascript
{
type: 'modal',
content: 'Welcome to our new feature!',
title: 'New Feature',
buttons: [
{
text: 'Got it',
action: 'next'
}
]
}
```
### Banners
Display announcements and notifications:
```javascript
{
type: 'banner',
content: 'New features available!',
style: 'info',
duration: 5000
}
```
## Advanced Features
### Wait Steps
Wait for user actions before proceeding:
```javascript
{
type: 'wait',
target: '#complete-profile',
event: 'click',
timeout: 30000
}
```
### Fork Steps
Create conditional paths based on user actions:
```javascript
{
type: 'fork',
conditions: [
{
type: 'user-property',
property: 'plan',
value: 'premium',
next: 'premium-features'
},
{
type: 'user-property',
property: 'plan',
value: 'free',
next: 'upgrade-prompt'
}
]
}
```
## Best Practices
1. **Keep it Short**: Focus on essential features
2. **Be Clear**: Use simple, concise language
3. **Test Thoroughly**: Verify all steps work correctly
4. **Monitor Progress**: Track completion rates
## Next Steps
Learn about tooltip steps
Learn about modal steps
# Tour Setup
Source: https://docs.oppla.ai/tours/setup
Learn how to set up and configure tours in Oppla
# Tour Setup
Learn how to set up and configure tours in your application using the Oppla tours package.
## Installation
### Install Package
```bash
npm install @oppla-ai/tours
```
### Import Package
```javascript
import { createTour, TourManager } from '@oppla-ai/tours';
```
## Basic Setup
### Initialize Tour Manager
```javascript
// Create tour manager
const manager = new TourManager();
// Configure global settings
manager.configure({
debug: false,
defaultOptions: {
showProgress: true,
showControls: true
}
});
```
### Create a Tour
```javascript
// Create a tour
const tour = createTour({
id: 'feature-tour',
steps: [
{
type: 'tooltip',
target: '#feature-button',
content: 'Try our new feature!'
}
]
});
// Register tour
manager.register(tour);
```
## Advanced Setup
### Custom Styling
```javascript
// Configure global styles
manager.configure({
styles: {
tooltip: {
backgroundColor: '#ffffff',
color: '#000000',
borderRadius: '4px',
padding: '12px'
},
modal: {
backgroundColor: '#ffffff',
color: '#000000',
borderRadius: '8px',
padding: '24px'
}
}
});
```
### Custom Controls
```javascript
// Configure custom controls
manager.configure({
controls: {
showPrevious: true,
showNext: true,
showClose: true,
showProgress: true,
customButtons: [
{
text: 'Skip',
onClick: (tour) => tour.stop()
}
]
}
});
```
## Best Practices
1. **Be Organized**: Keep tour IDs consistent and meaningful
2. **Be Efficient**: Only register tours when needed
3. **Be Responsive**: Handle tour events appropriately
4. **Be Clean**: Clean up tours when they're no longer needed
## Common Issues
### Setup Not Working
* Check package installation
* Verify imports
* Check initialization
* Ensure proper configuration
### Styling Issues
* Check CSS conflicts
* Verify style properties
* Check for missing styles
* Ensure proper specificity
## Next Steps
Learn about tooltip steps
Learn about modal steps
# Tooltips
Source: https://docs.oppla.ai/tours/tooltip
Learn how to create and customize tooltips in Oppla tours
# Tooltips
Learn how to create and customize tooltips to highlight specific elements in your application.
## Basic Usage
### Create a Tooltip
```javascript
import { createTour } from '@oppla-ai/tours';
const tour = createTour({
id: 'feature-tour',
steps: [
{
type: 'tooltip',
target: '#feature-button',
content: 'Click here to access this feature'
}
]
});
tour.start();
```
### Tooltip with Options
```javascript
{
type: 'tooltip',
target: '#feature-button',
content: 'Click here to access this feature',
placement: 'right',
arrow: true,
offset: 10,
delay: 0
}
```
## Customization
### Styling
Customize tooltip appearance:
```javascript
{
type: 'tooltip',
target: '#feature-button',
content: 'Click here to access this feature',
style: {
backgroundColor: '#ffffff',
color: '#000000',
borderRadius: '4px',
padding: '12px',
boxShadow: '0 2px 4px rgba(0,0,0,0.1)'
}
}
```
### Positioning
Control tooltip placement:
```javascript
{
type: 'tooltip',
target: '#feature-button',
content: 'Click here to access this feature',
placement: 'right', // 'top', 'right', 'bottom', 'left'
arrow: true,
offset: 10,
container: '#tooltip-container' // Optional container element
}
```
## Advanced Features
### Interactive Tooltips
Add interactive elements to tooltips:
```javascript
{
type: 'tooltip',
target: '#feature-button',
content: `
New Feature
Click here to access this feature
`,
allowHTML: true
}
```
### Conditional Tooltips
Show tooltips based on conditions:
```javascript
{
type: 'tooltip',
target: '#feature-button',
content: 'Click here to access this feature',
showIf: {
type: 'user-property',
property: 'plan',
value: 'premium'
}
}
```
## Best Practices
1. **Be Concise**: Keep tooltip content short and clear
2. **Be Specific**: Target elements precisely
3. **Be Consistent**: Use consistent styling and placement
4. **Be Accessible**: Ensure tooltips are keyboard accessible
## Common Issues
### Tooltip Not Showing
* Check target element exists
* Verify target selector is correct
* Check for z-index conflicts
* Ensure proper initialization
### Positioning Issues
* Check container boundaries
* Verify placement options
* Check for overflow issues
* Ensure proper offset values
## Next Steps
Learn about modal steps
Learn about banner steps
# Wait Steps
Source: https://docs.oppla.ai/tours/wait
Learn how to create and customize wait steps in Oppla tours
# Wait Steps
Learn how to create and customize wait steps to pause your tour until certain conditions are met.
## Basic Usage
### Create a Wait Step
```javascript
import { createTour } from '@oppla-ai/tours';
const tour = createTour({
id: 'feature-tour',
steps: [
{
type: 'wait',
duration: 2000 // Wait for 2 seconds
}
]
});
tour.start();
```
### Wait with Options
```javascript
{
type: 'wait',
duration: 2000,
message: 'Loading...',
showSpinner: true
}
```
## Advanced Features
### Wait for Element
Wait for an element to appear:
```javascript
{
type: 'wait',
target: '#feature-button',
timeout: 5000,
message: 'Waiting for feature to load...'
}
```
### Wait for Condition
Wait for a custom condition:
```javascript
{
type: 'wait',
condition: () => {
return document.querySelector('#feature-button') !== null;
},
timeout: 5000,
message: 'Waiting for feature to be ready...'
}
```
### Wait for User Action
Wait for user interaction:
```javascript
{
type: 'wait',
userAction: 'click',
target: '#feature-button',
message: 'Please click the button to continue'
}
```
## Best Practices
1. **Be Clear**: Provide clear messages about what you're waiting for
2. **Be Patient**: Set reasonable timeouts
3. **Be Helpful**: Show loading indicators when appropriate
4. **Be Fallback**: Provide fallback behavior if conditions aren't met
## Common Issues
### Wait Not Completing
* Check condition logic
* Verify target element exists
* Check timeout values
* Ensure proper event handling
### User Experience
* Avoid long wait times
* Provide clear feedback
* Handle timeouts gracefully
* Consider fallback options
## Next Steps
Learn about tooltip steps
Learn about modal steps
## What is Oppla?
Oppla is an all-in-one platform for businesses looking to track user behavior, optimize workflows, and make data-driven decisions. Whether you're a marketer, product manager, or part of a customer success team, Oppla provides the tools you need to succeed.
