MADE

One-line: A comprehensive web-based development environment for managing repositories, knowledge bases, and AI agent interactions - optimized for your phone 📱!

MADE (Mobile Agentic Development Environment) is a full-stack Node.js application that provides developers with an integrated workspace for project management, knowledge organization, and AI-powered development assistance. It features a React-based frontend with repository browsing, file editing, markdown-based knowledge management, and seamless agent communication through the A2A protocol.

Key Features

• 📁 Repository Management - Create, browse, and manage multiple code repositories with Git integration
• 🤖 AI Agent Integration - Chat with AI agents for code assistance, project planning, and development guidance
• 📚 Knowledge Base - Organize documentation, notes, and project artifacts with markdown support
• ⚖️ Constitution System - Define and manage development rules, guidelines, and constraints
• 📝 Integrated File Editor - Edit files directly in the browser with live preview capabilities
• 🚀 Publishment Workflows - Streamlined deployment and publishing automation
• 🎨 Modern UI - Responsive React interface with dark/light theme support

Quickstart

# Install dependencies (preferred)
make install

# Run development servers
make run

Table of Contents

• Quickstart
• Installation
• Usage
• Configuration
• Contributing
• License
• Security
• Maintainers

Installation

Install dependencies and start the development environment:

# Clone the repository
git clone https://github.com/tbrandenburg/made.git
cd made

# Install all dependencies (monorepo setup)
make install

# Run both frontend and Python backend
make run

(Alternative: build from source: npm run build && npm run start)

Usage

Minimal example to get started:

# Start the development servers
make run

# Backend runs on: http://localhost:3000
# Frontend runs on: http://localhost:5173

Expected output:

MADE backend listening on http://0.0.0.0:3000
MADE frontend available on http://localhost:5173

Access the web interface at http://localhost:5173 to:

1. Browse Repositories - View and manage your code projects
2. Chat with Agents - Get AI assistance for development tasks
3. Manage Knowledge - Create and organize documentation
4. Define Constitutions - Set development rules and guidelines
5. Edit Files - Use the integrated editor with live preview

Docker Deployment

Container images are provided for both the API backend and the static frontend. The docker-compose.yml file builds and runs the complete stack with one command.

# Build images and start the containers
docker compose up --build

# Backend API:    http://localhost:3000
# Frontend (Nginx): http://localhost:8080

The backend persists its .made workspace inside the named made-data volume defined in the compose file. Environment variables such as MADE_HOME, MADE_WORKSPACE_HOME, MADE_BACKEND_HOST, or MADE_BACKEND_PORT can be overridden by editing the pybackend service configuration.

Manual agent CLI acceptance in Docker

The following process tests a selected Made agent adapter against the real application and CLI in Docker, without mounting host agent configuration or using development ports. Before building, configure docker/pybackend.Dockerfile with the selected CLI's official non-interactive install command (replace the default install step or add a separate layer) and ensure its executable is on PATH. Rebuild whenever the Dockerfile changes. Supply any required credentials at container runtime through environment variables or a dedicated volume; do not bake credentials into the image.

Start the acceptance project with its own Made data, workspace, and agent home volumes:

docker compose -p made-agent-acceptance \
  -f docker-compose.yml -f docker-compose.agent-acceptance.yml \
  up --build -d

The frontend and API are bound to loopback ports 18080 and 13000. In Made Settings, select the adapter matching the installed CLI, save, reload, and confirm the choice persisted. Create a repository in the isolated workspace and add a small fixture file with a unique marker.

Use Playwright MCP at http://127.0.0.1:18080 to verify the real UI flow:

1. Open the fixture repository's Agent chat and select a model available to the container's CLI.
2. Ask the agent to read the fixture file and return its exact marker. Confirm the response appears and a session ID is shown.
3. Send a follow-up asking for the previous marker without naming it. Confirm the answer is correct and the same session continues.
4. Reload the repository page. Confirm the request/response history returns from the selected CLI's session store; use the session picker to reopen it if needed.
5. Confirm Settings still selects the chosen adapter after a reload.

