# Vicunia: Your users ask. Your agent builds. You approve.

Vicunia is a trust and orchestration layer between the places where change requests appear (user feedback webhooks, error alerts, a web inbox and Telegram messages, with WhatsApp coming later) and the coding agent a developer already uses (Claude Code by default, or any CLI agent). It writes a structured spec, applies per-project rules, asks for approval in chat when needed, then a local runner on the developer's machine implements the change in a git worktree, runs tests, re-checks the rules on the real diff, pushes and opens a GitHub pull request. Vicunia merges when CI is green and the rules allow it, detects the deployment, checks the live URL and notifies the developer and the original requester. Vicunia never writes, hosts or deploys code itself.

## Your users ask. Your agent builds. You approve.
Vicunia turns feedback, error alerts and messages from your phone into tested, merged and deployed changes. It runs the coding agent you already use on your own machine. You approve with one tap in Telegram.

## The problem
### A one-line fix still costs an evening
Branch, prompt the agent, wait, run the tests, open the PR, merge, watch the deploy, reply to the user. The change takes minutes. The ceremony takes the night.

### Agents are fast. Babysitting them isn't.
Your coding agent can fix the date format in five minutes. It still needs someone to hand it the task, check the diff and press merge.

### Small requests pile up across products
Three side projects, one inbox each. The little things your users ask for sit in a backlog until they stop asking.

## How it works
1. A request comes in. From your app's feedback widget or error alerts through a webhook, from the web inbox, or as a plain text to the Vicunia bot on Telegram.
2. Vicunia writes the spec. Title, type, risk, acceptance criteria and likely files. Duplicate requests become votes on the same spec instead of new work.
3. You approve, or your rules do. Approve, edit or reject with one tap in chat. Low-risk requests from trusted sources can go straight through. Public ones always wait for you.
4. Your agent ships it. The runner on your machine creates a git worktree, runs your agent and your tests, checks the real diff, pushes and opens a PR. Vicunia merges when CI is green, checks the deploy is live and tells you and the person who asked.

## The runner CLI
```
vicunia login --token <token>
vicunia link habits --path ~/code/habits
vicunia agent set habits "claude -p {prompt_file}"
vicunia start
```

## Example: one request, end to end
- 20:40 A user writes in the feedback widget. “Export uses US date format, I'm in France.”
- 20:40 Vicunia writes the spec. Bug: CSV export ignores user locale. Low risk, two acceptance criteria.
- 20:41 Sara taps Approve on Telegram. The request came from a public source, so her rules ask her first. She's at dinner.
- 20:42 The runner on her laptop picks it up. New git worktree, Claude Code starts. Tests fail once; the agent reads the output and fixes it.
- 20:50 23 lines, no protected files. The rules pass on the real diff. Vicunia pushes and opens the pull request.
- 20:52 CI green, auto-merged. A small bug fix inside her auto-merge limits, so no second tap needed.
- 20:54 Deployed and checked live. Vercel reports the deployment, Vicunia checks the site answers, and the user gets an email: “Fixed, thanks for reporting it!”

## Safety
### Rules run twice
Once on the spec before anything runs, and again on the actual diff before anything is pushed.

### Protected paths block the push
.env files, migrations, auth, payments, CI workflows and lockfiles. If the agent touches one, the change stops on your machine.

### Public requests never auto-merge
Anything your users send waits for your approval and is never merged without you. That's in the code, not a setting.

### Only small changes merge on their own
By default: trusted source, bug, copy or chore, at most 300 lines and 10 files, green CI. Everything else asks you first.

### Every decision explains itself
Each card says auto, needs approval or blocked, and why. No silent automation.

### Requests are data, not instructions
User text goes to the agent as a delimited file, never into a shell command, so a crafted request can't run anything.

## By hand vs. with Vicunia
- Read the request, decide if it's worth doing: by hand, you; with Vicunia, vicunia writes the spec, you tap.
- Branch, prompt the agent, wait: by hand, you; with Vicunia, runner, on your machine.
- Run tests, feed failures back: by hand, you; with Vicunia, runner.
- Check the diff for risky files: by hand, you; with Vicunia, rules, before push.
- Open PR, wait for CI, merge: by hand, you; with Vicunia, vicunia, within your limits.
- Watch the deploy, tell the user: by hand, you; with Vicunia, vicunia.

## Channels
### Telegram
Send requests as normal messages. Approve, edit or reject with buttons on cards that update in place, plus /inbox, /status and /mute 8h.

### Email
One-click signed links that expire, and the fallback whenever chat can't be reached.

### Web
The live inbox and job timelines, with tests, diff size, PR and deploy links.

### WhatsApp
The same cards and buttons on WhatsApp. Coming later.

## Plans
### Free: For one side project
- Free, no card needed
- 1 project, 30 requests a month
- Spec, rules and approvals from Telegram, email and the web
- Your agent on your machine, tests and the diff check
- Merge each PR with one tap

### Pro: For several products with real users
- $39 a month
- 10 projects, 500 requests a month
- Everything in Free
- Auto-merge for small changes from trusted sources, with green CI
- Monthly subscription, cancel any time from the billing portal

## FAQ
### Which coding agents does Vicunia work with?
Claude Code is the default. Any agent that runs from the command line, such as Codex or Aider, works through a command template like claude -p {prompt_file}. Vicunia hands the agent the spec as a file and runs your tests afterwards.

### Does my source code leave my machine?
No. The Vicunia runner works in a git worktree on your machine with your own agent and git credentials. The only way code leaves is your own git push to GitHub. Vicunia's servers receive the job status, diff stats and short log excerpts, never your source code.

### What stops the agent from breaking production?
Your tests, your CI and Vicunia's rules. Rules are checked on the spec and again on the real diff before any push. Changes to protected paths such as .env files, migrations, auth, payments, CI workflows and lockfiles are blocked. Only small, low-risk changes from trusted sources merge automatically, and only with green CI.

### Can the users of my app trigger code changes?
They can send requests, not changes. Requests from public sources like a feedback widget always need your approval and never merge automatically. Their text is treated as data and is never executed.

### Where does my app need to be hosted?
Your code lives on GitHub; Vicunia connects through a GitHub App to open pull requests, read CI results and merge. Deploys are detected through GitHub deployment statuses, which Vercel reports, and Vicunia then checks that your URL responds before it calls a change shipped.

### Does my laptop have to be on?
The runner executes jobs whenever it is online. If it's offline, approved jobs wait in the queue. You can also run it on an always-on machine or a small server.

### Why chat apps?
Most small requests can be decided in five seconds, and your phone is where you are. You can send requests and approve specs from Telegram today. Email covers the rest and is the fallback when chat can't be reached.

### Does Vicunia work with WhatsApp?
Not yet. WhatsApp support, with the same cards and buttons as Telegram, is planned for later. Until then, use Telegram, email or the web inbox.

### Does it work with GitLab or Bitbucket?
Not yet. Vicunia starts with GitHub.

### How much does Vicunia cost?
There's a free plan with 1 project and 30 requests a month, no card needed. Pro raises that to 10 projects and 500 requests a month, and lets small changes from trusted sources merge on their own. Pro is $39 a month, and you can cancel any time.

Website: https://vicunia.si
Contact: hello@vicunia.si