Glimx API Documentation

This document provides detailed information about the Glimx CLI API, including available commands, configuration options, and programmatic usage.

CLI Commands

Main Commands

Command	Description	Usage
glimx	Start interactive mode	glimx
glimx --template <name> <dir>	Create project from template	glimx --template react-vite my-app
glimx --model <provider/model>	Use specific model	glimx --model groq/qwen-32b
glimx --config <path>	Use custom config file	glimx --config ./my-config.json

Session Commands

These commands are available during an interactive Glimx session:

Command	Description
/compact	Summarize session to save tokens
/undo	Undo last message
/redo	Redo last message
/help	Show all available commands
/exit	Exit the session

Configuration Options

Top-Level Configuration

interface Config {
  model?: string;
  theme?: string;
  username?: string;
  share?: "manual" | "auto" | "disabled";
  autoupdate?: boolean;
  $schema?: string;
}

Provider Configuration

interface ProviderConfig {
  api?: string;
  models?: Record<string, ModelConfig>;
  options?: {
    apiKey?: string;
    baseURL?: string;
    timeout?: number | false;
  };
}

Model Configuration

interface ModelConfig {
  id: string;
  cost?: {
    input: number;
    output: number;
  };
  limit?: {
    context: number;
    output: number;
  };
}

Permission Configuration

type Permission = "ask" | "allow" | "deny";

interface PermissionConfig {
  bash?: Permission | Record<string, Permission>;
  edit?: Permission;
  write?: Permission;
  webfetch?: Permission;
}

MCP Configuration

type McpConfig = McpLocalConfig | McpRemoteConfig;

interface McpLocalConfig {
  type: "local";
  command: string[];
  environment?: Record<string, string>;
  enabled?: boolean;
  timeout?: number;
}

interface McpRemoteConfig {
  type: "remote";
  url: string;
  headers?: Record<string, string>;
  enabled?: boolean;
  timeout?: number;
}

Environment Variables

Variable	Description	Default
GROQ_API_KEY	API key for Groq provider	None
OPENROUTER_API_KEY	API key for OpenRouter provider	None
CEREBRAS_API_KEY	API key for Cerebras provider	None
OPENCODE_CONFIG	Path to custom config file	None
OPENCODE_LOG_LEVEL	Logging level (debug, info, warn, error)	info

Programmatic Usage

Installing Glimx as a Dependency

npm install glimx
# or
bun add glimx

Using Glimx in Your Code

import { Glimx } from 'glimx';

// Initialize with configuration
const glimx = new Glimx({
  model: 'groq/qwen-32b',
  provider: {
    groq: {
      options: {
        apiKey: process.env.GROQ_API_KEY
      }
    }
  }
});

// Start a session
await glimx.startSession();

// Send a message
const response = await glimx.sendMessage('Hello, world!');

// End session
await glimx.endSession();

Custom Tool Integration

import { Tool } from 'glimx';

class CustomTool extends Tool {
  name = 'custom-tool';
  description = 'A custom tool for specific functionality';
  
  async execute(params: any) {
    // Implementation here
    return { result: 'success' };
  }
}

// Register the tool
glimx.registerTool(new CustomTool());

API Response Formats

Standard Response

{
  "id": "response-id",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "Response content"
      }
    }
  ]
}

Error Response

{
  "error": {
    "type": "error-type",
    "message": "Error description"
  }
}

Hooks and Events

Session Events

// Listen for session start
glimx.on('session:start', () => {
  console.log('Session started');
});

// Listen for message completion
glimx.on('message:complete', (message) => {
  console.log('Message completed:', message);
});

// Listen for session end
glimx.on('session:end', () => {
  console.log('Session ended');
});

Custom Hooks

// File edit hook
{
  "experimental": {
    "hook": {
      "file_edited": {
        "pattern": "**/*.ts",
        "command": ["npx", "tsc", "--noEmit"]
      }
    }
  }
}

Plugin System

Creating Plugins

// plugin.ts
import { Plugin } from 'glimx';

export class MyPlugin extends Plugin {
  name = 'my-plugin';
  
  async onLoad() {
    // Plugin initialization
  }
  
  async onMessage(message: string) {
    // Process messages
  }
}

Loading Plugins

{
  "plugin": [
    "./plugin.ts"
  ]
}

Error Handling

Common Error Types

Error Type	Description	Solution
ConfigInvalidError	Invalid configuration file	Check JSON syntax and schema
ConfigJsonError	JSON parsing error	Fix malformed JSON
ModelNotFoundError	Specified model not found	Check model name and provider
PermissionDeniedError	Operation blocked by permissions	Adjust permission settings

Error Handling in Code

try {
  const response = await glimx.sendMessage('Hello');
} catch (error) {
  if (error.type === 'ModelNotFoundError') {
    console.log('Please check your model configuration');
  } else {
    console.log('An error occurred:', error.message);
  }
}

Performance Considerations

Memory Management

• Use /compact command to reduce memory usage in long sessions
• Configure session history limits in configuration
• Restart Glimx periodically for long-running processes

Rate Limiting

const glimx = new Glimx({
  provider: {
    groq: {
      options: {
        timeout: 60000 // 60 second timeout
      }
    }
  }
});

Security Best Practices

API Key Management

1. Use environment variables for API keys
2. Never commit API keys to version control
3. Rotate keys regularly
4. Use least-privilege keys when possible

Permission Configuration

{
  "permission": {
    "bash": {
      "rm -rf *": "deny",
      "git push *": "ask",
      "*": "ask"
    }
  }
}

Extending Glimx

Custom Providers

import { Provider } from 'glimx';

class CustomProvider extends Provider {
  name = 'custom';
  
  async sendMessage(message: string) {
    // Custom implementation
  }
}

Custom Themes

{
  "theme": {
    "name": "custom-theme",
    "colors": {
      "primary": "#8b7ff4",
      "secondary": "#4fc3f7",
      "background": "#0d0d14"
    }
  }
}

Integration Examples

CI/CD Integration

# GitHub Actions
- name: Run Glimx
  run: |
    glimx --model groq/qwen-32b <<EOF
    Review this code for best practices:
    $(cat src/index.ts)
    EOF

Editor Integration

// VS Code extension example
const glimx = new Glimx({
  model: 'groq/qwen-32b'
});

async function explainCode(code) {
  const explanation = await glimx.sendMessage(
    `Explain this code:\n\n${code}`
  );
  return explanation.choices[0].message.content;
}

Troubleshooting API Issues

Debug Logging

Enable debug logging to troubleshoot issues:

export OPENCODE_LOG_LEVEL=debug
glimx

Common API Issues

1. Timeout errors: Increase timeout values in provider configuration
2. Rate limiting: Implement retry logic with exponential backoff
3. Authentication errors: Verify API keys and provider configuration
4. Model errors: Check model availability and context limits

Next Steps

• Configuration Guide - Detailed configuration options
• MCP Integration - Model Context Protocol integration
• Templates Guide - Project templates usage
• Troubleshooting - Common issue resolution