Features

Vincent turns locally installed coding agents into managed, repeatable workloads. Your repositories, credentials, worktrees, transcripts, and task state stay on your machine; vincent provides the control plane around them.

At a glance

Orchestrate work instead of terminals

The daemon owns task state, agent processes, workflow execution, scheduling, and git worktrees. The TUI and CLI are clients, so closing either does not stop the work behind it. vincent service install can start the daemon with your login on launchd, systemd, or Windows Task Scheduler.

The scheduler admits work by priority and creation time while enforcing a global concurrency cap and an optional cap for each project. A task waiting at a human gate, blocked step, or fan-out join releases its slot instead of starving other work.

Each task runs in a dedicated git worktree on its own branch. Parallel tasks do not collide with one another, and vincent never changes your active checkout. The branch convention is configurable globally, per project, or for one task.

Talk to an agent without a workflow

Not every question is a task. A chat is a titled conversation with an agent, scoped to a project, that gets its own worktree and vincent/{id}-{slug} branch exactly as a task does — so you can ask about a repository, read the answer, and ask the next question with the first still in context.

Continuity is the agent CLI resuming its own session, not vincent replaying the conversation into the next prompt. That means only an adapter that can resume may hold a chat — all three of claude, codex and cursor can, each pinned to a captured fixture from a named CLI build. One that could not would be refused at creation rather than having continuity faked for it.

A chat is real work, not a scratchpad. The agent may commit to the chat’s branch, every turn records its tokens, cost and duration, and each turn keeps its own transcript — the accounting a conversation held in a terminal never leaves behind. Archiving a chat cleans up its worktree, and an empty branch with it, the way archiving a task does.

And when an exploration turns out to be the start of real work, hand the chat off to a task. The task adopts the chat’s worktree, branch, base branch and base SHA exactly as they are — no copy, no rename, no hidden commit, so committed and uncommitted changes are simply already there when the task’s first step runs. The chat ends, linked to the task; the task owns the worktree and branch from then on. ctrl+t in the chat workspace, vincent chat handoff, or POST /v1/chats/{id}/handoff.

Chats never appear on the task board and never enter the scheduler. A turn starts the moment you send it, bounded only by its own max_parallel_chats cap — over that it is refused immediately rather than queued behind batch work, which is the wait a chat exists to avoid.

Drive one from the TUI’s own chats board and chat workspace (guide), from vincent chat, or over the /v1/chats routes. A chat turn is bounded by the same agent_timeout and input_timeout a workflow step is, so a conversation nobody comes back to gives its slot up rather than holding it forever. No chat route is exposed as an MCP tool.

Express the workflow the work needs

Workflows are reusable YAML files that reload when saved and can travel with a repository under .vincent/workflows/. Strict validation catches unknown fields and invalid combinations before a task starts.

Three step types perform work or wait for a person:

• agent runs Claude Code, Codex, or Cursor with a rendered prompt.
• command runs a deterministic shell command in the task worktree.
• manual creates an explicit approval gate.

Six structural types compose those steps:

• parallel runs independent sub-steps concurrently in one worktree.
• fan_out creates child tasks with isolated branches and merges their results.
• condition ends a sequence early when a rendered condition is true.
• loop repeats a body by count or over a discovered list.
• break exits a loop cleanly.
• include reuses another workflow inside the current one.

Prompts, commands, checks, and instructions use Go templates. A step can read task and project data, declared task fields, loop context, and earlier step results. Workflows can declare ordered inputs with labels, descriptions, required flags, types, defaults, and validation patterns — including enum fields whose values are published as a list, so the TUI offers a picker rather than a text box. The TUI renders them before the task is submitted, while additional ad hoc fields remain available.

The workflow guide explains the patterns, and the workflow schema lists every field.

Verify outcomes and recover cleanly

An agent saying “done” is not the success condition. Agent and command steps can carry a check command, and the step advances only when both its body and its check succeed. A retry receives the actual failure, so the next attempt can correct the work rather than guess what happened.

Timeouts are enforced, retry counts are bounded, and exhausted steps become blocked instead of being silently skipped. From there a person can retry, edit the step for this task and retry, skip it, or cancel the task.

Spend can be bounded as well. max_task_cost_usd blocks a task with cost_limit once its cost across every attempt passes a ceiling you set. It is off by default, it counts one task at a time, and it only sees the agents that report cost at all.

When the problem is in the worktree rather than in the step, a blocked task can also be repaired: one throwaway agent, prompted by you and handed the blocked step’s failure context, runs in that task’s existing worktree and branch. It changes files and nothing else — the task returns to blocked at the same step with the same reason, so you read the diff and then decide. The repair is recorded as its own step run with its own transcript and cost, and does not consume the blocked step’s retries.

