kollabor architecture

core application structure:

  kollabor/                     (application core)
    application.py              (main orchestrator)
    config/                     (configuration management)
      loader.py                 (config loading with dot notation)
      plugin_schema.py          (plugin config validation)
    events/                     (event system)
      bus.py                    (central event coordinator)
      registry.py               (hook registration and lookup)
      executor.py               (hook execution with error handling)
      processor.py              (event processing through hooks)
      models.py                 (event and hook data models)
    io/                         (terminal i/o system)
      terminal_renderer.py      (main terminal rendering)
      input_handler.py          (raw mode input handling)
      layout.py                 (terminal layout management)
      message_coordinator.py    (message flow and render state)
      visual_effects.py         (color palettes and effects)
      status_renderer.py        (multi-area status display)
      terminal_state.py         (global terminal state management)
    llm/                        (llm core services)
      llm_service.py            (main llm orchestration)
      api_communication_service.py  (http client with rate limiting)
      conversation_manager.py   (conversation state management)
      conversation_logger.py    (conversation persistence)
      tool_executor.py          (tool/function calling execution)
      message_display_service.py (response formatting and display)
      mcp_integration.py        (model context protocol)
      response_parser.py        (response parsing with question gate)
      plugin_sdk.py             (plugin development interface)
      permissions/              (tool permission system)
        manager.py              (permission manager)
        risk_assessor.py        (risk-based assessment)
        models.py               (permission data structures)
    plugins/                    (plugin system)
      base.py                   (base plugin class)
      discovery.py              (plugin discovery)
      registry.py               (plugin registry)
      factory.py                (plugin instantiation)
    commands/                   (command system)
      parser.py                 (slash command parser)
      registry.py               (command registry)
      executor.py               (command execution)
    ui/                         (ui system)
      design_system/            (design system components)
        colors.py               (theme management)
        styles.py               (style constants)
        boxes.py                (box rendering)
      widgets/                  (ui widgets)
        (dropdown, checkbox, slider, etc.)
      modals/                   (modal system)
      fullscreen/               (fullscreen plugin rendering)
    models/                     (shared data models)
    utils/                      (utility functions)
      config_utils.py           (path resolution and initialization)
      prompt_renderer.py        (<trender> tag processing)

  plugins/                      (plugin implementations)
    (each plugin is self-contained with hooks, commands, config)

  agents/                       (specialized agents)
    default/                    (general purpose agent)
    coder/                      (implementation specialist)
    kollabor/                   (meta-agent - you are here)
    research/                   (investigation specialist)
    (other specialized agents)

llm service architecture:

  request flow:
    [1] user input
        → llm_service.process_input()
    [2] build request
        → conversation_manager.get_conversation_history()
        → tool_executor.get_available_tools()
        → mcp_integration.get_mcp_tools()
    [3] pre-api-request hooks
        → event_bus.emit("pre_api_request", context)
        → plugins can modify request
    [4] api call
        → api_communication_service.call_api()
        → rate limiting and retry logic
    [5] response processing
        → response_parser.parse_response()
        → question gate detection (<question> tags)
        → tool call extraction
    [6] tool execution
        → tool_executor.execute_tool()
        → permission system checks (risk_assessor)
        → user approval if needed
        → tool execution
        → result injection
    [7] post-api-response hooks
        → event_bus.emit("post_api_response", context)
        → plugins can transform response
    [8] display
        → message_display_service.format_and_display()
        → message_coordinator coordinates rendering

  key services:
    llm_service                 (orchestrates entire flow)
    api_communication_service   (http client with connection pooling)
    conversation_manager        (maintains conversation state)
    tool_executor               (executes function calls)
    mcp_integration             (model context protocol servers)
    permissions/manager         (tool approval system)

event system and hook priorities:

  event bus flow:
    [1] event emitted
        → event_bus.emit(event_type, data)
    [2] lookup hooks
        → hook_registry.get_hooks(event_type)
    [3] sort by priority
        → CRITICAL (900) → HIGH (700) → NORMAL (500) → LOW (300)
    [4] execute hooks
        → hook_executor.execute_hooks()
        → each hook can modify context
    [5] return result
        → final context passed to next handler

  hook priorities:
    [900] CRITICAL              (security, permissions, validation)
    [700] HIGH                   (core functionality, state changes)
    [500] NORMAL                 (standard plugin behavior)
    [300] LOW                    (logging, monitoring, analytics)

  key event types:
    pre_user_input              (before user input processed)
    post_user_input             (after user input processed)
    pre_api_request             (before llm api call)
    post_api_response           (after llm response received)
    tool_execution              (tool execution events)
    permission_request          (tool permission requests)
    status_update               (status line updates)

plugin lifecycle:

  [1] discovery
      → plugin_discovery.scan_plugins()
      → scans plugins/ directory for python modules
      → loads plugin metadata

  [2] instantiation
      → plugin_factory.create_plugin()
      → instantiates plugin with dependencies:
        - event_bus
        - config
        - terminal_renderer
        - command_registry

  [3] initialization
      → plugin.initialize()
      → plugin registers hooks
      → plugin registers slash commands
      → plugin merges config

  [4] execution
      → hooks called when events emitted
      → commands executed when user types slash commands
      → status line updated via get_status_line()

  [5] cleanup
      → plugin.shutdown()
      → plugin cleanup resources
      → hooks unregistered

configuration system:

  global directory (~/.kollabor-cli/):
    config.json                 (user configuration)
    agents/                     (global agent definitions)
    mcp/                        (mcp server configurations)
    projects/                   (project-specific data)
      <encoded-path>/
        conversations/          (conversation history as jsonl)
        logs/                   (application logs)

  local directory (.kollabor-cli/):
    agents/                     (project-specific agents)
    mcp/                        (project-specific mcp config)
    (optional - only created when needed)

  priority order:
    [1] local (.kollabor-cli/)   (overrides global)
    [2] global (~/.kollabor-cli/) (defaults)

  config access:
    config.get("kollabor.llm.max_history", 90)
    config.set("terminal.color_mode", "truecolor")
    dot notation for nested keys

data flow:

  user input flow:
    [1] user types in terminal
        → input_handler reads keystrokes
        → key_parser parses keys/chords
    [2] line submitted
        → command_parser checks for slash commands
        → if command: command_executor.execute()
        → if not: llm_service.process_input()
    [3] response streaming
        → message_display_service formats response
        → message_coordinator coordinates with render loop
        → terminal_renderer displays response
    [4] status updates
        → status_renderer renders status areas a/b/c
        → plugins contribute via get_status_line()

  plugin hook flow:
    [1] event emitted
    [2] hooks called in priority order
    [3] each hook receives and can modify context
    [4] modified context passed to next hook
    [5] final result returned

agent and skill system:

  agent resolution (local takes precedence):
    [1] .kollabor-cli/agents/<name>/  (project-specific)
    [2] ~/.kollabor-cli/agents/<name>/ (user defaults)

  agent structure:
    agents/<name>/
      system_prompt.md           (agent system prompt)
      sections/                  (modular sections, optional)
      README.md                  (documentation, optional)
      <skill>.md                 (skill files, optional)

  skill loading:
    - skills are .md files in agent directory
    - loaded via <skill> tag when spawning sub-agent
    - skill content injected into agent's context

  sub-agent spawning:
    - uses xml tags: <agent><agent-name>...</agent-name></agent>
    - runs in separate tmux session
    - monitored for completion (6 seconds idle = done)
    - results injected back when complete

