Corgi runs your project locally
with one command. Describe the stack once in corgi-compose.yml. corgi run
clones the repos, seeds the databases, writes the .env files and starts
every service. Run all of it, only the databases (corgi db -u), or only the
frontend against staging (corgi run --tier staging --services web).
In the editor this extension:
- highlights and autocompletes
corgi-compose.yml
- runs corgi and its helpers (run, doctor, status, db, tunnel) from the
activity bar, status bar and editor
- browses and runs the showcase examples
- answers as
@corgi in Copilot Chat
- shows every Claude Code session on the machine (below)
🤖 AI assistant
@corgi in Copilot Chat knows the corgi-compose.yml schema and the CLI:
@corgi /new a go api with a postgres db: scaffold a corgi-compose.yml@corgi /explain: explain the current compose file@corgi /debug: run corgi doctor and corgi status, diagnose@corgi how do I add a redis cache?: questions, answered from the docs
Each reply offers one-click corgi doctor / corgi run buttons.
Copilot agent-mode tools: Copilot can call corgi directly:
corgi-status, corgi-doctor, corgi-validate, corgi-list (read-only) and
corgi-run (asks before starting your stack). So "get my stack running and fix
issues" just works. Reference them explicitly with #corgiStatus, #corgiDoctor,
etc.
Install corgi
The extension shells out to the corgi CLI. Install it once, either way:
- in VS Code: Shift+Cmd+P,
Corgi install with Homebrew
- in a terminal:
brew install andriiklymiuk/homebrew-tools/corgi
corgi update # later versions
Try it on an Expo + Hono example:
corgi run -t https://github.com/Andriiklymiuk/corgi_examples/blob/main/honoExpoTodo/hono-bun-expo.corgi-compose.yml
Claude Code sessions
The corgi daemon keeps a board of every Claude Code session on the machine
(corgi agent mode).
This extension shows that board in VS Code.
The Corgi side bar is one page: Usage (the 5-hour and 7-day
limits of every account, as bars), Inbox (the tickets, review requests,
comments and red builds the watch found and nobody dealt with), and
Sessions (every Claude Code session, with a dot for its state, what it
does, its diff and tests, context fill, time since the last change). Click
a session to focus its terminal tab or Claude Code panel. Hover a row for
its buttons: Allow and Deny when it asks, Fresh when it drifts,
Chat, and ⋯ for the rest. The title bar has Run, Stop, Reload and ⋯
with every corgi command in one quick pick.
Status bar: ⌁ 3 · 🔔 1 · 5h 62%. Sessions working, sessions that wait
for you, the tightest 5-hour usage limit across accounts. The text turns
yellow when a session waits. Hover for the list. Click to pick one.
Toast with a Go button when a session in another window starts
waiting. Only the front window shows it (corgi.agentToasts).
Auto-continue when limits reset. A session that stops on a usage limit
sits dead until someone notices. Turn on corgi.autoContinue.enabled and
corgi sends one message to each limited session the moment its window
resets - no second extension, no daemon of its own.
It is off by default, and it never resumes anything quietly: while
something is queued, the status bar shows what and how long
(api in 47m, or 2 queued, next in 12m). Click it to see the list and
cancel a session that should stay stopped, cancel all of them, or turn the
whole thing off. A cancelled session is only cancelled for this wait: its
next limit queues again.
corgi.autoContinue.message is what gets typed (default continue).
corgi.autoContinue.graceSeconds waits past the reset (default 60) because
the limit lifts on Anthropic's clock, not this machine's.
Watch what runs for you. corgi agent watch --auto fixes tickets and
review comments headless, in the background - a run takes minutes and only
speaks when it is over, so the editor gave no sign anything was happening.
Now the status bar spins with what it is on (HUM-1338 7m), a progress
notification follows each run, and when one opens a pull request it offers
to open it. Afterwards the bar reports what came out
(1 from the watch). Click it for the list: pick a row to open its PR.
corgi.watchFixes.statusBar and corgi.watchFixes.progress turn each half
off.
A row says what is wrong, and offers the way out. A session the daemon
thinks is drifting - context nearly full, the same tool failing on repeat, a
diff far past its budget - turns red with the reason, and the right-click
menu offers Fresh from a handoff: a clean session, same account, picking
up from the handoff it leaves. A limited one says when the daemon continues
it. Every working row also carries what its branch has built up (4 files ·
120 lines) and its last test run (tests ✓ / tests ✗ go test); when
another session in the same repository is on the same files the row turns
amber with a merge icon and names it - ⚠ api·2 on registry.go - so work
crossing streams is seen here, not at merge time. What it has cost sits
there too (52.3M, cache reads included), and turns into 52.3M over
budget with a red icon once it passes the budget corgi agent cap 50M
gave it (corgi 2.20.9+). Bots (corgi 2.20.13, corgi agent bot add …): the view's robot icon
opens one - its workspace, its persona, its last conversation resumed - and a
bot's row carries the bot's name. The sparkle asks the chief:
what should I look at first? → corgi agent ask, a few lines back.
A working row has Interrupt - Escape into
the session, as you would press it: the turn stops, the session waits,
nothing is closed (corgi agent interrupt, corgi 2.20.10+). The menu also has Send…,
Allow always, Open pull request and Copy session id. Chat (the speech
bubble on a row, or Corgi Agent: Chat with a session beside the code)
opens the conversation in a panel next to the editor - what it said, the
tools it ran, a box for the next message, Allow / Deny / Stop - through
corgi agent transcript and corgi agent send (corgi 2.22+). Select lines
in any file and the editor's context menu has Send selection to a
session: the file and line, the code quoted, your words after it. And when
the file in front of you is one another live session's branch touched, the
status bar and the first line say so - api·auth is editing this file -
click to bring it forward. A row also says not done · go test when the
workspace's done-when check went red after the session stopped, main moved
12 · conflicts in total.ts, try 2 on WEB-88 for a fan-out, and the
agent's name for a session that is not Claude Code. In the inbox, an issue has Work on it (also inline): a real
session on the ticket, in its own checkout, with the prompt an unattended run
would have had - corgi agent watch work ABC-123 - and Work on it in a
worktree of its own: the same session on corgi/ABC-123 under
corgi_services/.worktrees, so it never shares a checkout with another
(--isolate, corgi 2.20.8+; corgi.agentIsolate makes every session from
here start that way, and the sessions view's New … in a worktree of its
own does it for a blank session). A blocked ticket is red
with the reason and Unblock; every item has Ignore (also inline), Assign
to me and Move…. A row about a pull request of yours - corgi's run's, a
session's, or your own - has ready for review, merge and close
(corgi agent watch pr ready ABC-123), and its line says how it stands:
ready to merge · checks ✓ · approved, or checks ✗ · changes requested
(corgi 2.20.19 reads that from GitHub or GitLab once a round).
An idea page beside the code
Preview with comments (the comments icon in the title bar of any .md,
or right-click it in the Explorer) opens the file as a page beside the
code: pictures and videos play inline, comments sit on the words, and the
same comments show as threads in the file itself - yours, the team's, the
agent's. Corgi: Copy the link for the team puts its link on the
clipboard; people comment without an account, the agent answers and fixes
the page, and the fix lands back in your file. Needs corgi 2.34.
corgi idea new "a scheduling app for a coffee shop" has the agent write one
page - the thing you want built, as markdown - and from then on the page is
where it gets argued over: people highlight words and comment, the agent
answers in the thread and amends the page, and when it reads right, Build
it hands it over. The extension puts that page in VS Code.
Corgi: New idea page… asks for the sentence, then what kind of page it
is - idea (something to build from nothing), spec (a feature in an
existing product), HLD (a high-level design) or RFC (a proposal to
decide) - waits while the agent writes (a progress notification; it takes a
minute or a few), and opens the page beside the code. A markdown file you
already have becomes a page with Corgi: Keep this markdown as an idea
page (the editor's title bar on any .md; corgi idea new --from).
Corgi: Open idea page picks one from the list (name, type, summary,
3 open · 1 waiting on the agent, the epic it was sent as). The Ideas
section of the side bar lists them too, with the type as a pill and the same
counts, a + new link, an Edit button for the markdown and ⋯ for
the rest.
The panel shows the page as corgi renders it on the left, the comments on
the right (below it when the panel is narrow); a thin bar along the top says
how far down the page you are, and On this page, above the comments,
lists the sections with how many open comments each has - click one to jump,
the one in view is marked as you scroll. Select words on the page and a
Comment button floats over the selection: your words go in with the
quote, so the comment sits on those words - highlighted on the page, tinted
by its status - and a click on a card's quote scrolls there. Hover a section
heading for + comment, a comment on the whole section. Comment on the
whole page is at the bottom, next to Build it, under Hand it to the
agent.
Above that, Tickets (N), folded: the agent's split of the page into
tickets - number, title, the tracker ref as a link once it has one, its
state, after 1, 2 for what it waits on; click a row for the body. Under
it, chips for where the page went: 🎯 SHOP-12 · BrewShift, 📄 page 99.
When corgi has credentials for Jira, Linear or Confluence, Send to jira
/ linear / confluence sits next to Build it: it asks for the project
or team key (the space key for Confluence) when corgi does not know it,
confirms an epic and N tickets will be created in KEY, runs corgi idea send and offers to open what it made.
A comment can carry a link and files: Attach… in the composer opens the
file dialog, the picked names show as chips (× drops one) and go along as
corgi idea comment --file. The words you highlighted travel with their
context (prefix, suffix, heading), so corgi puts the comment on the right
copy when the same words are on the page twice.
Each card says who, when, proposal when the agent proposed something,
and the status: open, answered (the agent replied without touching the
page), changed the page, resolved. Every card ends in a one-line reply
box - type, Enter sends (Shift+Enter for a new line), the agent reads it. A
proposal nobody answered has Accept (a reply, after which the agent
acts) and Dismiss; everything else has Resolve or Reopen. The
filter is All / Open / Proposals / Resolved. The agent answers on its own
while the corgi dashboard runs (corgi agent up): the panel re-reads the
moment the files change, and agent is answering… shows while it works -
nothing here waits on it.
Edit markdown (also Corgi: Edit idea page markdown) opens idea.md
in a normal editor, and the comments show there as VS Code comment threads
on the lines their words are on (page-level ones on the first line), the
status in the thread's label, the replies under it. Reply in the thread's
box, Resolve or Reopen from its title, or press the gutter's + on a line
and write: that is a comment on those lines (the file is saved first, and
heading marks and bullets are left out of the quote). With text selected
the editor's context menu has Corgi: Comment on this for the idea page.
Threads update in place as the agent answers - a fold, or a reply you are
typing, stays.
Build it runs corgi idea build under a progress notification and says
what came of it - the plan and its tasks, or why it could not start.
Open in browser opens the same page in the corgi dashboard; it is the
same page on the phone, so a comment left from the train is on the page
here when you sit down.
Comments carry your login name; corgi.idea.author sets another. Commands:
Corgi: New idea page…, Keep this markdown as an idea page, Open idea page,
Edit idea page markdown, Build it (hand an idea page to the agent), Comment
on this for the idea page.
Reload (↻ on either view) is a real reload: the daemon rescans sessions
and polls every tracker now, and the phone, the menu bar and this editor
re-read the same fresh picture.
Hidden workspaces, for showing the editor to someone: right-click a
workspace heading → Hide this workspace. Its sessions, inbox items and runs
leave the views, the status bar and the toasts. Corgi: Hidden workspaces…
brings them back; the list is corgi.agent.hiddenWorkspaces. Nothing on the
machine changes.
Commands (Shift+Cmd+P): Corgi Agent: Sessions (pick one to focus), New
Claude Code session in this window, Go to the session that needs you, Send
text to the front session, Talk to the front session, Auto-continue queue, What the watch worked on, Reload everything, Hidden workspaces….
How it works: the extension sets CORGI_VSCODE_WINDOW in every terminal, so
a claude started there knows its window. It tells the daemon which
terminal tabs and Claude Code panels the window has. When corgi agent focus, corgi-bar or a Stream Deck key asks, it reveals that tab. corgi agent new opens a claude terminal (corgi.claudeCommand). corgi agent send types text into the session's terminal as keystrokes, never as a
shell command.
It offers once to set terminal.integrated.tabs.title to ${sequence}, so
a tab reads ▲ acme-api NEEDS YOU instead of "claude". Nothing runs until
corgi agent has been used on the machine. corgi.sessionTracking: false
turns it off. If the Claude Code panel does not come forward, set
corgi.claudePanelCommand to the command that focuses it.
The same board is in the menu bar with
corgi-bar and on Stream Deck
keys with Corgi Agent Deck.
Attribution
Credits:
