Kraft for VS Code reference
For installing it and clearing a gate, see Kraft for VS Code.
The status bar and the connection
The status bar shows a check mark beside Kraft while the extension is
connected and nothing waits on you, and Kraft (read-only) when the versions do
not match or the workspace is in Restricted Mode.
While connected, the status bar also shows how many items in scope wait on you,
such as Kraft 2, the same count as the Needs you group. When something waits,
it shows a bell in place of the check mark on VS Code's warning background. It
leaves the number out when nothing waits.
While connected, hovering Kraft shows what Kraft has spent today against its daily cap, such
as "Today: $1.20 of $20.00" or "Today: $0.500 (no daily cap)". It reads the
figure on connect and again at most every 30 seconds while the board changes,
and leaves the line out when the server does not answer.
Click Kraft in the status bar for Show Log, Open Web UI, Start
Kraft (only while it is disconnected) and Retry Now. Kraft: Show Log
in the Command Palette opens the same log: it records each connect, disconnect
and retry with its delay, every request Kraft refused, and every command that
failed.
While the extension cannot connect, hovering Kraft says why, and an empty
Kraft view shows one row:
| Row | Meaning | Clicking it |
|---|---|---|
| Kraft isn't running — Start | Nothing answers at kraft.url. | Starts Kraft in the background: kraft admin start --detach, from kraft.path. |
| Kraft refused the token — check kraft.url | Kraft answered but rejected the token: kraft.url points at another Kraft, or the token changed. | Opens the kraft.url setting. |
| Kraft error: … — Show log | Kraft answered with another error. | Opens the log. |
The extension retries on its own, waiting 1 second, then 2, 4 and so on up to 30 seconds between tries. Retry Now tries again at once.
Start Kraft runs from your home folder and shows "Starting Kraft…" until
Kraft answers, then connects. A Kraft that is already running is said so, and
the extension reconnects to it. When the binary is not found, Get Kraft
opens the install page and Open Settings opens kraft.path. Any other failure shows Kraft's own error, with the full
output in Show Log. Clicking again while one start runs says "Kraft is already starting."
Which items the board shows
Added in 2.1
The board, the count on its icon and the notifications cover the repos of the window's folders. A folder matches its repo the way Kraft matches it, so these all show the repo's items:
- A subfolder of the repo.
- A symlinked path to it.
- A linked worktree of it.
- A submodule or nested repo under a connected repo.
A window opened on an item's worktree shows that item's repo.
Archived items sit under Archived, the last group, collapsed. Expand it to list them, then right-click one, or select several, and run Restore to put them back under Done. The group reads its items from Kraft when you expand it, when the extension connects, and after an item is archived or restored. If that read fails, the group shows one row saying why.
Archived shows only while the board has other items. When it has none, restore from the Command Palette with Kraft: Restore, which lists the archived items to pick from, or from the web UI.
Show All Repos, in the view's title bar, widens the board, the count and the notifications to every repo Kraft has work in. Show This Repo, in the same place while all repos show, goes back to this window's repos. Both are also in the Command Palette.
The view's description says which it shows, "This repo" or "All repos", where VS Code shows a description (not in a sidebar that holds only the board). While Kraft is disconnected, the rows are the last it knew, and a line above them says "Not connected · last known".
The choice is kept per workspace: reopen the folder, or reload the window, and the board shows the repos it showed when you left it.
When this window's repos have no Kraft work, the view says "No Kraft work in this repo." with File Work Item… and Show all repos links. With all repos shown and no work in any, it says "No Kraft work yet, in any repo." with the File Work Item… link.
When a folder's repo isn't connected to Kraft at all, the view says "This repo isn't connected to Kraft." instead, after one sentence on what Kraft is and what a gate is, with a What is Kraft? link to the docs and a Connect this repo link (also Kraft: Connect This Repo in the Command Palette). It connects the repo with the commands Kraft detects, and the board then reads the connected repos again.
To set the test or setup command yourself, connect from the web UI or with
kraft repo connect. Connecting from VS Code needs Kraft on this machine: when
kraft.url points elsewhere, neither the link nor the command is offered, and
you connect the repo from the web UI or with kraft repo connect on Kraft's
machine. A read-only window doesn't offer them either.
To work in an item's worktree, right-click the item and run Open Worktree in New Window. It appears only while the item's worktree is on disk: not before the item has run, and not once its worktree is reclaimed.
Gate notifications and approval
Added in 2.1
When a gate opens, the notification names the item by its title and says what the gate asks, such as "Design the caching layer: approve spec". A notification for an item that failed or hit a cap or budget is a warning; a question or a gate is not.
When two or more arrive at once, as on startup or after a reconnect, one notification says "3 items need you" instead, with Next Gate when a gate is among them and Show Board to reach the rest.
Approving a gate whose document you have not opened opens it instead ("Read the spec on
A gate that is followed by a merge or a push asks first ("Approve and merge
| Setting | What it does |
|---|---|
kraft.url | Where Kraft listens. Empty reads KRAFT_HOST and KRAFT_PORT, then bind and port from access.yaml. Set in your user or Remote settings only: a workspace's settings cannot change it. |
kraft.path | The kraft binary Start Kraft runs. Empty runs kraft on your PATH; a leading ~ means your home folder. Set in your user or Remote settings only. |
kraft.notifications | all, gates or off: all notifies when an item needs you or fails, gates only when a gate opens. Pausing an item yourself never notifies. |
In Restricted Mode
Added in 2.1
In a workspace you have not trusted, the extension runs read-only. The board,
gate documents and Review Changes work. Every action, from Approve to
Submit Review and Start Kraft, shows "Kraft is read-only in Restricted
Mode: trust this workspace to act." The status bar item reads
Kraft (read-only), with the reason in its tooltip.
Config checks, schema completion, Show Resolved Chain and Lint Template Library start once you trust the workspace, with no reload.
If the extension is read-only
The extension works with a Kraft of its own major release and at least its
minor: the 2.0 extension needs Kraft 2.0 or a later 2.x. Against any other, it
turns read-only. The board still updates, every action is disabled, and its
status bar item reads Kraft (read-only).
| The extension | The server | The fix |
|---|---|---|
| 2.0 | 1.4 | Upgrade from 1.4. |
| 1.4 | 2.0 | Update the extension. |
An extension newer than Kraft
- When it connects, it shows a warning that says which to update, and the status bar item's tooltip repeats it: against a 1.4 server, "This extension (2.0.0) needs Kraft 2.0 or later; this server runs 1.4.0. Update Kraft. Actions are disabled until they match."
- When you then try an action, it shows "Kraft is read-only: this server's version does not work with this extension. Hover Kraft in the status bar to see which one to update."
VS Code updates the extension on its own, so after a new major release this is what you see until you update Kraft from 1.4.
An extension older than Kraft
The rule holds the other way too: an extension from 1.4, one whose updates are off or that you pinned, is read-only against a 2.0 server. The 1.4 extension has no tooltip and says less. When it connects, it shows "Kraft 2.0.0 does not match this extension (1.4.0); actions are disabled until they match." When you try an action, it shows "Kraft is read-only: the daemon's version does not match this extension." Update the extension as well.
Related
- Kraft for VS Code: install the extension, clear a gate, review a branch and edit config files.