chamba

A browser workspace paired to your terminal coding agent over one shared conversation.

Quick start

Install the skill for your agent:

npx chamba@latest skill install

Then, in your agent, run /chamba (or ask it to "open chamba"). It opens a browser workspace where you read rendered markdown, paste screenshots the agent can read, and point at UI - all in the same thread as the terminal.

When the session opens, the browser asks how you will use it. Pick everyday for open conversation beside your app, or spec for a structured interview that builds a spec package with Draft, Mock, and Diagram surfaces. The choice sets up that same session; the agent then drives it accordingly.

Add --global to install the skill for every project (~/.claude/skills).

Testing

pnpm check is the full gate: typecheck (the packages plus the test sources, via tsconfig.test.json), lint, both builds (inject, web), then pnpm test and pnpm test:e2e:flake. pnpm test runs Vitest's two projects (unit + integration). pnpm test:e2e runs the Playwright suite once; pnpm test:e2e:flake repeats it three times with no retries so an intermittent failure cannot hide, and is the e2e variant the gate runs on every push. pnpm test:e2e:video runs the suite once and records a video of every flow under test-results/e2e/, for watching the browser interactions.

| Path | Covers | Run by | | --- | --- | --- | | packages/*/src/**/*.test.ts | Unit tests colocated with each package (shared, server, cli, inject): pure schema and logic. | pnpm test (Vitest unit project, parallel). | | tests/integration/ | Integration: real server and CLI processes over real ports and the WebSocket transport (roundtrip, durability, annotations, attachments, issues, spec sessions, init, lifecycle). Shared helpers live in tests/support/. | pnpm test (Vitest integration project, sequential forks with long timeouts, since parallel port binding would flake). | | tests/e2e/ | End-to-end: a real browser drives the production web build against a real server and CLI, proving the human and agent exchange renders live. | pnpm test:e2e (Playwright, serial; pretest:e2e installs the browser first). | | tests/fixtures/ | Sample apps for the "Your app" surface: a Vite + React app on port 4001 and a Next.js app on port 4002. The e2e suite drives the React app as a cross-origin annotation target; both are runnable by hand for manual exploration. | pnpm fixture:react, pnpm fixture:next (see tests/fixtures/README.md). |

The e2e browser runs inside the dev container, which provides the Chromium system libraries and fonts it needs.

Local package testing

pnpm -s chamba drives the working copy: it runs the source under tsx (no build) and resolves only inside this repo, so it is always the local version, never the published package.

One command

From the repo root:

pnpm try:chamba

It waits until the Next fixture is serving :4002, then drops you straight into a sandbox session in the same terminal tab. This tab never starts the fixture itself, so it can never leave one running in the background. If nothing is serving :4002 yet, it prints the command to start the fixture and waits; open a separate tab in the repo root, run pnpm dev:next (or pnpm re:dev:next for a clean reinstall first), and this tab continues on its own once the port is up.

The individual pieces

Each runs from the repo root; add -w (pnpm -w dev:next) to run it from any subdir.

• pnpm dev:next - Next fixture on :4002 (fast; assumes deps are installed via pnpm install).
• pnpm re:dev:next - clean build dirs, reinstall, then the same (the container shadows node_modules, so this matters for a truly fresh run).
• pnpm fixtures:stop - stop the fixture dev servers (React on :4001, Next on :4002). Run it where the fixture runs (host or container); it kills only the fixture processes, never Docker's port forwarder.
• npx totopo - start the workspace's sandbox session; runs from anywhere under the repo.
• pnpm -s chamba open - inside the session, opens chamba and prints its URL.

Confirm the workspace publishes chamba's port with CHAMBA_HOST=0.0.0.0 and CHAMBA_PORT=4319; the fixture's inject script targets :4319. Then open the printed chamba URL, point the "Your app" tab at :4002, and do real work: paste a screenshot, annotate, run a spec session.

A personal tool, published as-is with no stability promises.