Use explicit Compose files and the same project name for inspection and teardown. This removes only the acceptance stack and its isolated volumes:

docker compose -p made-agent-acceptance \
  -f docker-compose.yml -f docker-compose.agent-acceptance.yml down -v

OpenCode v2 acceptance environment

The Settings page supports opencode-v2 as a separate adapter; the existing opencode selector remains unchanged. To exercise v2 without changing a host OpenCode installation or using the standard development ports, build the dedicated pinned image under a unique Compose project:

docker compose -p made-opencode-v2-acceptance \
  -f docker-compose.yml -f docker-compose.opencode-v2.yml \
  up --build -d

# Run the opt-in real-CLI persistence/resume test inside the v2 container
docker compose -p made-opencode-v2-acceptance \
  -f docker-compose.yml -f docker-compose.opencode-v2.yml \
  exec -T -e MADE_OPENCODE_V2_ACCEPTANCE=1 pybackend \
  .venv/bin/pytest -q tests/integration/test_opencode_v2_acceptance.py

# Remove only this acceptance project and its dedicated volumes
docker compose -p made-opencode-v2-acceptance \
  -f docker-compose.yml -f docker-compose.opencode-v2.yml down -v

This project binds the backend and frontend to 127.0.0.1:13000 and 127.0.0.1:18080. Its project-scoped Docker volumes isolate Made settings, workspace, OpenCode home/config, and the OPENCODE_DB SQLite database. Create or seed a test repository under /workspace inside the backend container, select opencode-v2 in Settings, and verify a real chat, session resume, and reloaded v2 database history at http://127.0.0.1:18080. Keep these explicit Compose files and project name for startup, inspection, and teardown; do not use the default Compose project for this acceptance.

Configuration

Environment variables / config:

• MADE_HOME — string — default: process.cwd() — Base directory for MADE configuration and data storage
• MADE_WORKSPACE_HOME — string — default: process.cwd() — Root directory where repositories are stored
• MADE_BACKEND_HOST — string — default: 0.0.0.0 — Host address for the backend API server
• MADE_BACKEND_PORT — number — default: 3000 — Port for the backend API server

The application automatically creates a .made directory structure:

$MADE_HOME/.made/
├── knowledge/     # Knowledge base articles
├── constitutions/ # Development rules and guidelines
└── settings.json  # Application settings

Command Discovery Locations

MADE loads commands from the following locations (first found are combined):

• $MADE_HOME/.made/commands/, $MADE_HOME/.kiro/prompts/ — pre-installed commands bundled at the MADE home.
• $MADE_WORKSPACE_HOME/.made/commands/, $MADE_WORKSPACE_HOME/.kiro/prompts/ — workspace-scoped commands.
• ~/.made/commands/, ~/.claude/commands/, ~/.codex/commands/, ~/.kiro/commands/, ~/.kiro/prompts/, ~/.opencode/command/ — user commands.
• $MADE_WORKSPACE_HOME/<repo>/.*/commands/**/*.md, $MADE_WORKSPACE_HOME/<repo>/.*/prompts/**/*.md — repository-specific commands inside hidden folders.

API / Reference

The backend provides a RESTful API with endpoints for:

• Repositories: /api/repositories - CRUD operations for code repositories
• Knowledge: /api/knowledge - Manage documentation and knowledge artifacts
• Constitutions: /api/constitutions - Define development rules and constraints
• Agent Communication: /api/repositories/:name/agent - AI agent chat interface
• File Operations: /api/repositories/:name/file - File management and editing
• Settings: /api/settings - Application configuration

📦 Releases & Versioning

This project follows Semantic Versioning (SemVer).

Version Format

Given a version number MAJOR.MINOR.PATCH:

• MAJOR - Incompatible API changes
• MINOR - New functionality (backwards compatible)
• PATCH - Bug fixes (backwards compatible)

