FAQ

Short answers, with links to the long ones.

What is vincent, in one sentence?

A local-first control plane for AI coding-agent workloads: a background daemon runs agent CLIs against your git repositories under workflows you write, and every client is a thin consumer of its localhost API.

Does it need an API key or an account?

No. vincent stores no credentials. It runs the agent CLI you already installed and authenticated. There is no vincent account and no telemetry, and vincent reaches the network only on your behalf: whatever your agent CLI and your workflow’s own git commands do, plus reading a GitHub issue when you create a task from one — which uses your existing gh login, or a GITHUB_TOKEN/GH_TOKEN already in the daemon’s environment, stores neither, and is switched off by github.enabled: false.

Which agent CLIs work?

Claude Code (claude), Codex (codex) and Cursor (cursor-agent). Pick one per workflow, per step, or per task. See Agent CLIs.

Does it work on Windows?

Yes — fully, and CI proves it on every pull request alongside macOS and Linux. The one genuine gap is that cursor’s restricted mode requires macOS or Linux, where vincent fails the step rather than silently running it full-auto. See Windows.

Is my repository safe? What does “full-auto” actually mean?

An agent in full-auto can run arbitrary commands as you. The git worktree isolates tasks from each other, not from your machine. Nothing is pushed or merged unless a workflow step does it, everything is transcripted, and any step can be restricted. Read the Security model before pointing it at anything sensitive.

Does it touch my working copy?

No. Each task gets its own git worktree on its own branch — vincent/{id}-{slug} unless you configure a different convention. Your checkout, current branch and stash are untouched.

Does it delete my branches?

Only an empty one. Archiving a task removes its worktree and keeps the record. It keeps the branch too, unless that branch has no commits past the base it was cut from — a workflow that never wrote to the repository leaves nothing on its branch, and archiving deletes it rather than leaving an empty ref behind. A branch carrying any commit is never deleted. Turn the cleanup off with delete_empty_branch_on_archive: false.

The remote counterpart is left alone unless you also set delete_remote_branch_on_archive: true — off by default, and even then it runs only after the local delete succeeded, only for a branch with a configured upstream, and only when you archive the task yourself.

To find what to clean up, ask vincent rather than git — with configurable names a glob no longer finds them all:

vincent task ls --archived      # the branch column lists every branch vincent made

What happens if I close the TUI?

Nothing. The daemon owns all execution; clients are disposable. Close the TUI, close the terminal, log out — tasks keep running (on Linux, surviving logout needs loginctl enable-linger, which the service installer handles).

What happens if the daemon crashes mid-run?

Every transition is persisted before it is acted on. On restart, interrupted step runs are finalized, verified orphan processes are killed (the PID must still exist and still hold the same process, checked against a platform-native identity recorded at spawn — a PID the operating system has since handed to something else is left alone), and the step re-runs as an attempt that does not consume a retry. See Task lifecycle.

Do I have to write YAML?

Not to start: the built-in adhoc workflow is one agent step, and four examples ship ready to copy. You will want your own soon after — Writing workflows is short. If you would rather not write the first one by hand, run the built-in create-workflow against the repository that needs it: describe the workflow in the task, name it in the required workflow_name field, and leave global unset to install into that repo’s .vincent/workflows — or set it to true for {config_dir}/workflows.

How do I make a workflow only apply to one repository?

Put it in .vincent/workflows/ inside the repo. Project scope shadows a global file of the same name, and the file travels with the repository.

Do I need to restart anything after editing a workflow or the config?

No. The daemon watches both directories and reloads on save. An invalid file is reported and the last good version keeps running. The one exception is listen:, which takes effect at the next daemon restart.

My workflow file does not show up in vincent workflow ls

Add --project <id> — without it you see built-in and global scopes only.

Why did a step fail when the agent said it succeeded?

Because a check disagreed. An agent reporting success is a claim; a build is a fact. check_failed is the healthy, common failure: read the transcript, then press E to edit the prompt and retry. See Checks.

A task is stuck in queued

It is waiting for a scheduler slot. Check max_parallel_tasks (default 3) and the per-project cap, and raise the task’s priority to move it up the queue.

A task is stuck in awaiting_input

An agent asked you something. It is pinned to the top of the board with a badge — press enter on the row to answer. Note that awaiting_input holds a concurrency slot, because the agent process is alive mid-step. Set on_input: deny on workflows that must stay unattended.

vincent says my agent CLI is missing, but my shell finds it

Almost always PATH. A service-installed daemon captures PATH at install time on macOS and Linux, so a CLI installed afterwards is invisible to it — rerun vincent service install. Or skip PATH entirely with agents.<name>.path in config.yaml. If it is cursor: vincent resolves cursor-agent, never cursor.

Why does running a cursor step change my cursor model?

Cursor persists whatever --model it is given to ~/.cursor/cli-config.json, and vincent always passes one (defaulting to auto) so runs are reproducible. It is the one place vincent writes outside its own directories, and it is documented rather than discovered.

Can I use it in CI?

vincent workflow validate yes — it needs no daemon, no network and no agent CLI, which makes it ideal for a pre-commit hook or a CI job. Running tasks in CI is possible via the API but was not the design target: vincent is built for a developer machine.

Can I drive it from a script?

Yes. Every subcommand takes --json, exit codes distinguish “fix your request” (1) from “no daemon” (2), and the API is a documented localhost REST + SSE surface. See Scripting vincent.

Is there a web UI?

Not today. The TUI and the CLI are the shipped clients; both are thin consumers of the API, so a web UI is a client someone could write against the same endpoints.

Does it cost anything? Does it show me what a run cost?

vincent is MIT-licensed and free. Your agent CLI’s usage is billed by its vendor. Claude Code reports cost, so the board’s cost column sums every attempt for it; codex and cursor report none, and vincent shows nothing rather than guessing. That figure can also be a limit: max_task_cost_usd blocks a task once it has spent past a ceiling you set. It is off by default, and — for the same reason the column is empty — it cannot see a task that ran on codex or cursor.

How do I stop everything right now?

vincent daemon stop

Graceful: admission stops, running processes get 15 seconds, then they are killed and marked interrupted — the same resume path as a crash, so nothing is lost. --force if it will not go.

How do I remove it completely?

vincent service uninstall, vincent daemon stop, delete the binary, delete the config and data directories, then clean up vincent/* branches in any repository you used.

Where do I report a bug?

GitHub issues. Security issues go through private advisories instead. Include vincent version, your OS, and the relevant part of {data_dir}/logs/daemon.log.

Can I contribute?

Please. CONTRIBUTING.md has the setup, the commit convention, architecture pointers, documentation expectations, and the PR checklist. For substantial changes, open an issue first so the problem and user impact can be agreed before implementation begins.