A finished task keeps its worktree, its branch and its commits until you archive it, and that window is where the last mile of real work lives — a branch that needs rebasing onto a main that moved, one more commit a review asked for, a stray file to drop. A follow-up run does that work inside vincent: give a done or aborted task an agent prompt, a shell command, or the name of a workflow, and it runs on that task’s own branch in that task’s own worktree, recorded in its own ledger with a transcript and cost accounting. It is repeatable, and it never changes the task’s verdict — a done task comes back done and an aborted one comes back aborted. It was the first human action to get a command line, because “rebase these six finished branches” is a batch; every other one — approve, reject, retry, repair, skip, pause, resume, answer, archive — is a subcommand now too, so a board full of blocked tasks can be cleared from a shell loop.

Every state transition is persisted before execution. If the daemon dies mid-step, restart recovery finalizes the interrupted attempt, verifies and stops orphan processes, and reruns the step without charging it as a failed retry. Every attempt also keeps a durable JSONL transcript.

When Claude Code reports a usage limit, vincent treats it as a temporary wait instead of a failure: the task returns to the queue without consuming a retry or slot, shows its next admission time, and starts again when the window reopens.

A step that fails on something transient can borrow the same wait. Give it retry_backoff: 30s and its retry is paced rather than immediate: the task returns to the queue, gives up its slot so other work carries on, shows when it will resume, and re-runs the step by itself. Unlike a usage limit the attempt still counts against max_retries — the wait decides when a retry happens, not whether there is one.

Keep people in the loop

Human oversight is part of the workflow instead of an informal terminal habit:

• Add manual steps before publishing, merging, deployment, or any other irreversible boundary.
• Review the task’s file-grouped git diff before approving it.
• Answer a supported agent’s structured question while its session remains alive, or require that capability when the workflow depends on it.
• Pause active work at a step boundary, change task priority, and recover a blocked step without discarding its branch or transcript.
• Send a one-off repair agent into a blocked task’s worktree when the fix is a file change, and still decide yourself whether the step then re-runs.
• Follow a finished task up with one more agent run, shell command or workflow in its existing worktree, as many times as it takes, before archiving it.
• Use bulk selection to act on several eligible tasks while refusals remain selected for follow-up.

• Let a long-running step say what it is doing: vincent status "<message>" from inside an agent or command step reports a line that shows live on the board and stays on the finished attempt as the step’s own account of how it went. It is opt-in per workflow — vincent never asks an agent for it.

• Be told when you are needed, with nothing open. Point notify.command at a script and the daemon runs it whenever a task enters a state you listed — blocked, awaiting_gate, awaiting_input, done — writing a JSON envelope with the task, the transition, the reason and the agent’s question to its standard input. It composes with whatever you already use: terminal-notifier, notify-send, msg, a Slack curl, a file drop. That is the point of walking away: the daemon is designed to run with no client attached, and this is how it says it needs you. See notify.

The daemon computes the actions valid in each state and sends that list to every client, so the TUI, CLI, and API agree on what can happen next. See the task lifecycle for the complete model.

Operate from a purpose-built TUI

Running vincent opens a Bubble Tea interface for active agent workloads:

