avibe AGENTS.md

Agent Guidelines for Avibe

This document is the operating manual for coding agents working in this repository.

1. Project Overview

Avibe is the local-first Agent OS: one install command turns a machine into the runtime an agent lives in, and the user operates that runtime through Web or IM surfaces such as Slack, Discord, Telegram, Feishu/Lark, and WeChat.

Current product shape:

• V2 config-driven service with a Web UI setup wizard and settings pages
• multi-platform message transport with shared core orchestration
• multi-backend agent routing across OpenCode, Claude Code, and Codex
• local Incus-based unified regression environment for real cross-platform verification

Default mindset:

• treat the system as multi-platform, multi-backend first
• prefer root-cause fixes over narrow patches
• preserve user-visible behavior unless the task explicitly changes product behavior

2. Design Philosophy and Architecture

Core Rule: Fix at the Highest Appropriate Layer

• If a bug appears on one platform, check whether the same logic exists for the others before patching a platform adapter.
• If a behavior should be shared by multiple backends, prefer the shared core or backend abstraction over a single backend implementation.
• Keep transport/platform details out of core business logic whenever possible.

Decision checklist before writing code:

1. Scope: is this platform-specific/backend-specific, or common?
2. Abstraction: can the shared base or core layer own this behavior?
3. Call path: is the code called from controller/handlers/common flow?
4. Future-proofing: would a new platform/backend inherit the correct behavior automatically?

Codebase Map

• main.py - entry point wiring config.V2Config into core/controller.py
• core/controller.py - orchestration and dependency wiring
• vibe/ui_server.py and vibe/api.py run in a separate process from the controller and reach controller-owned state over the internal socket; vibe/api.py builds its own AgentAuthService. In-memory registries therefore cannot span IM and Web surfaces: cross-surface exclusion needs an explicit IPC hop or a documented per-instance scope. See PR #1417's Known-by-design ledger.
• core/handlers/ - platform/backend-agnostic business workflows
• core/message_dispatcher.py - outbound message routing and reply enhancement flow
• core/reply_enhancer.py - file-link and quick-reply prompt injection helpers
• modules/im/ - IM platform adapters (slack.py, discord.py, telegram.py, feishu.py, wechat.py) plus shared base classes
• modules/agents/ - agent backend adapters (opencode/, codex/, Claude-related modules) plus shared abstractions
• modules/im/formatters/ - platform-specific formatting built on shared formatter concepts
• config/ - V2 config, settings, sessions, paths, and compatibility conversion
• ui/ - React + Vite + TypeScript Web UI
• scripts/ - operational helpers, including regression testing workflows
• tests/ - pytest-style unit/integration/regression coverage