{"id":50747235,"url":"https://github.com/tranbathanhtung/dddx","last_synced_at":"2026-06-10T22:02:17.565Z","repository":{"id":363458794,"uuid":"1262814030","full_name":"tranbathanhtung/dddx","owner":"tranbathanhtung","description":"An AI design agent that lives in your repo and browser. Works with your favorite coding agent — Open-source Claude Design/Google Stitch.","archived":false,"fork":false,"pushed_at":"2026-06-09T01:10:29.000Z","size":22205,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-09T03:10:13.525Z","etag":null,"topics":["agent","ai","claude-code","claude-design","codex","cursor","design","devtools","llm","opencode"],"latest_commit_sha":null,"homepage":"https://www.dddx.dev","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tranbathanhtung.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-08T10:50:15.000Z","updated_at":"2026-06-09T01:10:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tranbathanhtung/dddx","commit_stats":null,"previous_names":["tranbathanhtung/dddx"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/tranbathanhtung/dddx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tranbathanhtung%2Fdddx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tranbathanhtung%2Fdddx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tranbathanhtung%2Fdddx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tranbathanhtung%2Fdddx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tranbathanhtung","download_url":"https://codeload.github.com/tranbathanhtung/dddx/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tranbathanhtung%2Fdddx/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34172196,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai","claude-code","claude-design","codex","cursor","design","devtools","llm","opencode"],"created_at":"2026-06-10T22:02:16.737Z","updated_at":"2026-06-10T22:02:17.560Z","avatar_url":"https://github.com/tranbathanhtung.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dddx\n\n**Design where you code.** dddx is an AI design agent that lives in your repo and browser. It runs alongside your app, connects to coding agents like Cursor, Claude Code, OpenCode, and Codex, and gives you a Studio for chat, live preview, and design prototypes.\n\n![dddx Studio — chat, live preview, and design canvas](apps/web/public/app.png)\n\n- **Site:** [dddx.dev](https://dddx.dev)\n- **Install:** `curl -fsSL https://dddx.dev/install | bash`\n\n## What it does\n\n- Starts your dev server and proxies it into **Studio** with live preview\n- Runs **agent mode** against your main codebase\n- Runs **design mode** in isolated sandboxes under `.dddx/designs/\u003cslug\u003e/`\n- Ships **plugins** (themes, HTML templates, agent skills) from a local marketplace\n- Works with Node, Python, and Rails projects (auto-detected)\n\n## Install\n\n```sh\ncurl -fsSL https://dddx.dev/install | bash\n```\n\nThe installer puts `dddx` in `~/.dddx/bin` and adds it to your shell `PATH`. Node.js 18+ is required for the dev proxy.\n\nOther install paths:\n\n```sh\nnpm install -g @dddx/cli\nbun add -g @dddx/cli\n```\n\nUpgrade or check version:\n\n```sh\ndddx upgrade          # latest from npm\ndddx upgrade 0.1.4    # specific version\ndddx version\n```\n\n## Quick start\n\nFrom any project with a `dev` script:\n\n```sh\ncd my-app\ndddx\n```\n\ndddx detects your package manager and framework, starts your app, opens Studio in the browser, and wires up the AI chat panel.\n\nCommon flags:\n\n```sh\ndddx -p 5173                    # proxy port (default: 3000)\ndddx --script dev               # npm/bun script to run (default: dev)\ndddx --command \"vite --port 5173\"  # override auto-detection\ndddx --startup-timeout 60       # wait longer for the app to boot\ndddx --debug                    # verbose logs\ndddx --no-open-browser          # skip auto-opening Studio\n```\n\n## CLI reference\n\n| Command | Description |\n| --- | --- |\n| `dddx` | Start dev environment + Studio |\n| `dddx version` / `dddx v` | Print installed CLI version |\n| `dddx upgrade [version]` | Upgrade `@dddx/cli` |\n| `dddx plugin add \u003csource\u003e` | Add a plugin marketplace to `~/.dddx/plugins/\u003cid\u003e` |\n| `dddx plugin remove \u003cid\u003e` | Remove an installed marketplace |\n| `dddx plugin index` | Generate `plugin.json` or `marketplace.json` |\n| `dddx plugin validate` | Validate plugin manifests |\n\n### Plugin commands\n\n```sh\n# Add the official marketplace from GitHub\ndddx plugin add https://github.com/tranbathanhtung222/ddd\n\n# Index a plugin folder (for authors)\ndddx plugin index --dir ./my-plugin --name \"My Plugin\"\n\n# Index a collection and capture HTML previews\ndddx plugin index --dir . --collection --capture-previews\n```\n\nPlugins install under `~/.dddx/plugins/`. Each plugin can ship **themes** (DESIGN.md style guides), **templates** (HTML starting points), and **skills** (agent instructions).\n\n## Configuration\n\ndddx reads config from `package.json` under a top-level `\"dddx\"` key.\n\n### Single app\n\nFor a normal project, dddx runs the `dev` script in the current directory. You can override per-package settings:\n\n```json\n{\n  \"dddx\": {\n    \"port\": \"5173\",\n    \"script\": \"dev\",\n    \"name\": \"My App\"\n  }\n}\n```\n\n| Field | Description |\n| --- | --- |\n| `script` | Dev script name (default: `dev`) |\n| `port` | Proxy port for Studio preview |\n| `name` | Label shown in Studio |\n\n### Monorepo\n\nIn a workspace with multiple packages that have `dev` scripts, list the apps you want proxied in the **root** `package.json`:\n\n```json\n{\n  \"dddx\": {\n    \"script\": \"dev\",\n    \"apps\": {\n      \"apps/web\": { \"port\": \"3000\" },\n      \"apps/docs\": { \"port\": \"3001\", \"name\": \"Docs\" }\n    }\n  }\n}\n```\n\n- Every workspace package with a matching `dev` script is started\n- Only packages listed under `dddx.apps` get a Studio preview proxy\n- If a monorepo has no `dddx.apps`, dddx prints a config guide and exits\n\nThis repo's root config:\n\n```json\n{\n  \"dddx\": {\n    \"apps\": {\n      \"apps/web\": { \"port\": \"3000\" }\n    }\n  }\n}\n```\n\n## Project layout\n\nWhen you run dddx in a project, it creates a `.dddx/` directory:\n\n```\nmy-project/\n├── .dddx/\n│   ├── designs/          # design-mode prototypes (one folder per slug)\n│   │   └── landing/\n│   │       ├── hero.html\n│   │       └── hero.css\n│   └── dev.json          # local dev state (e.g. studio opened timestamp)\n├── package.json\n└── src/\n```\n\n### Agent vs design mode\n\n| Mode | Write target | Use for |\n| --- | --- | --- |\n| **agent** | Main project (outside `.dddx/designs/`) | Shipping code, refactors, features |\n| **design** | `.dddx/designs/\u003cslug\u003e/` | Visual prototypes, flows, mockups |\n\nDesign prototypes are plain HTML/CSS/JS served over HTTP. Each top-level `.html` file becomes a canvas frame in Studio. Use device suffixes for frame size:\n\n- `screen.html` — desktop (1440×1024)\n- `screen.tablet.html` — tablet (834×1112)\n- `screen.mobile.html` — mobile (390×844)\n\nSee `examples/react/.dddx/designs/` for real prototypes.\n\n## Supported coding agents\n\ndddx connects to agents through the Agent Client Protocol (ACP):\n\n- **Cursor** — agent, plan, ask modes\n- **OpenCode** — build, plan modes\n- **Claude Code** (via ACP)\n- **Codex** (via ACP)\n\nAgent capabilities and model options are defined in `packages/cli/src/agents/registry.json`.\n\n## Environment variables\n\n| Variable | Description |\n| --- | --- |\n| `DDDX_STUDIO_PORT` | Studio worker port (default: `4723`) |\n| `DDDX_ORIGIN` | Override CDN/site origin (staging, local web app) |\n\nBun loads `.env` automatically when developing this repo.\n\n## Repository structure\n\nThis is a [Turborepo](https://turborepo.dev) monorepo managed with [Bun](https://bun.sh).\n\n```\nddd/\n├── apps/\n│   └── web/                 # Marketing site + install script (dddx.dev)\n├── packages/\n│   ├── cli/                 # @dddx/cli — dev server, Studio, MCP, plugins\n│   ├── sdk/                 # @dddx/sdk — Studio UI (React)\n│   ├── plugins-official/    # Official themes, templates, and skills\n│   └── r2/                  # R2/CDN publish helpers\n├── examples/\n│   └── react/               # Vite + React example with design prototypes\n├── package.json             # Workspace root + dddx.apps config\n└── turbo.json\n```\n\n### Packages\n\n| Package | npm name | Description |\n| --- | --- | --- |\n| `packages/cli` | `@dddx/cli` | CLI binary, dev proxy, Studio server, plugin system |\n| `packages/sdk` | `@dddx/sdk` | Studio frontend bundled and served from R2 in production |\n| `packages/plugins-official` | — | Official plugin marketplace (design-md, hallmark, hyperframes, …) |\n| `packages/r2` | `@dddx/r2` | Internal S3/R2 upload utilities |\n| `apps/web` | — | Next.js landing page and `/install` route |\n\n## Development\n\n### Prerequisites\n\n- [Bun](https://bun.sh) 1.3+ (package manager for this repo)\n- Node.js 18+ (used by the CLI dev proxy at runtime)\n\n### Setup\n\n```sh\ngit clone https://github.com/tranbathanhtung222/ddd.git\ncd ddd\nbun install\n```\n\n### Run from source\n\n```sh\n# CLI with hot reload (from repo root or any project)\nbun run dddx\n\n# Built CLI binary (after build:caps)\nbun run dddx:prod\n\n# Example React app\ncd examples/react\nbun run dddx\n```\n\n### Scripts\n\n| Script | Description |\n| --- | --- |\n| `bun run dddx` | Run CLI from source with hot reload |\n| `bun run dddx:prod` | Run built `packages/cli/bin/dddx` |\n| `bun run dev` | Start all turbo `dev` tasks |\n| `bun run build` | Build all packages |\n| `bun run typecheck` | Type-check all workspaces |\n| `bun run lint` | Lint all packages |\n| `bun run build:caps` | Build agent capability bundles |\n| `bun run build:plugins` | Index official plugins + capture previews |\n| `bun run clean` | Remove build artifacts |\n\nBuild and publish the CLI:\n\n```sh\nbun run --cwd packages/cli build\nbun run --cwd packages/cli publish\n```\n\nBuild and publish the SDK to R2:\n\n```sh\nbun run --cwd packages/sdk build\nbun run --cwd packages/sdk publish\n```\n\nRun the marketing site locally:\n\n```sh\nbun run dev --filter=web\n# or\ncd apps/web \u0026\u0026 bun dev\n```\n\n### Testing\n\n```sh\nbun test                          # all tests\nbun test packages/cli/src/...     # specific file\n```\n\n## License\n\nSee individual package licenses. Official plugins include MIT-licensed themes and templates from third-party collections (e.g. [awesome-design-md](https://github.com/VoltAgent/awesome-design-md)).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftranbathanhtung%2Fdddx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftranbathanhtung%2Fdddx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftranbathanhtung%2Fdddx/lists"}