API Overview
Lokus provides a comprehensive API architecture that spans multiple layers, from the Tauri backend to the frontend plugin system. This document provides a high-level overview of the entire API surface.
Architecture Layers
1. Tauri Backend (Rust)
The Tauri backend provides the core native functionality through Rust commands that are invoked from the frontend JavaScript/TypeScript code.
Key Modules:
- File System Operations - Read, write, create, delete files and folders
- Workspace Management - Session state, workspace validation, and persistence
- Plugin System - Plugin installation, management, and execution
- MCP Server - Model Context Protocol server lifecycle management
- Gmail Integration - OAuth authentication and email operations
- Task Management - Task creation, querying, and extraction
- Search - Full-text search across workspace files
- Clipboard - Cross-platform clipboard operations
- Platform Services - OS-specific features and capabilities
2. Frontend JavaScript API
The frontend provides high-level abstractions and utilities for building Lokus functionality.
Core Modules:
- Editor API - TipTap editor extensions and commands
- Shortcuts Registry - Keyboard shortcut management
- Theme Manager - Theme customization and switching
- Config Store - Application configuration persistence
- Plugin Manager - Frontend plugin lifecycle
- Wiki Links - Internal linking and resolution
- Graph Engine - Knowledge graph rendering and analysis
3. Plugin API
Lokus provides a powerful plugin system that allows extending functionality without modifying core code.
Plugin Capabilities:
- Access to file system operations
- Editor manipulation and extensions
- UI panel registration
- Custom data providers
- MCP tool integration
- Event system hooks
4. MCP Server API
The Model Context Protocol server provides AI assistant integration through a standardized protocol.
MCP Features:
- File and workspace tools
- Note manipulation
- Search capabilities
- Editor commands
- Custom resource providers
API Invocation Patterns
Backend Commands (Rust → JavaScript)
import { invoke } from '@tauri-apps/api/core';
// Example: Read file content
const content = await invoke<string>('read_file_content', {
path: '/path/to/file.md'
});
// Example: List plugins
const plugins = await invoke<PluginInfo[]>('list_plugins');
Event System
import { listen } from '@tauri-apps/api/event';
// Listen for shortcuts updated event
await listen('shortcuts:updated', (event) => {
console.log('Shortcut updated:', event.payload);
});
// Emit custom event
import { emit } from '@tauri-apps/api/event';
await emit('lokus:save-file');
Plugin Registration
// Plugin manifest (plugin.json)
{
"name": "example-plugin",
"version": "1.0.0",
"main": "index.js",
"permissions": [
"read:files",
"write:files",
"ui:editor"
]
}
// Plugin entry point (index.js)
export default class ExamplePlugin {
activate(context) {
// Plugin initialization
context.registerCommand('example:command', () => {
// Command implementation
});
}
deactivate() {
// Cleanup
}
}
API Categories
File Operations
read_workspace_files
- Recursive directory listingread_file_content
- Read file as stringwrite_file_content
- Write string to filecreate_file_in_workspace
- Create new filecreate_folder_in_workspace
- Create new folderrename_file
- Rename file or foldermove_file
- Move file to different directorydelete_file
- Delete file or folderreveal_in_finder
- Open file manager at pathopen_terminal
- Open terminal at path
Workspace Management
save_last_workspace
- Persist workspace pathclear_last_workspace
- Clear saved workspacevalidate_workspace_path
- Validate workspace directoryget_validated_workspace_path
- Get and validate saved workspaceclear_all_workspace_data
- Reset workspace datasave_session_state
- Save open tabs and UI stateload_session_state
- Restore session state
Plugin System
list_plugins
- Get all installed pluginsinstall_plugin
- Install from ZIP or directoryuninstall_plugin
- Remove pluginget_plugin_info
- Get plugin metadataenable_plugin
- Activate plugindisable_plugin
- Deactivate pluginget_enabled_plugins
- List active pluginsvalidate_plugin_manifest
- Validate plugin.jsonset_plugin_permission
- Configure permissionsget_plugin_permissions
- Read permissionsset_plugin_setting
- Store plugin configget_plugin_setting
- Read plugin configread_plugin_file
- Read plugin file contentget_plugin_manifest
- Read plugin.json
MCP Server
mcp_start
- Start MCP server processmcp_stop
- Stop MCP servermcp_status
- Get server statusmcp_restart
- Restart servermcp_health_check
- Check server health
Gmail Integration
gmail_initiate_auth
- Start OAuth flowgmail_complete_auth
- Complete OAuth with codegmail_check_auth_callback
- Poll for auth completiongmail_is_authenticated
- Check auth statusgmail_logout
- Clear credentialsgmail_get_profile
- Get user profilegmail_list_emails
- List emails with filtersgmail_search_emails
- Search with querygmail_get_email
- Get single emailgmail_send_email
- Send new emailgmail_reply_email
- Reply to emailgmail_forward_email
- Forward emailgmail_mark_as_read
- Mark emails as readgmail_mark_as_unread
- Mark emails as unreadgmail_star_emails
- Add star to emailsgmail_unstar_emails
- Remove stargmail_archive_emails
- Archive emailsgmail_delete_emails
- Delete emailsgmail_get_labels
- Get label listgmail_get_queue_stats
- Get operation queue statsgmail_force_process_queue
- Force queue processinggmail_clear_queue
- Clear operation queue
Task Management
create_task
- Create new taskget_all_tasks
- List all tasksget_task
- Get task by IDupdate_task
- Update task propertiesdelete_task
- Delete taskget_tasks_by_status
- Filter by statusget_tasks_by_note
- Get tasks in notebulk_update_task_status
- Update multiple statusesextract_tasks_from_content
- Parse tasks from markdown
Search Operations
search_in_files
- Full-text search across workspacesearch_in_file
- Search within single fileget_file_content_with_lines
- Get file with line numbersbuild_search_index
- Build search index for workspace
Clipboard Operations
clipboard_write_text
- Write plain textclipboard_read_text
- Read plain textclipboard_write_html
- Write HTML contentclipboard_read_html
- Read HTML contentclipboard_has_text
- Check if clipboard has textclipboard_clear
- Clear clipboardclipboard_write_text_enhanced
- Enhanced text writeclipboard_read_text_enhanced
- Enhanced text readclipboard_write_html_enhanced
- Enhanced HTML writeclipboard_get_content_info
- Get content metadataclipboard_get_platform_info
- Get platform capabilitiesclipboard_get_usage_tips
- Get usage recommendationsclipboard_clear_enhanced
- Enhanced clear operation
Platform Services
get_platform_information
- Get OS and platform detailscheck_platform_feature_support
- Check feature availabilityget_platform_capabilities
- Get platform capabilitiesget_system_information
- Get detailed system infocheck_system_capability
- Check specific capability
Theme Management
theme_broadcast
- Broadcast theme changes
Error Handling
All Tauri commands return Result<T, String>
where errors are serialized as strings. Frontend code should handle errors appropriately:
try {
const result = await invoke('some_command', { param: value });
// Success handling
} catch (error) {
console.error('Command failed:', error);
// Error handling
}
Type Safety
Lokus uses TypeScript for type-safe API interactions. Define interfaces for complex types:
interface PluginInfo {
manifest: PluginManifest;
path: string;
enabled: boolean;
installed_at: string;
size: number;
}
interface PluginManifest {
name: string;
version: string;
description: string;
author: string;
main: string;
permissions: string[];
dependencies?: Record<string, string>;
keywords?: string[];
repository?: string;
homepage?: string;
license?: string;
}
Performance Considerations
- Debounce file operations - Avoid rapid successive writes
- Batch operations - Use bulk commands when available
- Cache read operations - Store frequently accessed data
- Lazy load plugins - Only load when needed
- Async/await properly - Don’t block the UI thread
- Clean up listeners - Remove event listeners when unmounting
Security
- All file operations are sandboxed to workspace directories
- Plugin permissions are strictly enforced
- No arbitrary code execution without plugin manifest
- OAuth tokens are stored securely using platform APIs
- Network requests require explicit permissions
Next Steps
- Tauri Commands Reference - Detailed command documentation
- Plugin API Reference - Plugin development guide
- MCP Server API - MCP protocol integration
- Gmail API - Email integration guide
- Keyboard Shortcuts - Shortcut reference
- Configuration - Configuration options