Meeseeks: The Personal Assistant 👋

Meeseeks.pre-alpha.demo.v2.mp4

Meeseeks runs right in your terminal, browser, or hosted as an API.

Intro

Meeseeks is an AI task agent assistant built on a plan → tool selection → step execution loop. It breaks a request into steps, chooses tools per step, runs them, and synthesizes a final reply. It keeps a session transcript, compacts long histories, and stores summaries for continuity across longer conversations.

Legends (Expand to View)

Completed	In-Progress	Planned	Scoping
✅	🚧	📅	🧐

Feature highlights

Answer questions and interpret sensor information	Control devices and entities	Web chat interface

What's next (Meeseeks Console)

We are upgrading the API backend to better support a task-orchestration frontend. Next up: finalize the API shape, then polish the frontend and ship the full console experience.

Task detail page (coming soon)	Landing console (coming soon)

Core workflow

• (✅) Plan → select tools → execute: Builds a short plan, chooses the right tools per step, and executes them.
• (✅) Step-level reflection: Validates tool outcomes and adjusts tool inputs when required.
• (✅) Plan updates: Emits updated action plans after each step so UIs can refresh the to‑do list.
• (✅) Synthesized replies: Produces a final answer after tool results are collected and summarized.

Memory and context management

• (✅) Session transcripts: Writes tool activity and responses to disk for continuity.
• (✅) Context compaction: Summarizes long sessions and auto-compacts near the context budget.
• (✅) Token awareness: Tracks context window usage and exposes budgets in the CLI.
• (✅) Selective recall: Builds context from recent turns plus a summary of prior events.
• (✅) Session listing hygiene: Filters empty sessions and supports archiving via the API.

Model and provider support

• (✅) Model gateway: Uses LiteLLM for OpenAI-compatible access across multiple providers.
• (✅) Model routing: Supports provider-qualified model names and a configurable API base URL.
• (✅) Reasoning compatibility: Applies reasoning-effort controls where supported by the model.

Tooling and integrations

• (✅) Tool registry: Discovers local tools and optional MCP tools with manual manifest overrides.
• (✅) Local file + shell tools: Built-in Aider adapters for edit blocks, read files, list dirs, and shell commands (approval-gated). Edit blocks require strict SEARCH/REPLACE format; the tool returns format guidance on mismatches.
• (✅) Home Assistant: Ships a Conversation integration for voice control and entity actions.
• (✅) REST API: Exposes the assistant over HTTP for third-party integration.
• (✅) Web chat UI: Streamlit interface with plans, tool input types, and responses.
• (✅) Terminal CLI: Fast interactive shell with plan visibility and tool result cards.

Safety and observability

• (✅) Permission gate: Uses approval callbacks and hooks to control tool execution.
• (✅) Operational visibility: Optional Langfuse tracing (session-scoped traces) stays off if unconfigured.

Optional add-ons

Optional features that can be installed when needed.

• (📅) Quality Use CRITIC reflection framework to reflect on a response to a task/query using external tools via [^].
• (🚧) Privacy Integrate with microsoft/presidio for customizable PII de-identification.

Interface notes

• CLI layout adapts to terminal width. Headers and tool result cards adjust to small and wide shells.
• Interactive CLI controls. Use a model picker, MCP browser, session summary, and token budget commands.
• Inline approvals. Rich-based approval prompts render with padded, dotted borders and clear after input.
• Unified experience. Web, API, Home Assistant, and CLI interfaces share the same core engine to reduce duplicated maintenance.
• Shared session runtime. The API exposes polling endpoints; the CLI runs the same runtime in-process for sync execution, cancellation, and summaries.
• Event payloads. action_plan steps are {title, description}; tool_result/permission use tool_id, operation, and tool_input.

Monorepo layout

• packages/meeseeks_core/: orchestration loop, schemas, session storage, compaction, tool registry.
• packages/meeseeks_tools/: tool implementations and integrations (including Home Assistant and MCP).
• apps/meeseeks_api/: Flask REST API for programmatic access.
• apps/meeseeks_chat/: Streamlit UI for interactive chat.
• apps/meeseeks_cli/: Terminal CLI frontend for interactive sessions.
• meeseeks_ha_conversation/: Home Assistant integration that routes voice to the API.
• packages/meeseeks_core/src/meeseeks_core/prompts/: planner prompts and tool instructions.

Architecture (short)

Requests flow through a single core engine used by every interface, so behavior stays consistent across UI, API, and voice.