Latest Release

Check the latest version:

git fetch --tags
git tag --list | tail -1

Creating a Release

Release version bumps are non-interactive and keep the root, frontend, and backend package versions synchronized with the backend lockfile:

# Patch/minor/major bump (e.g. 0.1.0 -> 0.1.1), BUMP is case-insensitive
make release BUMP=patch
make release BUMP=MAJOR

# Or set an explicit version
make release VERSION=1.2.3

make release runs the fast QA gate (make qa-quick: format + lint + lockfile consistency check + unit tests), bumps package.json, packages/frontend/package.json, and packages/pybackend/pyproject.toml to the same version, regenerates packages/pybackend/uv.lock, commits the changes, creates an annotated vX.Y.Z tag, and pushes the commit and tag together in one push. The pushed tag triggers the GitHub Actions release workflow, which re-validates that the tag version matches all package manifests and runs its own QA before publishing the GitHub Release. make qa (full test suite, including tests/integration, which hits real external agent CLIs) and make system-test are intentionally not part of the release gate — run them manually first if you want that deeper check before releasing.

Release Automation

Releases are automated via GitHub Actions:

1. Developer creates annotated tag (v*.*.* format)
2. CI runs full test suite (make qa)
3. GitHub release is created automatically
4. Release artifacts are built and attached

Tests & CI

Quick Test Commands

# Unit tests (Python backend)
make unit-test

# System tests (Playwright)
make system-test

# All tests with coverage
make test-coverage

# Lint and format code
make qa

CI/CD Notes for Python Tests

If your CI/CD environment runs python -m pytest packages/pybackend/tests/unit directly, make sure to install the backend dependencies first and run pytest inside the uv environment. Otherwise, collection can fail with missing imports like fastapi or frontmatter.

# Option A: use uv (recommended)
cd packages/pybackend
uv sync
uv run python -m pytest tests/unit

# Option B: use pip
python -m pip install -e packages/pybackend

If you run tests from the repo root, use uv run with the backend project so pytest sees the uv environment:

uv run --project packages/pybackend python -m pytest packages/pybackend/tests/unit

Testing Execution Patterns

For Unit Tests (Jest):

# Simple - no dependencies required
npm test

For End-to-End Tests (Playwright):

Playwright tests require the full application stack running. Follow this sequence:

# 1. First-time setup (one-time only)
npm install
npx playwright install                    # Download browser binaries
sudo npx playwright install-deps         # Install system dependencies (optional)

# 2. Start application servers (keep running)
# Use make run to start both services:
make run
# Wait for both:
# "✅ Backend started" and "VITE v5.4.21 ready"

# 3. Verify server connectivity (optional)
curl http://localhost:3000 -I            # Backend health check
curl http://localhost:5173 -I            # Frontend health check

# 4. Run tests (separate terminal)
# Terminal 3 - Tests:
npx playwright test                       # All tests
npx playwright test --grep "test name"   # Specific test
npx playwright test --headed             # Visual debugging

Alternative - Combined Server Start:

# Start both servers in background
make run &
sleep 5                                   # Wait for startup
npx playwright test                       # Run tests

Testing Architecture

Testing follows the pyramid approach:

• Unit Tests - Core business logic and services (pytest)
• Integration Tests - API endpoints and database interactions (pytest)
• System Tests - Full user journeys and workflows (Playwright)

Contributing

Please read CONTRIBUTING.md (or follow the short flow below):

1. Fork the project
2. Create a branch feature/your-feature
3. Add tests and documentation
4. Open a pull request

Development setup:

# Install dependencies
make install

# Start development servers with hot reload
make run

# Run quality assurance checks before committing
make qa

License

This project is licensed under the MIT License — see the LICENSE file for details.

Security

• Never commit secrets or API keys to the repository
• Use environment variables for sensitive configuration
• Follow secure coding practices for file operations
• Report security issues privately to the maintainers

Maintainers

• Tom Brandenburg — contact: GitHub Profile