Camarero Multiplexing System

A modular Unix-style system for aggregating and managing issues from multiple forge platforms (GitHub, GitLab, etc.) with agent-enabled interfaces and deep Org-mode integration.

Core Philosophy

• Each tool does one thing well
• JSON as the canonical data format
• Filesystem as the universal API (cache directory as source of truth)
• Agent capabilities optional but pervasive when enabled
• Voice interaction via Whisper.cpp integration

Components

• camarero-fetch: Fetches issues from configured forges to cache
• camarero-convert: Converts cached JSON to other formats (Org, MD)
• camarero-tui: Terminal user interface for issue management
• camarero-gui: Graphical user interface for issue management
• camarero-agent: Autonomous agent for issue triage and management
• camarero-org: Org-mode integration bridge
• camarero-voice: Voice interaction module (Whisper.cpp wrapper)
• camarero-watch: Filesystem monitor for cache changes
• camarero-config: Configuration management library (docs)

Agent Server

The camarero-agent includes a UNIX domain socket server for inter-process communication. The server library is located in agent/server/ and provides:

• Concurrent Connection Handling: Supports multiple simultaneous client connections
• Graceful Shutdown: Proper cleanup on server termination
• Session Management: Tracks client sessions with timeout handling
• Protocol Compliance: Implements 255-byte JSON header specification
• Security: Same-user verification and request rate limiting

Usage Example

import "camarero/agent/server"

// Create a request handler
handler := &server.AgentHandler{}

// Create server instance
srv, err := server.NewServer("/tmp/camarero.sock", handler)
if err != nil {
    log.Fatal(err)
}

// Start server with context
ctx := context.Background()
if err := srv.Start(ctx); err != nil {
    log.Fatal(err)
}

// Server is now running...

// Graceful shutdown
// srv.Stop()

Testing

Run the agent server tests with:

go test ./agent/server/... -v -cover

Test coverage must exceed 95% as per project requirements.

Quick Start

1. Clone the repository (if not already done)
2. Navigate to the project root (where go.mod is located):

   cd /path/to/camarero
   

3. Install dependencies:

   go mod tidy
   

4. Run tests to verify the configuration layer:

   go test ./config -cover
   

5. Create a configuration file:

   mkdir -p ~/.config/camarero
   cp example-config.json ~/.config/camarero/config.json
   

6. Set environment variables (optional):

   export GITHUB_TOKEN=your_token_here
   export GITLAB_TOKEN=your_token_here
   

7. Test the configuration loader:

   go run cmd/test-config/main.go
   

For development, see the Development section below.

Data Flow

1. Data Acquisition: Forge APIs → camarero-fetch → JSON Cache Directory
2. Format Conversion: JSON Cache → camarero-convert → Org/Markdown Files
3. Monitoring: camarero-watch monitors filesystem events and triggers updates
4. Interfaces: Multiple UI options (TUI, GUI, Org-mode) access the cache
5. Agent Layer: Optional AI assistance for all operations
6. Voice Layer: Voice-to-text integration via Whisper.cpp

Configuration

Camarero uses a unified configuration system implemented in the config package. For complete documentation, see config/README.md.

Key features:

• Hierarchical Loading: Multiple config files merged with proper precedence
• JSON Schema Validation: All configuration validated against a schema
• Environment Variable Interpolation: Use ${ENV_VAR} syntax in config files
• Type-Safe Accessors: Get configuration values with proper typing
• Immutable Config: Configuration objects are immutable after loading

Quick Configuration Example

{
  "version": "1.0",
  "cache_dir": "~/.cache/camarero",
  "polling_interval": "300",
  "forges": {
    "github": {
      "token": "${GITHUB_TOKEN}",
      "poll_interval": "60",
      "repos": ["owner/repo"]
    }
  }
}

Usage in Go Code

import "camarero/config"

// Load configuration
cfg, err := config.Load(
    "/etc/camarero/config.json",
    "~/.config/camarero/config.json",
)
if err != nil {
    // Handle error
}

// Access configuration
cacheDir := cfg.GetCacheDir()
agentEnabled := cfg.IsAgentEnabled()

For detailed documentation including all configuration options, validation rules, and API reference, see the config library documentation.

Development

This project follows strict Go development practices:

• Conventional Commits specification
• High test coverage (>95%)
• Standard library preferred over third-party modules
• Comprehensive documentation

See specs/01_POLICY.org for detailed development guidelines.

License

To be determined.