• A filterable, grouped task board shows state, current step, elapsed time, reported cost, and — on a wide terminal — the step’s own status message. Groups fold away, and a folded one still carries its task count and its needs-attention badge.
• Task detail is a full-screen workspace with Steps & Attempts, Task Details, Output, Diff, and Workflow tabs, plus a Pull Request tab on a task that has one linked; each tab uses the whole view.
• A fan-out is something you can watch. L hangs a fan-out parent’s lanes under it as indented board rows in every state it passes through — without putting them in any count — one key opens the lane you are pointing at and another opens a lane’s parent, the Output pane cycles the lanes’ live output, the Diff tab groups lane › file so you can see which lane wrote what, and a failed join names the lane, its child task and that lane’s own block reason.
• The Output tab and the chat workspace share one renderer, and one verbosity level. Assistant prose is rendered as Markdown — headings, lists, blockquotes, inline and fenced code, rules, tables, links and images become terminal structure instead of literal syntax — while reasoning, tool calls, command output and errors stay literal behind their own gutter marks. A table is laid out to the pane and degrades to stacked column: value records rather than being clipped; a link’s destination is printed in a numbered reference list, never opened or turned into a terminal hyperlink; a fenced block shows its language and is tinted with styling only. Every marker is a glyph rather than a colour, so a monochrome terminal keeps every distinction, and the transcript on disk keeps the agent’s exact bytes. One key swaps the rendered view for the stored Markdown when a render surprises you, and another opens a picker that puts a message, its plain text, or a single fenced code block on the clipboard — built from the source, so the pane’s width is never baked into what you paste. Consecutive assistant records are read as one message, so structure that an agent split across records renders whole, and a pane you have scrolled away from keeps its place across a resize, a level change, the raw toggle and output dropping off the front of the window.
• Guided task creation exposes project, workflow, declared fields, git and priority settings, agent overrides, and a final review stage.
• Project and workflow workspaces keep navigation visible beside contextual details on wider terminals and fall back to compact layouts when needed.
• Workflows are authored where they are listed: structured forms create, edit and fork them without leaving the TUI. The forms are rendered from a schema the daemon serves, so a field the step you are editing cannot carry is one you are never offered, and saving preserves the comments and key order of the file you did not touch. $EDITOR is still one key away for anything the forms cannot load.
• A pull-requests screen lists what is open across every GitHub-based project at once, with the task claiming each one, and is where a link is made or removed by hand. It is offered only when at least one project qualifies.
• The workflow graph visualizes parallel groups, fan-out lanes and merges, the needs: edges between lanes and the waves they run in, conditions, loops, guards, checks, and nested includes — and, on a task’s own Workflow tab, what each step of that task did on it, live. enter opens any node in full: its prompt or run: body, and the values it inherits from the file’s defaults block.

The screenshots in the main README are real renders using representative workloads. Using the TUI documents every view and key.

Bring the agent you already use

Vincent invokes locally installed and authenticated CLIs; it stores no agent API keys or login credentials.

Agent, model, effort, and permission settings resolve from step to task override to workflow default to adapter default. The TUI shows which level won, and free text remains available when a newly released model is not in a catalog yet. Read Agent CLIs for installation and capability details.

Run steps in a container

Point container.image at an image you already have and a task’s step processes run inside one container, created with the task’s worktree and removed with it. What that confines is the filesystem outside the worktree and the project repository, the shell, and the tooling the image carries. Leave the key empty, which is the default, and nothing changes: every step runs on the host exactly as before.

Today that covers command steps and every check:, including a check on an agent step. The agent process itself still runs on the host — putting it in the container needs a launch seam across all three adapters, and that is the next piece of this work. A containerized task with agent steps is a mixed run until then, and vincent neither refuses it nor warns about it.

The image is yours and must already carry your agent CLI and git — vincent builds, publishes and bundles nothing. The repository and the worktree are mounted at their own absolute paths, so a path means the same thing inside and out and workflow templates need no translation. A workflow can pin its own image in defaults.container:.

macOS and Linux hosts only, and the container is a filesystem boundary rather than a network or credential one — outbound traffic is open by default and your agent’s configuration is mounted inside it so it can authenticate. Read the security model for what that means and container for the knobs.

Script and integrate it

The TUI, command-line subcommands, and external integrations all use the same localhost API.

• Every subcommand supports --json for machine-readable output.
• Stable exit codes distinguish a rejected request from an unavailable daemon.
• REST endpoints cover projects, workflows, tasks, actions, output, and diffs.
• Creating a task takes an optional idempotency key, so a create that loses its response can be re-sent without making a second task.
• Server-sent events provide durable state replay and live per-task output.
• vincent workflow validate works without a daemon or installed agent CLI, so it fits pre-commit hooks and CI. vincent workflow render belongs there too: it executes a workflow’s templates against a preview context, so a reference no task would satisfy is caught before a task is created.

Start with Scripting vincent, then use the complete HTTP API reference when you need direct integration.

Let an AI agent drive it

The daemon serves the Model Context Protocol on the same loopback listener, behind the same bearer token, so any MCP client gets the whole API as tools — with discovery, argument schemas and typed errors rather than hand-rolled curl.

• The tool surface is the route table, minus six destructive-admin routes an agent has no business calling: stopping, backing up, garbage-collecting, repairing or reconfiguring the daemon, and force-deleting a project. The configuration one is also the only tool whose body differs from its route’s: config_get masks environment.set’s values and notify.command’s argv, because a tool result lands in the model’s context and in the transcript.
• One bounded task_wait call blocks until a task is done, aborted, archived, or waiting on a human — with a hard ceiling, so a call cannot hang. Step transitions stream as progress notifications, and the result is complete without them.
• Your own agent steps get the same tools by default. A step can file follow-up work, read a sibling lane’s transcript, or answer a gate, with nothing to configure. mcp.wire_steps: false turns it off.
• A chain of tasks created this way is bounded by mcp.max_depth and mcp.max_tasks, because a step’s agent can create a task whose step runs an agent that creates a task.

