Skip to content

development.md

Latest commit

 

History

History
245 lines (181 loc) · 7.13 KB

development.md

File metadata and controls

245 lines (181 loc) · 7.13 KB
Raw

Monaw Development

This document is for contributors and maintainers. The root README is for end users.

Tech Stack

  • Frontend: Electron, React, Vite, TypeScript, Tailwind CSS.
  • Backend: FastAPI, Uvicorn, Pydantic.
  • LLM providers: OpenAI SDK, Google GenAI SDK, DeepSeek through an OpenAI-compatible API.
  • Storage: SQLite plus local markdown memory files.
  • Automation: browser-use, MCP, and Windows desktop automation packages.

Development Commands

Run the full dev app from the frontend folder:

cd frontend
npm run dev

This starts Vite and Electron. Electron starts the backend.

Run only Vite:

cd frontend
npm run dev:vite

Run only Electron:

cd frontend
npm run dev:electron

Run only the backend:

cd backend
python -m uvicorn app.main:app --host 127.0.0.1 --port 8435 --reload

Health check:

Invoke-WebRequest -UseBasicParsing http://127.0.0.1:8435/health

Frontend npm commands must run from frontend, not the repo root.

Related Module Docs

Runtime Layout

Runtime data is stored under:

%USERPROFILE%\.monaw\runtime\

Important files:

%USERPROFILE%\.monaw\runtime\agent.db          SQLite conversations, runs, and app state
%USERPROFILE%\.monaw\runtime\settings.json     Runtime settings saved by the app
%USERPROFILE%\.monaw\runtime\backend.log       Backend process log
%USERPROFILE%\.monaw\runtime\launcher\         Launcher logs

The user's Monaw home folder is:

%USERPROFILE%\.monaw\

Runtime layout:

%USERPROFILE%\.monaw\runtime\        settings.json, agent.db, backend.log, Electron store
%USERPROFILE%\.monaw\workspace\      default workdir for agent shell commands
%USERPROFILE%\.monaw\browser\        managed browser data and artifacts
%USERPROFILE%\.monaw\memory\         long-term memory markdown files

Override the main folder with MONAW_HOME or AGENT_HOME, runtime with AGENT_RUNTIME_DIR, workspace with AGENT_WORKSPACE_DIR, and memory with AGENT_MEMORY_DIR.

Architecture

flowchart LR
  UI["React renderer"] --> Preload["Electron preload API"]
  Preload --> Backend["FastAPI backend"]
  Main["Electron main process"] --> Backend
  Backend --> Runtime["Agent runtime"]
  Runtime --> Skills["Skill registry"]
  Runtime --> Memory["Long-term memory"]
  Runtime --> DB["SQLite"]
  Skills --> Tools["Filesystem / exec / browser / MCP / scheduling"]
Loading

Module Guide

backend/app/main.py                    FastAPI app, CORS, health check, scheduler and Telegram startup
backend/app/config.py                  Environment-backed defaults used before runtime settings load
backend/app/api/routes/                HTTP API routes for chat, settings, memory, files, uploads, sandbox, diagnostics, approvals, access grants, conversations, and scheduled tasks
backend/app/agent/runtime.py           Runtime assembly for settings, LLM client, memory, tools, MCP, and run execution
backend/app/agent/turn_loop.py         Main agent turn loop and tool-call flow
backend/app/agent/llm_client.py        OpenAI, DeepSeek, and Gemini client abstraction
backend/app/agent/settings_store.py    Local runtime settings persistence
backend/app/agent/long_term_memory.py  Sectioned markdown long-term memory storage
backend/app/agent/scheduler.py         Scheduled task service and run orchestration
backend/app/agent/sandbox/             Exec sandbox policy, backend selection, sessions, and path controls
backend/app/agent/harness/             Tool protocol, execution wrapper, and policy checks
backend/app/agent/observability/       Trajectory logging
backend/app/agent/security/            Prompt-injection detection helpers
backend/app/skills/                    Runtime skills exposed to the agent
backend/app/integrations/telegram/     Optional Telegram bridge
frontend/electron/                     Electron main and preload processes
frontend/src/                          React renderer, settings UI, chat UI, scheduling UI, API clients, and tests
scripts/start-windows.ps1              Windows dev launcher used by start.bat
docs/browser-automation.md             Browser automation behavior and troubleshooting
docs/mcp.md                            MCP server setup, lifecycle, and reflected tools
docs/memory.md                         Long-term memory storage and APIs
docs/permissions.md                    Permissions, approvals, and access grants
docs/sandboxing.md                     Sandbox behavior and troubleshooting
docs/scheduling.md                     Scheduled task lifecycle and APIs
docs/telegram.md                       Telegram bridge setup and operations

Current built-in skills:

browser_use       Managed browser automation
computer_use      Windows desktop observation and control helpers
core              Basic runtime/system controls
exec              Shell command execution through the sandbox layer
filesystem        File read/write/search helpers
mcp_bridge        MCP server tool bridge
memory            Long-term memory tools
scheduling        Scheduled task tools

Models

The model dropdown uses:

GET /api/settings/model-options

The local catalog is defined in backend\app\agent\llm_constants.py.

Default backend settings:

provider: openai
model: gpt-5.4
reasoning_effort: medium
vision_fallback_model: gemini-3.1-flash-lite-preview

Current curated chat model groups:

OpenAI:   gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.4-nano
DeepSeek: deepseek-v4-flash, deepseek-v4-pro
Google:   gemini-3.1-pro-preview, gemini-3.1-flash-lite, gemini-3.1-flash-lite-preview, gemini-3-flash-preview

Memory Internals

Durable memory is stored locally as sectioned markdown. Inside the memory root, long-term memory is stored by category:

long-term\preference.md
long-term\behavior.md
long-term\fact.md
long-term\workflow.md
long-term\project.md
long-term\reflection.md

Each section is editable through the Settings UI and memory API. The legacy style category is normalized into preference.

Browser Automation

Browser settings and diagnostics live in Settings -> Browser.

For Chrome DevTools MCP workflows, use one of the MCP templates in Settings -> MCP, or start Chrome manually with remote debugging.

MCP

MCP servers are configured in Settings -> MCP. The app supports filesystem, Chrome DevTools, and custom stdio or streamable HTTP server entries.

Diagnostics in the same panel show server connection state, reflected tools, process state, and startup errors.

Sandbox And Permissions

Approvals and access grants run before tool execution. Shell execution then routes through the sandbox layer.

Sandbox modes include:

off / disabled
auto
enforce
docker
local_restricted

See docs\sandboxing.md for backend behavior and limitations.

Testing

Backend tests:

cd backend
python -m pytest

Frontend tests:

cd frontend
npm test

Frontend build smoke:

cd frontend
npm run build:renderer