{"id":45919281,"url":"https://github.com/13point5/agent-canvas","last_synced_at":"2026-02-28T08:18:13.582Z","repository":{"id":340287021,"uuid":"1154736407","full_name":"13point5/agent-canvas","owner":"13point5","description":null,"archived":false,"fork":false,"pushed_at":"2026-02-24T04:51:26.000Z","size":1727,"stargazers_count":16,"open_issues_count":5,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-24T10:42:24.958Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/13point5.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-02-10T18:10:02.000Z","updated_at":"2026-02-17T11:13:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/13point5/agent-canvas","commit_stats":null,"previous_names":["13point5/agent-canvas"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/13point5/agent-canvas","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/13point5%2Fagent-canvas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/13point5%2Fagent-canvas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/13point5%2Fagent-canvas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/13point5%2Fagent-canvas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/13point5","download_url":"https://codeload.github.com/13point5/agent-canvas/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/13point5%2Fagent-canvas/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29928411,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-27T19:37:42.220Z","status":"online","status_checked_at":"2026-02-28T02:00:07.010Z","response_time":90,"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":[],"created_at":"2026-02-28T08:18:13.145Z","updated_at":"2026-02-28T08:18:13.567Z","avatar_url":"https://github.com/13point5.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agent Canvas\n\nA whiteboard CLI for coding agents like Claude Code, Codex, OpenCode, Amp, Gemini CLI, and more.\n\nUse the `agent-canvas` CLI to orchestrate swarms of agents on the same board, compare multiple implementations of the same feature side-by-side, and keep each agent isolated with git worktrees while you pick the best approach.\n\n## Main Use Cases\n\n### 1) Architecture planning and feature iteration\n\nAsk a coding agent to draw architecture and sequence diagrams so you can:\n\n- plan architecture before implementation\n- understand how an existing feature works end-to-end\n- iterate on design and flow changes quickly\n\n![Architecture and sequence diagrams](docs/images/features/architecture-diagrams.png)\n\n### 2) PR review with logical diff chunks and tested screenshots\n\nAsk a coding agent to lay out PR changes as small, logical chunks of related diffs, then attach screenshots of the tested feature (for example with Playwright or agent-browser).\n\n![PR review grouped diffs and screenshots](docs/images/features/pr-review.png)\n\n## Prerequisites\n\n- [Bun](https://bun.sh/) (v1.0+)\n\n## Quick Start (Linked CLI)\n\nBuild everything and link the `agent-canvas` command globally:\n\n```bash\nbun install\nbun run build:link\n```\n\nThis runs `build` (shared, server, web, cli), bundles the web app into the CLI, and links it via `bun link`.\n\n### Add the Skill to Claude Code\n\nThe `skills/` directory contains a skill that teaches Claude Code how to use agent-canvas. Skills are directories with a `SKILL.md` inside.\n\nRun this from the agent-canvas repo (where you just ran `build:link`):\n\n```bash\nCANVAS_DIR=$PWD\n\n# Option 1: Symlink the skill directory (stays in sync with updates)\nmkdir -p ~/.claude/skills\nln -s \"$CANVAS_DIR/skills\" ~/.claude/skills/agent-canvas\n\n# Option 2: Copy the skill directory\nmkdir -p ~/.claude/skills\ncp -r \"$CANVAS_DIR/skills\" ~/.claude/skills/agent-canvas\n```\n\nNow use the CLI:\n\n```bash\n# Start the server and open the browser\nagent-canvas open\n\n# Start without opening a browser (for agents)\nagent-canvas open --headless\n\n# Optional: pick a specific port (default is 3456; if occupied, CLI falls back to an open port)\nagent-canvas open --port 3456\n\n# Check status\nagent-canvas status\n\n# Create a board\nagent-canvas boards create \"My Board\"\n\n# List boards\nagent-canvas boards list\n\n# Draw shapes (board must be open in browser)\nagent-canvas shapes create --board \u003cboard-id\u003e --shapes '[\n  {\"type\": \"geo\", \"x\": 100, \"y\": 100, \"props\": {\"w\": 200, \"h\": 100, \"geo\": \"rectangle\", \"text\": \"Hello\"}}\n]'\n\n# Read shapes back (compact YAML-like summaries by default)\nagent-canvas shapes get --board \u003cboard-id\u003e\n\n# Read shapes as JSON (machine-readable)\nagent-canvas shapes get --board \u003cboard-id\u003e --json\n\n# Read only specific shapes (minimal summaries)\nagent-canvas shapes get --board \u003cboard-id\u003e --ids '[\"shape:abc\", \"shape:def\"]'\n\n# Read full shape payloads as JSON (for file-based analysis)\nagent-canvas shapes get --board \u003cboard-id\u003e --full --json \u003e shapes.json\n\n# Add an agent comment thread to a markdown shape\nagent-canvas comments add \\\n  --board \u003cboard-id\u003e \\\n  --shape \u003cmarkdown-shape-id\u003e \\\n  --target '{\"type\":\"text\",\"start\":10,\"end\":30,\"quote\":\"selected text\"}' \\\n  --body \"Please tighten this section\" \\\n  --author agent \\\n  --agent \"Codex\"\n\n# Add another message to an existing thread\nagent-canvas comments add \\\n  --board \u003cboard-id\u003e \\\n  --shape \u003cmarkdown-shape-id\u003e \\\n  --comment \u003cthread-id\u003e \\\n  --body \"I pushed a revision for this\" \\\n  --author agent \\\n  --agent \"Codex\"\n\n# Stop the server\nagent-canvas close\n```\n\nDefault `shapes get` output is compact YAML-like text:\n- It is optimized for lower token usage in agent contexts\n- Use `--json` for machine-readable JSON output\n\nMinimal-mode `shapes get` output is intentionally partial:\n- It includes only `id`, `type`, and selected `props`\n- Long values are truncated as `... (+N chars)`\n- `code-diff` summaries include only `oldFile.name` / `newFile.name` (no file contents)\n- `props._partial: true` means props are summarized, not complete\n- Use `--full --json` when you need complete shape payloads\n\n## Development Mode\n\nRun the server and web app with hot reload:\n\n```bash\nbun install\nbun run dev\n```\n\nThis starts the Hono server (with `--watch`) and Vite dev server concurrently. The web app is available at the URL printed in the terminal.\n\n`bun run dev` now auto-assigns non-conflicting server/web ports per worktree so you can run multiple worktrees in parallel.\nIn this mode, the web app also connects directly to the selected server WebSocket URL to avoid Vite ws proxy reset noise.\n\nTo run CLI commands against the dev server:\n\n```bash\nbun run cli -- boards list\nbun run cli -- shapes get --board \u003cboard-id\u003e\nbun run cli -- shapes get --board \u003cboard-id\u003e --json\nbun run cli -- shapes get --board \u003cboard-id\u003e --ids '[\"shape:abc\"]'\nbun run cli -- shapes get --board \u003cboard-id\u003e --full --json \u003e shapes.json\n```\n\nThe CLI resolves the server for the current worktree automatically. To target a different running instance explicitly, set `AGENT_CANVAS_URL`.\n\n## Project Structure\n\n```\napps/\n  cli/         CLI tool (Commander) — the `agent-canvas` command\n  web/         React + TLDraw frontend (Vite)\npackages/\n  server/      Hono HTTP + WebSocket server\n  shared/      Zod schemas and TypeScript types\nskills/        Skill documentation for AI agents\n```\n\n## How It Works\n\nShape operations go through a WebSocket relay:\n\n```\nCLI → HTTP API → Server (validates with Zod) → WebSocket → Browser (TLDraw editor) → WebSocket response → HTTP response → CLI\n```\n\nThe browser must have the board open for shape commands to work. The server acts as a relay between the CLI and the TLDraw editor running in the browser.\n\n## Scripts\n\n| Script                  | Description                                 |\n| ----------------------- | ------------------------------------------- |\n| `bun run dev`           | Start server + web with hot reload          |\n| `bun run build`         | Build all packages                          |\n| `bun run build:link`    | Build, bundle web into CLI, and `bun link`  |\n| `bun run cli -- \u003cargs\u003e` | Run CLI commands against dev server         |\n| `bun run format`        | Format with Biome + Prettier                |\n| `bun run clean`         | Remove all build artifacts and node_modules |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F13point5%2Fagent-canvas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F13point5%2Fagent-canvas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F13point5%2Fagent-canvas/lists"}