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.

Almost every call vincent makes is on your behalf: whatever your agent CLI and your workflow’s own git commands do, plus reading GitHub — an issue or a pull request when you create a task from one, and a project’s pull requests when you ask for them — and, when you press the key for it, pushing a task’s branch and opening its pull request. Both use your existing gh login, or a GITHUB_TOKEN/GH_TOKEN already in the daemon’s environment; vincent stores neither. Opening a pull request — and merging, closing, reopening, commenting on or re-running the failed checks of a task’s linked one — are the only things it writes to GitHub, and each happens only when you ask.

Two calls the daemon makes without being asked, both switchable:

• The release check. Once a day the daemon asks GitHub for vincent’s latest stable release, so vincent doctor can tell you a newer one exists. It is one unauthenticated GET and it sends nothing identifying — no token, no telemetry, no machine or install identifier. It downloads and installs nothing; that is vincent update, which you run. Set update.check: false and the daemon makes no such request at all.
• The GitHub reconciler. Every github.poll_interval (5 minutes by default) the daemon imports and refreshes each GitHub-based project’s issues into its issue set, and lists its open pull requests so a task can name the pull request opened from its branch. It fires only for projects whose origin is a github.com repository, so a daemon with no such project never makes it. Set poll_interval: 0 to stop it and keep the rest, or github.enabled: false to switch off every GitHub call vincent makes.

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; elsewhere vincent refuses the task at creation rather than silently running the step 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?

Not unless you ask it to. Each task gets its own git worktree on its own branch — vincent/{id}-{slug} unless you configure a different convention.

The exception is one you opt into per task: --existing-branch on a branch you have checked out runs the task in that checkout instead of making you move off it, and no worktree is created. The agent is then working in your working copy, uncommitted changes and all.

The one change vincent makes there is a fast-forward. Before a task’s worktree is created, its base branch is fetched from its remote, and a local base branch that is simply behind is moved to the fetched commit — with its working tree, when it is checked out and clean. A checkout with any change in it or an operation in progress, a branch with commits the remote lacks, and your stash are left alone. fetch_base_branch: false turns it off.

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 eight 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.

Later, when vincent has grown features your files predate, the built-in update-workflows rewrites the workflows a project versions against the current schema and hands you the result as a reviewable diff. It changes how they are written, not what they do. Set its global field to true to do the same for {config_dir}/workflows: the rewrite is then staged as a proposal that you approve before anything is installed.

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.

My issue’s task is queued, but slots are free

A task created from an issue runs in the issue’s main worktree, one task at a time, so it waits while another main task of the issue holds that worktree — or while a finished one still has a chat open in it. vincent task add names the holder when it creates the task (queued behind #61), the TUI’s issues board and issue detail name it (● #61 running), and vincent issue show <id> --json carries it as main_worktree.occupant_task_id. Wait for that task, or create the work as a side task to run it now — --separate-worktree, or separate in the TUI’s new-task form. See Working an issue.

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. When the task is in another project than the one selected, it is counted in the header’s (! N elsewhere) badge instead, and ! crosses to it. 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, and max_tree_cost_usd does the same for a fan-out task and all of its lanes together. Both are off by default, and — for the same reason the column is empty — neither can 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. The Contributing guide 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.