flowchart LR
  subgraph Clients["Clients / Interfaces"]
    User[User]
    CLI["CLI\n(apps/meeseeks_cli)"]
    Chat["Chat UI\n(apps/meeseeks_chat)"]
    API["REST API\n(apps/meeseeks_api)"]
    HA["Home Assistant\n(meeseeks_ha_conversation)"]
  end

  subgraph Runtime["Shared Runtime\n(packages/meeseeks_core/session_runtime.py)"]
    SessionRuntime["SessionRuntime"]
    RunRegistry["RunRegistry"]
  end

  subgraph Core["Core Orchestration\n(packages/meeseeks_core)"]
    TaskMaster["orchestrate_session\n(task_master.py)"]
    Orchestrator["Orchestrator\n(orchestrator.py)"]
    Planner["Planner\n(planning.py)"]
    ToolSelector["ToolSelector\n(planning.py)"]
    StepExecutor["StepExecutor\n(planning.py)"]
    PlanUpdater["PlanUpdater\n(planning.py)"]
    ActionPlanRunner["ActionPlanRunner\n(action_runner.py)"]
    ContextBuilder["ContextBuilder\n(context.py)"]
    ActionStep["ActionStep\n(classes.py)"]
    TaskQueue["TaskQueue\n(classes.py)"]
  end

  subgraph LLM["LLM Abstraction\n(packages/meeseeks_core/llm.py)"]
    ChatModel["ChatModel (Protocol)"]
    BuildChatModel["build_chat_model()"]
  end

  subgraph Tools["Tool Abstractions + Implementations"]
    ToolRegistry["ToolRegistry\n(tool_registry.py)"]
    AbstractTool["AbstractTool\n(classes.py)"]
    LocalTools["Local tools\n(Aider adapters)"]
    MCPTools["MCP tools"]
    HATools["Home Assistant tools"]
  end

  subgraph Store["Session Storage\n(packages/meeseeks_core/session_store.py)"]
    SessionStore["SessionStore"]
  end

  subgraph Events["Session events"]
    EventLog["JSONL event log"]
    Polling["API polling\n(/events?after=...)"]
  end

  User --> CLI
  User --> Chat
  User --> API
  HA --> API

  CLI --> SessionRuntime
  Chat --> SessionRuntime
  API --> SessionRuntime

  SessionRuntime --> TaskMaster
  SessionRuntime --> SessionStore
  SessionRuntime --> RunRegistry

  TaskMaster --> Orchestrator
  Orchestrator --> Planner
  Orchestrator --> ToolSelector
  Orchestrator --> StepExecutor
  Orchestrator --> PlanUpdater
  Orchestrator --> ActionPlanRunner
  Orchestrator --> ContextBuilder
  Orchestrator --> ToolRegistry
  Orchestrator --> SessionStore

  ActionPlanRunner --> TaskQueue
  ActionPlanRunner --> ActionStep

  ToolRegistry --> AbstractTool
  AbstractTool --> LocalTools
  AbstractTool --> MCPTools
  AbstractTool --> HATools

  Orchestrator --> BuildChatModel
  BuildChatModel --> ChatModel

  SessionStore --> EventLog
  EventLog --> Polling
  API --> Polling

  Orchestrator --> Langfuse

Loading

Documentation

The docs landing page mirrors the feature highlights in this README. Keep both updated together for consistent messaging.

Overview

• docs/index.md - product overview and architecture

Setup and configuration

• docs/getting-started.md - setup guide (env, MCP, configs, run paths)

Repository map

• docs/components.md - monorepo map

Reference

• docs/reference.md - API reference (mkdocstrings)
• docs/session-runtime.md - shared session runtime used by CLI + API

Installation (quick)

User install (core only):

uv sync

Optional components:

uv sync --extra cli   # CLI
uv sync --extra api   # REST API
uv sync --extra chat  # Streamlit UI
uv sync --extra ha    # Home Assistant integration

Developer install (all components + dev/test/docs):

uv sync --all-extras --all-groups

Development principles

• Keep the core engine centralized. Interfaces should remain thin to avoid duplicated maintenance.
• Organize logic into clear modules, classes, and functions. Favor readable, well-scoped blocks.
• Prefer small, composable changes that keep behavior consistent across interfaces.

---

Contributing 👏

We welcome contributions from the community to improve Meeseeks. Use the steps below.

1. Fork the repository and clone it to your local machine.
2. Create a new branch for your contribution.
3. Make your changes, commit them, and push to your fork.
4. Open a pull request describing the change and the problem it solves.

Bug Reports and Feature Requests 🐞

If you encounter bugs or have ideas for features, open an issue on the issue tracker. Include reproduction steps and error messages when possible.

Thank you for contributing.