Skip to content
conciv-devPublic

About

An embeddable AI dev agent for your running app — chat, page control, and live tests, injected into the page via a Vite plugin.

Topics

Resources

Contributing

Stars

7 stars

Watchers

0 watching

Forks

Repository files navigation

conciv: Claude Code, living inside your running app

✦  conciv

Conceive it.
Claude Code, living inside your running app.
Add one plugin. Then chat, let it drive the page, and run your tests,
without ever leaving the thing you're building.

Website  ·  Example app  ·  Docs  ·  Report a bug

npm CI License Node Status


What is conciv?

conciv puts an AI dev agent inside the app you are already running. Add one build plugin, and a conciv button appears in your dev preview. Open it and you're talking to an agent that can see the page you're building, drive it, edit your source, and run your tests, all in the same window, without a second terminal or a context switch.

It's dev-only (never shipped to production) and harness-agnostic: it drives a real coding CLI under the hood (Claude Code today, Codex and others behind one interface), so the agent is as capable as the tool you already trust.

Features

  • 💬  Chat in-app: talk to an agent that sees your running page, streams its reasoning, and calls tools live.
  • 🕹️  Page control: it grabs elements, clicks, fills, inspects React props/state, and live-edits the DOM to preview changes.
  • 🧪  Live tests: run Vitest and watch pass/fail result cards render right inside the app.
  • 🧩  Plugins: add a plugin to plugins or conciv/plugins/ and get new agent tools with their own cards and panels.
  • 🎨  Shared whiteboard: an Excalidraw canvas you and the AI draw on together, with source-anchored comments.
  • ✅  Approvals: risky or networked commands surface an Approve / Deny card before they run.
  • 🔌  One plugin: Vite, webpack, Rspack, Rollup, or esbuild. Dev-only, never in your production bundle.
  • 🤝  Harness-agnostic: Claude Code today; Codex and others behind a single capability interface.
  • 🌘  Zero style leak: the widget lives in an open Shadow DOM, isolated from your app's CSS.

How it works