See Driving vincent from an agent.

Start from a GitHub issue

On a project whose origin remote points at github.com, the new-task form offers an issue row above the title. It opens the same type-to-filter picker the project and workflow rows use, listing open issues newest first. Selecting one fills in the title — prefixed #N, so the board row says which issue it is — the body plus a GitHub issue #N: <url> link line, and any declared fields: named exactly issue, labels, assignee, or milestone. Every value lands in an ordinary editable row, so a guess can be corrected or cleared before the task exists.

A declared issue field gets the issue number, which is how a command step reads it: step bodies receive the environment of §8.5, not the template context, so {{ index .Task.Fields "issue" }} is what puts the number into a run: body.

Templates receive the issue as .Issue — number, title, body, URL, state, labels, author, assignee, and milestone — zero-valued when nothing is linked, so {{ if .Issue.Number }} lets one workflow serve both. The issue is fetched once at creation and stored on the task, so runs stay reproducible and no step render touches the network. Fan-out lanes inherit their parent’s issue.

vincent task add --github-issue 200 takes the same path as the form, with explicit flags winning, and vincent github issues lists issues without the TUI.

Vincent stores no credential: it prefers your existing gh CLI and falls back to GITHUB_TOKEN/GH_TOKEN from the daemon’s environment. Nothing about an issue is ever written back — the only thing vincent writes to GitHub is a pull request you ask it to open, below. When it is unavailable the row does not appear, vincent doctor reports why, and everything else is unaffected. Set github.enabled: false in config.yaml to switch it off entirely.

See the new-task form, the configuration reference, and the workflow schema for .Issue.

Link a task to its pull request

Once a workflow has pushed a task’s branch and a pull request has been opened from it, vincent finds it. Every github.poll_interval — 5 minutes by default — the daemon lists each GitHub-based project’s open pull requests and links the ones whose head branch is a task’s own branch. It never overwrites a link you made by hand, and a link you removed is never re-applied.

The TUI’s pull-requests screen shows every GitHub-based project’s listing at once and carries the two linking actions — link a pull request the head-branch rule missed, unlink one it got wrong — and a task’s own workspace shows its pull request beside its branch, on a Pull Request tab that adds one row per CI check on its head commit and carries a second copy of unlink. vincent github prs --project ID prints one project’s open pull requests with the task each one belongs to. Only the link is stored: a pull request’s title, state, draft and merged status — and every check on it — are re-read every time they are shown, which is what lets a task still name a pull request that has since merged and dropped off the open listing.

Open a pull request

A task with a branch and no pull request can get one without leaving vincent. Press P in the task workspace — or P on the pull-requests screen, which offers a picker of every task that has a branch and no pull request — and a form opens with the title, the body and a draft / ready toggle, all editable first. The body is prefilled from the task’s description, plus Closes #N when the task came from an issue. ctrl+s pushes the branch to origin and opens the pull request; the link appears immediately. vincent github pr create --task ID --title TITLE [--draft] does the same thing without the TUI.

This is the only thing vincent writes to GitHub. It never updates, comments on, closes or merges anything, it happens only when you ask for it, and github.enabled turns it off along with every read. Agents cannot reach it: it is deliberately not an MCP tool, and an agent that wants a pull request runs git push and gh pr create in its own worktree, as it always could.

Two things it will not do. It never force-pushes — a diverged, protected or rejected push creates no pull request and changes nothing on the remote, because your branch may hold commits nobody has pushed and throwing them away quietly is not vincent’s call. And it pushes committed work only: anything uncommitted in the task’s worktree is not in the pull request, which the form says before you confirm.

If there is no credential with write scope, or GitHub refuses the create, the branch is still pushed and vincent falls back to opening GitHub’s own “open a pull request” page in your browser — the same hand-off it always did, except that the branch behind it now exists.

Run a pull request

The other direction: turn a pull request into a task. Press c on the pull-requests screen, or run vincent task add --project ID --github-pull N. The new-task form opens prefilled with the pull request’s title and body, editable like any other draft, and the task that comes out runs on that pull request’s head branch — its worktree is that branch checked out with an upstream, so when a workflow pushes, the work lands on the pull request. Addressing review, fixing CI and extending somebody’s branch stop being out-of-band git.

s cycles the listing between open, closed and all, so a merged pull request you want to redo is reachable. A workflow field declared pull receives the number, which is how a run: step acts on the pull request. A fork works too: its head is fetched and checked out, and vincent says up front that nothing can be pushed back to it.

