wren-ai

---

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

✅ Node.js 22.12.x or later
✅ Python 3.12+ with uv or poetry  
✅ Docker (optional, for sandboxed execution)
✅ Git

Launch Wren (3 steps)

# 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 in your browser and start coding!

Need detailed setup instructions? Check out GETTING_STARTED.md

Run with Docker

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

# Install all dependencies (backend + frontend)
make build

# Install pre-commit hooks (required before committing)
make install-pre-commit-hooks

Development Commands

# 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

# 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 <specific-files>  # Avoid git add .
git commit -m "Your message"
git push

All pre-commit checks MUST pass before merging. See 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 — Step-by-step setup and first run
• Full Documentation — Advanced configuration and development
• Agent Architecture — Deep dive into agent systems
• Contributing Guide — How to contribute to Wren
• Issue Triage — How we manage issues
• Credits — Team & contributors
• Code of Conduct — 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 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.

Built with by Daniel and contributors.

---

Community & Support

• Questions? Open a discussion
• Found a bug? Report an issue
• Have an idea? Request a feature
• Website: wren.dev