Dreamatic

English | 简体中文

Harness for Professional Design Agents — Direct creativity, orchestrate intelligence, deliver professional design.

Dreamatic is a controllable agent runtime that goes beyond simple chat. Agents can understand requests, plan work, call tools, persist context, request human approval, spawn sub-agents, and stream execution in real time — all within persistent sessions.

The current release focuses on a general-purpose runtime layer suitable for design agents, research workspaces, local automation assistants, and multi-agent systems requiring predictable execution, tool governance, and observable long-running work.

Dreamatic requires Python >= 3.11.

python3 -m venv .venv
source .venv/bin/activate        # macOS/Linux
# .venv\Scripts\activate         # Windows
pip install --upgrade pip

pip install -e ".[dev]"

cp .env.example .env
# Fill in provider credentials

Basic OpenAI-compatible setup:

DREAMATIC_API_KEY=your-api-key
DREAMATIC_BASE_URL=https://your-endpoint/v1
DREAMATIC_MODEL=gpt-4o
HARNESS_DEFAULT_PROVIDER=openai-hub

For full web search:

SERPER_API_KEY=your-serper-key
BRAVE_SEARCH_API_KEY=your-brave-key

For image generation and editing:

DREAMATIC_IMAGE_API_KEY=your-image-api-key
DREAMATIC_IMAGE_BASE_URL=https://your-image-endpoint/v1
DREAMATIC_IMAGE_MODEL=gpt-image-2
DREAMATIC_IMAGE_GENERATION_ENDPOINT=https://your-image-endpoint/v1/images/generations
DREAMATIC_IMAGE_EDIT_ENDPOINT=https://your-image-endpoint/v1/images/edits
DREAMATIC_IMAGE_DEFAULT_SIZE=1024x1024

python -m uvicorn api.rest:app --port 8000
# Open http://localhost:8000

Use python -m uvicorn instead of the raw uvicorn command to ensure it runs within the current virtual environment. Avoid --reload as agent file writes can trigger restart and interrupt sessions.

python cli.py --persona builder

Dreamatic is organized into six runtime layers.

Execution flow: User sends a request → engine assembles prompt (system + persona + skills + memory + plan + history) → model responds or requests tool calls → tools pass through approval gate → results stream to frontend → loop continues or final answer returned.

Each example includes a full-resolution final package and artifact gallery.

A cultural merchandise system inspired by Peking opera facial makeup. Open package

Product system	Packaging	Series overview

Lab merchandise — bags, notebooks, badges. Open package

Tote hero	Notebook cover	Badge system

A companion device concept for elderly living alone. Open package

Hero render	Three-view	CMF board

Visitor center concept for an ancient water town. Open package

Site context	Zoning	Entry hall

Conference promotion — posters, social media, badges, templates. Open package

Main poster	Key visual	Social post

Bilingual campaign with merch mockups and moodboards. Open package

Logo poster	Chinese poster	Merch mockup

A dedicated input device for creative professionals working with AI-native workflows. Open package

Hero render	Usage scene	Form language

.
|-- api/                # FastAPI REST + WebSocket server
|-- harness/            # Agent runtime, tools, storage, LLM providers
|   |-- engine/         # Main loop, state machine, compression, prompt cache
|   |-- tools/          # Built-in tools and execution layer
|   |-- storage/        # SQLite and in-memory backends
|   |-- llm/            # Provider abstraction and implementations
|   |-- mcp/            # MCP bridge and transports
|   `-- commands/       # Built-in and project command system
|-- static/             # Browser frontend
|-- .myharness/         # Personas, skills, commands, transcripts
|-- tests/              # Tests
|-- cli.py              # CLI entry point
|-- config.yaml         # Runtime configuration
`-- pyproject.toml

Project-local behavior in .myharness/:

.myharness/
|-- personas/    # Agent roles (builder, planner, reviewer, etc.)
|-- skills/      # Reusable procedures (SKILL.md per skill)
|-- commands/    # Project-level shortcuts
`-- transcripts/ # Runtime transcripts

Personas define system prompt, default provider, approval mode, and allowed tools. Skills are injected by name at startup; full content loads on use_skill. Commands are project shortcuts exposed via CLI and Web UI.

The Web Workspace supports creating, switching, renaming, pinning, archiving, and deleting sessions; selecting provider/persona/approval mode; real-time message and tool-call viewing; historical message editing with regeneration; and editing skills/personas/config.

Two session-level modes: noquestion (direct execution, default) and question (agent asks clarification when information is missing).

python cli.py --persona builder --question-mode question
curl -X PATCH http://localhost:8000/sessions/{id}/mode \
  -H "Content-Type: application/json" \
  -d '{"question_mode": "question"}'

Built-in controls: approval gates for high-risk tools (shell, powershell), persona-scoped tool permissions, output caps, env-var secrets, SSRF protection in web_fetch, explicit state machine for runtime transitions. For untrusted-user exposure, use least-privilege personas, disable unnecessary tools, run in a controlled network, and add authentication/rate limiting/audit logging.

pytest                              # Full suite
pytest tests/test_engine.py         # Engine tests
python scripts/loc.py               # Count lines of code

Provider not found? — Check provider names in config.yaml and HARNESS_DEFAULT_PROVIDER in .env.

Web search empty? — Set SERPER_API_KEY or BRAVE_SEARCH_API_KEY; fallback is limited DuckDuckGo.

Should I use uvicorn or python -m uvicorn? — Always use python -m uvicorn. The raw uvicorn command may invoke a system-wide installation (e.g. from pipx) that uses a different Python path and won't find project dependencies installed in the virtual environment.

Avoid uvicorn --reload? — File writes from agents can trigger restart and interrupt sessions.

Skill not auto-invoked? — Check its SKILL.md description is clear. Use /<skill-name> to invoke manually.

MIT License