Two branch rules follow from the task not owning its branch. If you already have that branch locally, vincent fast-forwards it, and refuses rather than discarding anything when it has diverged or is checked out somewhere else. And archiving such a task never deletes the branch — local or remote — because vincent did not cut it.

This is one of two things vincent does on the network without being asked — the other is the release check under Run it on your platform — and it has its own switch: github.poll_interval: 0 stops the background listing and leaves everything else working on demand. It fires only for projects whose origin is a github.com repository, so a daemon with no such project never makes it. It writes nothing to GitHub either: the reconciler only reads, and the one write vincent makes there happens when you ask for it, never on a tick.

See the pull-requests screen, the CLI reference and the API reference.

Diagnose and maintain it

vincent doctor produces one report covering paths, configuration, daemon health, the recent log tail, the database’s footprint, row counts and integrity, agent availability, login state and whether the installed CLI build is one vincent has been tested against, the GitHub integration, whether a newer vincent has been released and whether the running daemon is older than the binary you just ran, disk use, worktrees, and task counts. It supports JSON output for bug reports and automation, while --fix can reclaim orphans and compact the database when it is safe to do so.

vincent daemon logs and vincent task transcript put the two artifacts a failure is diagnosed from on the command line, so neither needs the TUI. The log command reads {data_dir}/logs/daemon.log from disk and never contacts the daemon, so it still answers when the daemon is the thing that is broken; -f follows it. The transcript command prints one attempt’s complete record — the file vincent task show only names — rendered as text for a person, as NDJSON for jq, or as the agent’s own dialect byte for byte, with -f following an attempt while it is still running.

config.yaml is editable without leaving vincent. vincent config get prints every key in effect and vincent config set changes one; the TUI’s daemon view edits the same keys in a typed form. Both go through the daemon, which owns the file: it validates the whole candidate before writing anything, edits your key in place so comments and key order survive, and applies the result before it answers — so a change is in force with nothing to restart, listen excepted. An invalid value leaves the file untouched.

vincent gc focuses on orphaned worktrees and transcripts. It supports a dry run, refuses to remove dirty or unknown work without an explicit force, and never deletes a branch or anything outside vincent’s data roots. The daemon also reports orphaned paths at startup.

vincent daemon backup writes one .tar.gz holding a consistent copy of the database, every transcript, your config.yaml and your global workflows. The daemon takes the copy with SQLite’s own VACUUM INTO, so it can be taken while tasks are running — unlike copying vincent.db by hand, which under WAL is missing whatever has not been checkpointed. vincent daemon restore is the reverse, runs against a stopped daemon, and deletes nothing: a destination that already holds state needs --force, which moves the old state aside as <name>.bak-<timestamp>.

See Troubleshooting for the diagnostic workflow, Files for what an archive holds and what it leaves out, and the CLI reference for exact flags and exit codes.

Run it on your platform

Vincent is one self-contained Go binary with no runtime, CGO dependency, or external database. Releases cover Windows, macOS, and Linux, and are published as archives plus platform-friendly packages:

• Homebrew or a universal installer package on macOS
• WinGet or Scoop on Windows
• deb and rpm packages on Linux
• mise or release archives on all platforms

The daemon asks GitHub once a day whether a newer stable release exists and vincent doctor shows the answer; vincent update --check asks on demand, and vincent update applies one — verifying the download, and never touching a binary a package manager owns. The check is an opt-out (update.check: false); applying is always something you run.

Release archives are checksummed, the checksum manifest is signed with cosign, and builds carry GitHub attestations. There is no OS code signing on either macOS or Windows — both are recurring certificate purchases this project has not made — so a downloaded release meets Gatekeeper or SmartScreen once, and Installation documents the one command that clears it. Platform-specific installation, service, shell, and restricted-mode differences are documented in Installation and the platform guides.

Common ways to use vincent

• Verified feature delivery: implement with an agent, build and test with a command, stop for review, then publish only after approval.
• Converging repair loops: run a probe, let an agent repair the result, and repeat until the check is green or the iteration bound is reached.
• Parallel implementation: fan out independent changes into child tasks and merge the finished branches back in a declared order.
• Cross-agent review: implement with one adapter and review with another.
• Repository-specific intake: declare ticket numbers, environment choices, flags, and other validated task fields directly in the workflow.
• Repeatable maintenance: replace prompt-heavy steps with commands where the operation is deterministic, reserving agent calls for reasoning and edits.

Ready to try it? Follow the Quickstart, write your first workflow with vincent workflow init (--from starts it from one of the example workflows) or from the TUI’s workflows screen, or install the workflow-authoring skill.