https://github.com/viagen-dev/viagen
Vite dev server plugin that exposes endpoints for chatting with Claude Code SDK
https://github.com/viagen-dev/viagen
claude-code github vercel vite
Last synced: about 10 hours ago
JSON representation
Vite dev server plugin that exposes endpoints for chatting with Claude Code SDK
- Host: GitHub
- URL: https://github.com/viagen-dev/viagen
- Owner: viagen-dev
- License: mit
- Created: 2026-02-15T03:55:25.000Z (8 days ago)
- Default Branch: main
- Last Pushed: 2026-02-20T04:48:07.000Z (3 days ago)
- Last Synced: 2026-02-20T08:09:55.351Z (2 days ago)
- Topics: claude-code, github, vercel, vite
- Language: TypeScript
- Homepage: https://viagen.dev
- Size: 589 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# viagen
A Vite dev server plugin and CLI tool that enables you to use Claude Code in a sandbox — instantly.
## Prerequisites
- [Claude](https://claude.ai/signup) — Max, Pro, or API plan. The setup wizard handles auth.
- [Vercel](https://vercel.com/signup) — Free plan works. Sandboxes last 45 min on Hobby, 5 hours on Pro.
- [GitHub CLI](https://cli.github.com) — Enables git clone and push from sandboxes.
## Quick Setup (Claude Code Plugin)
```
/plugin marketplace add viagen-dev/viagen-claude-plugin
/plugin install viagen@viagen-marketplace
```
**Restart Claude Code to load the plugin.**
```
/viagen-install
```
The plugin will handle npm installation, vite config updates, and run the setup wizard for you.
## Manual Setup
### Step 1 — Add viagen to your app
```bash
npm install --save-dev viagen
```
```ts
// vite.config.ts
import { defineConfig } from 'vite'
import { viagen } from 'viagen'
export default defineConfig({
plugins: [viagen()],
})
```
### Step 2 — Setup
```bash
npx viagen setup
```
The setup wizard authenticates with Claude, detects your GitHub and Vercel credentials, and captures your git remote info — all written to your local `.env`. This ensures sandboxes clone the correct repo instead of inferring it at runtime.
You can now run `npm run dev` to start the local dev server. At this point you can launch viagen and chat with Claude to make changes to your app.
### Step 3 — Sandbox
```bash
npx viagen sandbox
```
Deploys your dev server to a remote Vercel Sandbox — an isolated VM-like environment where Claude can read, write, and push code.
```bash
# Deploy on a specific branch
npx viagen sandbox --branch feature/my-thing
# Set a longer timeout (default: 30 min)
npx viagen sandbox --timeout 60
# Auto-send a prompt on load
npx viagen sandbox --prompt "build me a landing page"
# Stop a running sandbox
npx viagen sandbox stop
```
## Plugin Options
```ts
viagen({
position: 'bottom-right', // toggle button position
model: 'sonnet', // claude model
panelWidth: 375, // chat panel width in px
overlay: true, // fix button on error overlay
ui: true, // inject chat panel into pages
sandboxFiles: [...], // copy files manually into sandbox
systemPrompt: '...', // custom system prompt (see below)
editable: ['src','conf'], // files/dirs editable in the UI
})
```
### SSR Frameworks (React Router, Remix, SvelteKit, etc.)
For plain Vite apps, the chat panel is injected automatically. SSR frameworks render their own HTML, so you need to add one script tag to your root layout:
```html
```
For React Router, add it to `app/root.tsx`:
```tsx
export default function Root() {
return (
{/* ... */}
{/* ... */}
)
}
```
### Editable Files
Add a file editor panel to the chat UI:
```ts
viagen({
editable: ['src/components', 'vite.config.ts']
})
```
Paths can be files or directories (directories include all files within). The editor appears as a "Files" tab in the chat panel.
The default system prompt:
```
You are embedded in a Vite dev server as the "viagen" plugin. Your job is to
help build and modify the app. Files you edit will trigger Vite HMR
automatically. You can read .viagen/server.log to check recent Vite dev server
output (compile errors, HMR updates, warnings). When running in a sandbox with
git, the gh CLI is available and authenticated — you can create pull requests,
comment on issues, and manage releases.
Publishing workflow:
- If you are on a feature branch (not main/master): commit your changes, push
to the remote, and create a pull request using "gh pr create". Share the PR URL.
- If you are on main/master and Vercel credentials are set ($VERCEL_TOKEN):
commit, push, and run "vercel deploy" to publish a preview. Share the preview URL.
- Check your current branch with "git branch --show-current" before deciding
which workflow to use.
Be concise.
```
Recent build errors are automatically appended to give Claude context about what went wrong. To customize the prompt, you can replace it entirely or extend the default:
```ts
import { viagen, DEFAULT_SYSTEM_PROMPT } from 'viagen'
viagen({
// Replace entirely
systemPrompt: 'You are a React expert. Only use TypeScript.',
// Or extend the default
systemPrompt: DEFAULT_SYSTEM_PROMPT + '\nAlways use Tailwind for styling.',
})
```
## API
Every viagen endpoint is available as an API. Build your own UI, integrate with CI, or script Claude from the command line.
```
POST /via/chat — send a message, streamed SSE response
POST /via/chat/reset — clear conversation history
GET /via/health — check API key status
GET /via/error — latest build error (if any)
GET /via/ui — standalone chat interface
GET /via/iframe — split view (app + chat side by side)
GET /via/files — list editable files (when configured)
GET /via/file?path= — read file content
POST /via/file — write file content { path, content }
GET /via/git/status — list changed files (git status)
GET /via/git/diff — full diff, or single file with ?path=
GET /via/logs — dev server log entries, optional ?since=
```
When `VIAGEN_AUTH_TOKEN` is set (always on in sandboxes), pass the token as a `Bearer` header, a `/t/:token` path segment, or a `?token=` query param.
```bash
# With curl
curl -X POST http://localhost:5173/via/chat \
-H "Authorization: Bearer $VIAGEN_AUTH_TOKEN" \
-H "Content-Type: application/json" \
-d '{"message": "add a hello world route"}'
# Or pass the token in the URL path (sets a session cookie)
open "http://localhost:5173/via/ui/t/$VIAGEN_AUTH_TOKEN"
# ?token= query param also works (fallback for backwards compat)
open "http://localhost:5173/via/ui?token=$VIAGEN_AUTH_TOKEN"
```
## Development
```bash
npm install
npm run dev # Dev server (site)
npm run build # Build with tsup
npm run test # Run tests
npm run typecheck # Type check
```
## License
[MIT](LICENSE)