Architecture: the browser widget talks to @conciv/core over /api/* (SSE + JSON); core spawns the harness (claude/codex); the plugin injects the widget

@conciv/unplugin boots a framework-free hono engine (@conciv/core) behind a set of /api/* routes on its own dev port, spawns a headless harness (default claude -p), and injects a Solid widget into your previewed page. The widget probes /api/chat/session on load and only shows the conciv button when the dev routes are live, so it stays inert on a plain preview.

Try it live

No install needed: open conciv.dev, click "Try it live", and paste the pairing prompt into Claude Code (or run the npx @conciv/try command it shows). The widget on the landing page connects to the agent on your machine. Everything stays local: the core binds 127.0.0.1 only, gated by a one-time token, and prompts never touch our servers.

Quickstart

npm i -D @conciv/it

Add the plugin to your app's vite.config.ts:

import {defineConfig} from 'vite'
import conciv from '@conciv/it/plugin/vite'

export default defineConfig({
  plugins: [conciv()],
})

Make sure the Claude Code CLI (claude) is on your PATH, start your dev server, and click the conciv button in the corner of your app.

Override defaults via conciv({harness, plugins, port, …}). Other bundlers are one import away: @conciv/it/plugin/webpack, /rspack, /rollup, /esbuild, /nextjs.

Plugins

Teach the agent new tricks with a plugin. List it in plugins (an npm package or a local directory, with options as ['name', {...}]) or drop it in conciv/plugins/, and the engine loads it live. A plugin adds agent tools, a result card per tool and panels in the widget, and can be added or removed while the app runs. Plugins ship with a real test harness: @conciv/plugin-testkit boots the real engine with your plugin loaded and a fake model.

Two first-party plugins show what the contracts can do, the whiteboard and test-runner plugins (the built-ins are the page and terminal plugins):

  • 🎨  Whiteboard: a plugin with a shared Excalidraw canvas over your dev app. You sketch, the AI draws back (real editable elements, mermaid included), with source-anchored comments and pins kept in the plugin's own storage.
  • 🧪  Test runner: a plugin that runs your tests (Vitest and Playwright). The Tests tab streams live rows, and a card shows the finished run in the thread.

Supported tools

Area Full support In progress
Harnesses Claude Code (claude -p), Codex Gemini CLI, opencode, Pi
Bundlers Vite webpack, Rspack, Rollup, esbuild
Tests Vitest, Playwright Jest, node:test

Packages

Install these. Everything else on npm under @conciv/* is internal and comes in automatically:

Package What it is
@conciv/it The one you install. Thin umbrella: @conciv/it/plugin/vite (+ webpack/rspack/rollup/esbuild/nextjs).
@conciv/plugin-testkit Boots the real engine with your plugin loaded and a fake model, for plugin tests through the real contract.
@conciv/plugin-test-runner The test-runner plugin: plugins: [['@conciv/plugin-test-runner', {runner: 'vitest'}]].
@conciv/try npx @conciv/try --token <t>: try conciv live on conciv.dev with the agent already on your machine.

Under the hood (installed automatically by @conciv/it):

Package What it is
@conciv/protocol Shared wire types + define* factories (chat, generative UI, test, page, harness). Zero-runtime.
@conciv/core The framework-free hono engine: every /api/* route, session, uiBus, harness + test registries.
@conciv/harness Harness adapters behind a capability interface: Claude + Codex, plus Gemini/opencode/Pi stubs.
@conciv/unplugin The dev agent as an unplugin: vite (full) + webpack/rspack/rollup/esbuild. Boots core + injects the widget.
@conciv/embed The browser half: mounts the conciv Solid app into an open Shadow DOM, with the chat UI, cards, and page-control driver.
@conciv/cli The conciv CLI the agent calls from Bash: tools page / test, plugin call server.

Documentation

Full docs live at conciv.dev and in apps/site/content/docs: quick-start guides per bundler, usage (chat, page control, live tests, approvals), harness and test-runner configuration, and troubleshooting.

Repository blueprint

Every package, app and source directory carries a README.md with its interface, invariants, side effects and the command that verifies it. Start from the three top-level blueprints and follow the links down.

Subdirectories & System Boundaries

  • packages: packages/README.md - the npm packages: engine and plugin, shared contracts, the browser widget and UI kits, host framework SDKs, and private repo tooling.
  • apps: apps/README.md - the widget UI (@conciv/app), the conciv.dev site, the Storybook and the example host apps.
  • native: native/README.md - the Swift ConcivWidget iOS SDK and the ConcivDemo app.

Global Invariants

  • Everything is ESM, Node >= 26, one pnpm workspace with catalog-pinned dependencies and turbo as the task graph.
  • Code shared between the browser and Node lives in a contract package (protocol, contract, plugin, grab); the browser never imports a server entry.
  • The public package set is PUBLIC_PACKAGES in packages/publish, and every other @conciv/* package is internal to @conciv/it.
  • The engine binds loopback only; cross-origin access is gated by the Host/Origin middleware in packages/core/src/lib.

Global Side Effects

  • The engine writes its SQLite database, port file and endpoint discovery file under the project's state directory and ~/.conciv.
  • Harness adapters read the user's agent transcripts (~/.claude, ~/.codex, ~/.pi, opencode's database) and spawn the agent binaries.
  • The Vite plugin boots the engine process, injects the widget meta tags and script into served HTML and serves the widget boot script from the dev server.
  • conciv-publish publishes to npm, pushes git tags and force-pushes the conciv-swift mirror.

System Verification

  • Run: pnpm typecheck && pnpm lint && pnpm test at the repo root (turbo runs every package), or pnpm test:affected for packages changed since origin/main.

Contributing

Issues and PRs are welcome. This is a young project moving fast, so the best first step is to run the example app, find something rough, and open an issue.

pnpm install
pnpm dev        # runs the tanstack-start example with conciv wired in

See CONTRIBUTING.md for setup, everyday commands, and PR guidelines.

Star history

Star history chart for conciv-dev/conciv

License

MIT © conciv


conciv · as in @conciv/it. Say it out loud.
Built with hono, Solid, and a real coding agent living in the page.

About

An embeddable AI dev agent for your running app — chat, page control, and live tests, injected into the page via a Vite plugin.

Topics

Resources

Contributing

Stars

7 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages