agassiee/tars-ai-os

Purpose and Entry Points

TARS AI OS is a terminal-native personal AI assistant supporting typed and voice interaction, specialized behavior modes, local tools, cloud/local intelligence routing, and persistent user memory. main.py is the primary runtime entry point; start_tars.bat is the Windows launcher. scripts/memory_cleanup.py supports maintenance of persisted memory.

Core Orchestration

core/engine.py is the central execution layer: it receives user input from the terminal/voice layer, coordinates intent handling, selects capabilities, and returns assistant output. core/intent.py classifies or routes requests into the appropriate mode, agent, or integration. core/personality.py supplies the TARS-style response/personality behavior applied around execution.

Interaction Boundary: Terminal and Voice

The primary interface is the terminal loop in main.py. Voice capabilities are isolated behind voice/stt.py for speech-to-text, voice/tts.py for spoken responses, and voice/wake_word.py for activation/listening control. This keeps audio-device and speech-service concerns outside the core engine.

Specialized Modes

Mode modules define domain-oriented assistant behavior selected during routing: analysis, creative, health, life, money, study, and speaking practice. Representative paths are modes/analysis_mode.py, modes/health_mode.py, and modes/study_mode.py. These are behavior/control boundaries rather than the general execution loop, allowing requests to receive domain-specific prompts, reasoning, or response formats.

Agent Layer

Agents encapsulate task-specific planning and execution roles that can be invoked by core routing or modes. agents/planner_agent.py handles planning-oriented work, agents/research_agent.py supports research workflows, while agents/coding_agent.py and agents/health_agent.py cover coding and health-specific assistance. This layer separates higher-level task strategy from direct tool integrations.

Memory and User Context

Persistent personalization is owned by memory/user_profile.py, while semantic or vector-backed recall is handled by memory/vector_store.py. The expected flow is input → retrieval of relevant profile/history context → engine/agent response generation → memory update where appropriate. Memory is a local persistence boundary and should not be coupled directly to individual modes or tool modules.

Tool and External-Service Integrations

Feature integrations live behind modular adapters: modules/weather.py, modules/music.py (Spotify-related capability), modules/browser.py, modules/news.py, modules/files.py, modules/local_tools.py, modules/system_monitor.py, and modules/vision.py. These form the boundary between assistant reasoning and external services, OS resources, browser/file access, media APIs, weather/news providers, and vision inputs.

Runtime Configuration

Python dependencies are declared in requirements.txt; global configuration and likely service credentials/runtime settings are centralized in utils/config.py. The application runs as a local Python process, with optional cloud intelligence and third-party service calls mediated through the engine, agents, voice stack, and module adapters.