# Meeseeks Chat - Project Guidance

> Scope: this file applies to the apps/meeseeks_chat/ UI app. It captures runtime behavior, hidden dependencies, and testing notes.

- Skill: `tools-only/meeseeks-chat-project-guidance-2` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/meeseeks-chat-project-guidance-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/meeseeks-chat-project-guidance-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-29
- Page: https://skillmd.com/skills/tools-only/meeseeks-chat-project-guidance-2

---

# Meeseeks Chat - Project Guidance

Scope: this file applies to the `apps/meeseeks_chat/` UI app. It captures runtime behavior, hidden dependencies, and testing notes.

## Runtime flow
- Entry point: `apps/meeseeks_chat/src/meeseeks_chat/chat_master.py` (UI app).
- Uses `generate_action_plan(...)` for preview and `orchestrate_session(...)` for execution.
- Stores session state in `st.session_state`:
  - `session_store`, `session_id`, `messages`, and `conversation_memory`.
- Action plan (title/description steps) is displayed in an expander ("thought" role).

## Hidden dependencies / assumptions
- Expects static assets packaged under `src/meeseeks_chat/static/`.
- Uses `time.sleep(...)` for spinner pacing (adds latency even if tool work is fast).
- Approvals are auto-approved via `core.permissions.auto_approve`.

## Pitfalls / gotchas
- UI session state is per-browser tab; multi-tab behavior can fork sessions unexpectedly.
- The local rolling memory buffer is separate from core session summaries.
- If core orchestration changes the shape of `TaskQueue`, update UI formatting here.
- Treat language models as black-box APIs with non-deterministic output; avoid anthropomorphic language in docs/changes.

## Testing guidance
- Keep tests light: mock `orchestrate_session` and `generate_action_plan` only.
- Avoid end-to-end UI testing unless UX regressions require it.

## Cross-project insights
- Show the plan and reflect tool outputs before final response; keep the plan display concise.
- Context summaries should be short and recent; avoid dumping long histories into the UI.
- Keep turn boundaries clear (user input -> plan -> tool -> response).