Wren

# ๐Ÿš€ Wren โ€” AI Engineering Platform [![Python 3.12+](https://img.shields.io/badge/Python-3.12%2B-3776ab?style=flat-square&logo=python&logoColor=white)](https://www.python.org/downloads/) [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178c6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/) [![React 19](https://img.shields.io/badge/React-19-61dafb?style=flat-square&logo=react&logoColor=white)](https://react.dev/) [![FastAPI](https://img.shields.io/badge/FastAPI-Latest-009688?style=flat-square&logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com/) [![MIT License](https://img.shields.io/badge/License-MIT-green?style=flat-square)](LICENSE)

**Self-host your AI coding agents.** Chat, code, review, debug โ€” all in one unified workspace. _Bring your own LLM ยท Own your data ยท Own the workflow_
[๐ŸŒ Website](#) ยท [๐Ÿ“– Docs](./GETTING_STARTED.md) ยท [๐Ÿ’ฌ Discord](#) ยท [๐Ÿ› Issues](https://github.com/Daniel-debug-boop/Wren/issues)
--- ## โœจ Key Features

๐Ÿค– Agentic AI Engineering

  • Multi-mode chat interface (Vibe Code, Autonomous, Game)
  • Real-time WebSocket streaming
  • Intelligent mode auto-selection
  • Working Memory & Lessons Learned

๐Ÿ’ป Built-in IDE Workspace

  • Monaco Editor with full syntax highlighting
  • Live file tree with real-time updates
  • Terminal emulator with bidirectional WebSocket
  • Resizable panes & customizable layout

๐Ÿ”ง Flexible LLM Support

  • OpenAI (GPT-4o, o1, o3)
  • Anthropic (Claude 3.5 Sonnet, Opus)
  • Mistral, Groq, Custom Endpoints
  • Full model configuration control

๐Ÿ›ก๏ธ Privacy & Control

  • 100% self-hosted on your infrastructure
  • Zero vendor lock-in
  • Docker-based sandboxing
  • Optional, transparent analytics

--- ## ๐Ÿš€ Quick Start ### Prerequisites ```bash โœ… Node.js 22.12.x or later โœ… Python 3.12+ with uv or poetry โœ… Docker (optional, for sandboxed execution) โœ… Git ``` ### Launch Wren (3 steps) ```bash # 1๏ธโƒฃ Clone the repository git clone https://github.com/Daniel-debug-boop/Wren.git cd Wren # 2๏ธโƒฃ Install dependencies & build make build # 3๏ธโƒฃ Start the application make run ``` Open **[http://localhost:3001](http://localhost:3001)** in your browser and start coding! ๐ŸŽ‰ > **Need detailed setup instructions?** Check out [GETTING_STARTED.md](./GETTING_STARTED.md) ### ๐Ÿณ Run with Docker ```bash export PROJECTS_PATH="$HOME/projects" mkdir -p "$PROJECTS_PATH" "$HOME/.wren" docker run -it --rm \ -p 8000:8000 \ -v "$HOME/.wren:/home/wren/.wren" \ -v "${PROJECTS_PATH}:/projects" \ ghcr.io/wren/agent-canvas:latest ``` ### โš™๏ธ Configuration Set environment variables to customize Wren: | Variable | Default | Description | |----------|---------|-------------| | `LLM_API_KEY` | โ€” | Your LLM provider API key | | `LLM_MODEL` | `gpt-4o` | Default model to use | | `WORKSPACE_DIR` | `./workspace` | Project workspace path | | `FRONTEND_PORT` | `3001` | Frontend development port | | `BACKEND_HOST` | `127.0.0.1` | Backend server hostname | | `BACKEND_PORT` | `3000` | Backend server port |
--- ## ๐Ÿ“‹ Core Operating Modes Wren offers three powerful modes to fit your workflow: ### ๐ŸŽฏ **Vibe Code** โ€” Interactive Development Full agentic coding with real-time feedback. Chat, edit, run, and iterate. Perfect for building applications from scratch with continuous human guidance. ### โšก **Autonomous** โ€” Self-Driving Execution Agent plans, codes, and debugs independently using Working Memory and Lessons Learned. Minimal hand-holding required. Ideal for complex, multi-step tasks. ### ๐ŸŽฎ **Game** โ€” Game Development Focus Specialized scaffolding for game projects. Asset wiring, scene management, and playable previews built-in. --- ## ๐Ÿ—๏ธ Architecture ``` โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ ๐ŸŽจ Frontend (React 19) โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ โ”‚ โ”‚ Chat Panel โ”‚ โ”‚ Monaco โ”‚ โ”‚ Review โ”‚ โ”‚ Terminal โ”‚ โ”‚ โ”‚ โ”‚ Interface โ”‚ โ”‚ Editor โ”‚ โ”‚ Console โ”‚ โ”‚ Emulator โ”‚ โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ โ”‚ โ†• WebSocket / REST APIs โ”‚ โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”‚ ๐Ÿ”Œ Application Server (FastAPI) โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ โ”‚ โ”‚ Intent โ”‚ โ”‚ Session โ”‚ โ”‚ LLM โ”‚ โ”‚ Skills โ”‚ โ”‚ โ”‚ โ”‚ Router โ”‚ โ”‚ Manager โ”‚ โ”‚ Router โ”‚ โ”‚ Engine โ”‚ โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ โ”‚ โ†• Internal IPC โ”‚ โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”‚ ๐ŸŽญ Agent Orchestrator (Harness Layer) โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ โ”‚ โ”‚ Meta โ”‚ โ”‚ Task โ”‚ โ”‚Working โ”‚ โ”‚ Vector โ”‚ โ”‚ โ”‚ โ”‚Orchestr. โ”‚ โ”‚ Graph โ”‚ โ”‚ Memory โ”‚ โ”‚ Store โ”‚ โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”‚ ๐Ÿ”’ Agent Execution Backends (Isolated) โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ โ”‚ โ”‚ Docker โ”‚ โ”‚ VM โ”‚ โ”‚ Cloud โ”‚ โ”‚ โ”‚ โ”‚ Sandbox โ”‚ โ”‚ Backend โ”‚ โ”‚ Backend โ”‚ โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ ``` ### Component Stack | Layer | Technology | Purpose | |-------|-----------|----------| | **Frontend** | React 19, TypeScript, TailwindCSS, Monaco Editor | User interface & IDE workspace | | **API Server** | FastAPI, WebSockets, Python 3.12 | REST + real-time communication | | **Orchestration** | Python Harness, Task Graph | Agent lifecycle & execution | | **Intent System** | NLP-based analysis | Mode selection & skill synthesis | | **Execution** | Docker / VM / Cloud | Isolated, secure agent runtime |
--- ## ๐Ÿ› ๏ธ Development ### Setup Development Environment ```bash # Install all dependencies (backend + frontend) make build # Install pre-commit hooks (required before committing) make install-pre-commit-hooks ``` ### Development Commands ```bash # Start full development stack make run # Frontend only (on port 3001) cd frontend && npm run dev # Backend only (on port 3000) make start-backend # Run tests cd frontend && npm run test # Frontend tests poetry run pytest tests/unit/ # Backend tests # Linting & formatting cd frontend && npm run lint:fix && npm run build pre-commit run --all-files --config ./dev_config/python/.pre-commit-config.yaml ``` ### Before Submitting a PR ```bash # 1. Install pre-commit hooks make install-pre-commit-hooks # 2. Make your changes # ... edit files ... # 3. Lint & format (auto-fixes most issues) cd frontend && npm run lint:fix && npm run build # Frontend pre-commit run --config ./dev_config/python/.pre-commit-config.yaml # Backend # 4. Verify TypeScript compilation cd frontend && npx tsc --noEmit # 5. Run tests cd frontend && npm run test poetry run pytest tests/unit/ # 6. Commit & push git add # Avoid git add . git commit -m "Your message" git push ``` All pre-commit checks **MUST** pass before merging. See [Development.md](./Development.md) for detailed setup.
--- ## ๐Ÿ“ฆ Project Structure ``` Wren/ โ”œโ”€โ”€ ๐ŸŽจ frontend/ # React SPA (TypeScript) โ”‚ โ”œโ”€โ”€ src/ โ”‚ โ”‚ โ”œโ”€โ”€ api/ # API client layer & data fetching โ”‚ โ”‚ โ”œโ”€โ”€ components/ # Reusable UI components โ”‚ โ”‚ โ”œโ”€โ”€ hooks/ # Custom React hooks โ”‚ โ”‚ โ”œโ”€โ”€ routes/ # Page components & routing โ”‚ โ”‚ โ”œโ”€โ”€ types/ # TypeScript type definitions โ”‚ โ”‚ โ””โ”€โ”€ utils/ # Utilities & verified models โ”‚ โ”œโ”€โ”€ __tests__/ # Vitest test suite โ”‚ โ””โ”€โ”€ package.json # Dependencies & scripts โ”‚ โ”œโ”€โ”€ ๐Ÿ wren/ # Python backend โ”‚ โ”œโ”€โ”€ app_server/ # FastAPI application server โ”‚ โ”œโ”€โ”€ server/ # Core server & orchestrator โ”‚ โ”œโ”€โ”€ harness/ # Agent orchestrator (task graph, working memory) โ”‚ โ”œโ”€โ”€ intent/ # NLP intent analysis & mode selection โ”‚ โ”œโ”€โ”€ agent_server/ # Agent runtime server โ”‚ โ””โ”€โ”€ cli/ # Command-line interface โ”‚ โ”œโ”€โ”€ ๐ŸŽฏ skills/ # Reusable agent skill prompts (44+) โ”‚ โ”œโ”€โ”€ react/ # React skill prompts โ”‚ โ”œโ”€โ”€ python/ # Python development skills โ”‚ โ”œโ”€โ”€ docker/ # Docker/containers skills โ”‚ โ”œโ”€โ”€ godot/ # Game development (Godot) โ”‚ โ””โ”€โ”€ ... # Domain-specific skills โ”‚ โ”œโ”€โ”€ ๐Ÿ“š docs/ # Documentation & guides โ”œโ”€โ”€ ๐Ÿงช tests/ # Pytest test suite โ”œโ”€โ”€ ๐Ÿณ containers/ # Docker configuration โ”œโ”€โ”€ Makefile # Build & development commands โ””โ”€โ”€ pyproject.toml # Python project configuration ```
--- ## ๐Ÿ”Œ Technology Stack ### Frontend (34.7% TypeScript + HTML + CSS) - **React** 19.2 โ€” Modern UI framework - **TypeScript** 5.9 โ€” Type-safe development - **React Router** 7 โ€” Client-side routing - **TanStack Query** 5 โ€” Data fetching & caching - **TailwindCSS** 4 โ€” Utility-first styling - **Monaco Editor** 0.55 โ€” Code editor - **Framer Motion** 12 โ€” Animations - **Zustand** โ€” State management - **Socket.IO** โ€” Real-time communication - **i18next** โ€” Internationalization ### Backend (62.1% Python) - **Python** 3.12+ โ€” Core language - **FastAPI** โ€” High-performance web framework - **WebSockets** โ€” Real-time bidirectional communication - **LiteLLM** 1.84.1 โ€” Multi-LLM provider abstraction - **SQLAlchemy** 2.0+ โ€” ORM & database - **Pydantic** โ€” Data validation - **Poetry** 2.3 โ€” Dependency management - **Pytest** 9.0 โ€” Testing framework ### Infrastructure - **Docker** โ€” Containerization & sandboxing - **PostgreSQL** โ€” Optional persistent storage - **Redis** โ€” Caching & sessions - **Kubernetes** โ€” Optional orchestration
--- ## ๐ŸŽ“ Learn More - **[๐Ÿš€ Getting Started Guide](./GETTING_STARTED.md)** โ€” Step-by-step setup and first run - **[๐Ÿ“– Full Documentation](./Development.md)** โ€” Advanced configuration and development - **[๐Ÿค– Agent Architecture](./AGENTS.md)** โ€” Deep dive into agent systems - **[๐Ÿ› ๏ธ Contributing Guide](./CONTRIBUTING.md)** โ€” How to contribute to Wren - **[๐Ÿ“‹ Issue Triage](./ISSUE_TRIAGE.md)** โ€” How we manage issues - **[๐Ÿ‘ฅ Credits](./CREDITS.md)** โ€” Team & contributors - **[๐Ÿ“œ Code of Conduct](./CODE_OF_CONDUCT.md)** โ€” Community guidelines
--- ## ๐Ÿค Contributing We welcome contributions of all sizes! Whether it's bug reports, feature requests, or code contributions, your help makes Wren better. ### Getting Started 1. **Fork** the repository 2. **Create** a feature branch (`git checkout -b feature/your-feature`) 3. **Install** pre-commit hooks (`make install-pre-commit-hooks`) 4. **Make** your changes 5. **Test** thoroughly (`make test`) 6. **Lint** your code (`make lint`) 7. **Commit** with a clear message 8. **Push** and open a Pull Request See [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines.
--- ## ๐Ÿ“Š Language Composition - **Python** 62.1% โ€” Core backend logic - **TypeScript** 34.7% โ€” Frontend & tooling - **HTML** 1.2% โ€” Structure - **Shell** 0.4% โ€” Build scripts - **CSS** 0.4% โ€” Styles - **Jinja** 0.4% โ€” Templates - **Other** 0.8% โ€” Configuration
--- ## ๐Ÿ“œ License **Wren** is open source and released under the **[MIT License](LICENSE)**. Built with โค๏ธ by [Daniel](https://github.com/Daniel-debug-boop) and [contributors](./CREDITS.md).
--- ## ๐Ÿ”— Community & Support - ๐Ÿ’ฌ **Questions?** [Open a discussion](https://github.com/Daniel-debug-boop/Wren/discussions) - ๐Ÿ› **Found a bug?** [Report an issue](https://github.com/Daniel-debug-boop/Wren/issues) - ๐Ÿ’ก **Have an idea?** [Request a feature](https://github.com/Daniel-debug-boop/Wren/issues) - ๐ŸŒ **Website:** [wren.dev](https://assets.wren.dev)

Made with ๐Ÿš€ by AI engineers, for AI engineers

โฌ†๏ธ Back to Top