AI Workspace

A VSCode extension for the prompt tasks you keep in .prompts/.

It creates today's folder for you, makes a task in two keystrokes, shows what is done and what is stuck, launches a plan, brainstorm, implement or fix action — or any slash command you have installed — against the task you are looking at, and lets the AI report back when it finishes — including how long it took, how many tokens it used, which commits came out of it, and the files it produced.

How it works

.prompts/                        (git-ignored)
├── 2026-09-17/refactor-auth/
│   ├── task.md                  what you wrote — the only file treated as a task
│   └── plan.md, report.md …     what the AI produced — listed as artifacts
└── .aiws/
    ├── index.json               status, history, sessions, git links
    ├── bin/aiws                 stable CLI path, regenerated on every startup
    └── AGENTS.md                the contract, generated for agents to read

The extension and the aiws CLI are two separate processes writing one file, so every change goes through a cross-process lock. Nothing else writes index.json.

Using it

1. Open a project. Today's folder appears; if you leave the editor open past midnight, tomorrow's appears too.
2. New task in the view title bar. Type a title, press Enter. Esc leaves nothing behind.
3. Write what you want in task.md. A one-liner is fine: ✨ Refine prompt has an agent read the code and your earlier tasks, then rewrite it in more detail — in your style, without adding scope. Your original wording is kept under ## Original prompt.
4. Press one of the action buttons in the editor title bar. The prompt goes straight to your AI assistant.
5. The AI runs aiws ack to claim the task, then aiws status … done when it finishes. The tree updates, and a notification tells you.
6. Open the task details to see duration, tokens, estimated cost, commits, the PR, and the files the AI produced.
7. When you are happy with the work, commit it: Commit, Commit & Push, or Commit, Push & Create PR on the task. The AI never commits on its own.

Settings

The ... menu on the Tasks view has two entry points: Open Settings goes to this extension's settings page, and Set Launch Target switches where actions open without leaving the sidebar. Both are in the command palette too.

Committing

The AI is told, in every action prompt, not to commit, push or open a pull request. It leaves its work in the working tree. Three commands on a task — right-click it in the tree, or use the command palette — take it from there:

Each one sends a prompt to your AI the same way an action does, so the commit message is written with the context of what actually changed, and your aiWorkspace.commit.* conventions travel with it.

Before committing, the AI cleans the files in scope — everything changed since the task was launched, plus new untracked files. The rule is deliberately narrow: delete code that was commented out and abandoned, and debug or scratch comments left behind; keep every comment that explains why the code is the way it is, and change no behaviour while cleaning.

That cleanup rule and the steps after it are yours to change, per command, in aiWorkspace.git.instructions.commit, .commitPush and .commitPushPr. Each starts as the built-in text; clearing one brings the default back. What is always sent around them, whatever you write: the branch check, which files are in scope, the secrets guard, and the rule against rewriting history. If you allowed the Claude skills below, your text is written into them too, under .claude/skills/ in the repository — keep that in mind before committing them.

The AI is also told to stop rather than improvise: if HEAD is no longer on the branch the task was launched on, if an untracked file looks like a secret or machine-local config, or if there is simply nothing to commit, it says so instead of committing.

If your launch target is orca or app, these commands use the default route instead and say so. Both put the AI somewhere your uncommitted work is not — an Orca worktree is a fresh checkout, and the desktop app cannot reach the repository at all. The herdr target runs them as usual: its tab opens in this folder.

The commit commands sit behind a ✨ button wherever you work:

• on each task in the Tasks tree, and in the title bar of an open task.md: commits that task's changes;
• in the Tasks view title bar: asks whether to commit Current changes or a task's changes;
• in the Source Control title bar: commits everything uncommitted, no task involved.

The task details page has a button bar too: Run AI Action, Mark Done, Commit, Commit & Push and Commit, Push & Create PR, all for that task.

If you allow AI Workspace to add Claude skills, you can also commit from inside Claude with slash commands. They carry the same cleanup rule and limits:

Anything you type after the command is passed on, for example /aiws-commit only the api folder. Claude never runs these on its own. The skills are rewritten when the extension starts and when you change aiWorkspace.commit.*, aiWorkspace.git.instructions.* or aiWorkspace.agent.readmePath.

A README for every prompt

Put instructions you want the AI to follow on every task — project conventions, where things live, what never to touch — in .prompts/README.md. Every action and Commit command then tells the AI to read it first. The prompt's own rules still win a conflict, so the README cannot, for example, make an action commit. It is pointed at, not pasted in, and only when it exists; point aiWorkspace.agent.readmePath elsewhere in the workspace to use another file.

A source overview for newcomers

AI Workspace: Write Source Overview (command palette, or the views' ••• menu) has the AI read the code and write an onboarding overview, in Vietnamese, to .prompts/source/: overview.md (what the project is, how to run it), structure.md (folders and modules), domain.md (concepts, rules, workflows) and routes.md (routes, commands and other entry points). Run it again to Update — check it against the code and keep what is still right — or Rebuild from scratch. Once overview.md exists, task actions, Refine Prompt and task docs tell the AI to read it, as they do the README. The AI only writes those four files and never commits.

Task docs in Notion

When a task is done or in review, 📝 Docs → Notion (CodeLens, or the task's context menu) has the AI write docs.md beside the task — overview, changes, files, how to test, and the pull request link when the task has one — then the extension uploads it to Notion. The AI never sees your token.

In Notion, the root page holds one page per workspace folder, and each of those holds one page per task, titled with the docs' own heading — a clean title the AI writes, not the raw task name — followed by · <task id>. Running it again updates that page rather than adding another. Push Docs to Notion uploads the docs.md already on disk without asking the AI to rewrite it — useful after editing it by hand, or if the editor reloaded before the upload.

To connect:

1. Create an internal integration at notion.so/my-integrations and copy its token.
2. In Notion, open the page that should hold your docs, choose ••• → Connections, and add the integration.
3. Run AI Workspace: Connect Notion and paste the token, then the page's URL.

The token is kept in the editor's secret storage, not in settings; Disconnect Notion removes it. Until both are set, the docs commands send nothing and say why.

Running a task in Orca

Set the launch target to orca and an action hands the task to the Orca app instead of running it here: Orca creates a worktree for this project, starts the agent on the task prompt, selects it, and comes to the front. Each action gets its own worktree, so two tasks never share a checkout.

The task file itself stays in this workspace. The prompt names it by absolute path, and the agent writes back through this workspace's aiws shim, so status, duration, cost and artifacts land on the task you launched — from the other checkout.

The prompt also names this workspace as the main checkout and tells the agent to apply its diff there once the code changes are done, because the worktree is thrown away and anything left in it would go with it.

Orca is reached through its CLI, because orca:// has no deep link for a project or a task. The target finds the CLI in this order: aiWorkspace.orca.cliPath, then orca on your PATH, then the CLI inside Orca.app. The last one matters: Orca's PATH shim is a root-owned symlink, and where it cannot be read it fails with "Unable to determine Orca.app path" — so the target checks that a candidate actually answers before using it.

Running a task in herdr

Set the launch target to herdr and an action opens a tab in the running herdr session instead of the editor terminal. The tab goes into the herdr workspace that already has a pane in this folder, or into a new workspace for the project when none does, and herdr switches to it. The agent is started there and given the task prompt, and herdr tracks whether it is working, blocked or done like any other agent.

The tab opens in this folder, so the agent works on the same checkout and git actions run there too. Each agent is named after its task (aiws-<task id>, with -2, -3, … for a second launch), which is how herdr agent list tells them apart.

herdr has to be running already — start it with herdr in a terminal. The target finds the CLI in this order: aiWorkspace.herdr.cliPath, then herdr on your PATH, then /opt/homebrew/bin, /usr/local/bin and ~/.local/bin, since the editor may not inherit your shell's PATH.

Live conversation activity

By default a task only knows what the agent chose to report. Install the Claude Code hooks — AI Workspace: Install Claude Hooks — and each task also shows whether the AI is working right now, whether it is waiting on you, and how many turns the conversation has run.

This appends three hooks to ~/.claude/settings.json, backs the file up first, and leaves every hook already there untouched. AI Workspace: Remove Claude Hooks takes them back out. Everything else works without them; only the live indicator needs them.

Activity is shown, never acted on. Nothing can tell "waiting for your reply" from "finished", so the extension does not guess — a task's status still only changes when the agent says so or when you do.

Clearing up

The index only ever grew: a task whose file you deleted was flagged as missing and stayed in the list forever. Two commands fix that.

Clear Tasks… removes a group — everything done, everything archived, everything whose file is gone, or the whole index — and asks whether the task folders should go with it.

Rebuild Index From Disk scans the tree and rebuilds, keeping every id, title, status, history, session and git link of a task whose file is still there, and dropping the entries whose file is not. It asks before dropping, because status and metrics live only in the index and disk cannot give them back. A rebuild that changes nothing says so and writes nothing.

Right-click a task for Delete Task to do one at a time.

Worth knowing: removing a task from the index while leaving its task.md in place is not permanent. The watcher notices an unindexed task file and adopts it again within seconds — as a new task, named after its folder, with no history. That is the reconciler working as intended, so the dialogs say it plainly. Choose to delete the files when you want the task actually gone.

Things worth knowing

Costs are estimates. Token counts are read from the AI tool's own logs and are exact. The money figure is those counts multiplied by rates you configure. A model with no configured rate shows —, never $0.00, because a confident zero reads as "this was free".

Metrics need a provider that writes session logs. Claude Code does. Whether Codex does is currently unknown — it has not been run on the development machine, so the honest answer is "unverified", not "no". Tasks without logs show why instead of showing zeros.

POSIX only. The aiws shim is a /bin/sh script. On Windows the extension reports that the CLI is unavailable rather than writing something that cannot run.

Single-root workspaces only. A multi-root workspace is rejected with a clear message rather than a guess about which root owns .prompts/.

Restricted Mode disables it. The extension writes an executable into your workspace, so it declares that it does not support untrusted workspaces.

.prompts/ must be git-ignored. The extension checks with git check-ignore — which sees your global excludes file, not just the repository's .gitignore — and offers to add it before creating anything.

For agents

See docs/agent-integration.md, or read the AGENTS.md the extension generates inside .prompts/.aiws/.

Installing locally

./scripts/install-local.sh

Checks the toolchain, installs dependencies, typechecks, runs the tests, builds, packages, verifies the archive, and only then installs. Any failing step stops it — a broken extension that installs is worse than one that does not, because it disables itself quietly.

Reload the window afterwards: Cmd+Shift+P → Developer: Reload Window.

Actions and installed commands

Out of the box the task buttons are four slots: Plan, Brainstorm, Implement and Fix. Each sends a command you have installed when it recognises one — /ak:plan, /ak:brainstorm (or /superpowers:brainstorming), /ak:cook, /ak:fix — and otherwise a plain instruction any agent understands, so the buttons work whether or not you use a command kit.

The action picker (Run AI Action) also lists every slash command found installed, grouped as:

With codex as the provider, ~/.codex/prompts/*.md is listed as /prompts:<name> instead. Only file names and frontmatter (name, description, user-invocable) are read. Set aiWorkspace.discoverCommands to false to turn this off.

Custom actions

To pin your own buttons, set aiWorkspace.actions — in your user settings, or per project in .vscode/settings.json when a repository uses its own commands:

"aiWorkspace.actions": [
  "/ak:plan",
  "/ak:fix",
  { "command": "/ak:ship", "label": "Ship" }
]

A plain string labels itself; an object gives a shorter button. Only slash commands are accepted — anything with spaces or shell characters is ignored with a warning, because these strings end up in a prompt that the terminal route types into your shell. One bad entry never empties the toolbar.

Kits and auto tasks

A project that works with one command kit can say so in .vscode/settings.json:

"aiWorkspace.kit": "ak"   // or "ecc"; "all" (default) changes nothing

The action picker then shows only that kit's curated commands, plus anything in aiWorkspace.actions (which a repository can also set), with All installed commands… at the bottom for everything else. The task buttons are your aiWorkspace.actions when you set any, otherwise the kit's first four installed commands. Commands not installed are shown greyed out. Kit commands are found however many other skills you have installed.

ECC's own command map lists /tdd, /verify and /e2e; the installed plugin (2.2.3) ships TDD and verification as the tdd-workflow and verification-loop skills instead, and its /quality-gate formats a single file, so it is a manual action rather than a pipeline step.

AI Workspace: Install Command Kit… shows whether the ECC and Superpowers Claude Code plugins are installed, and installs (or re-enables) a missing one. It shows the exact claude plugin commands first, then runs them in a terminal; it never edits ~/.claude itself. With "aiWorkspace.kit": "ecc" and ECC missing, the action picker offers Install ECC… too. Start a new Claude session afterwards.

With a kit set, New Task asks Manual or Auto. A manual task works as always. An auto task walks the chain one step at a time:

1. Press ▶ Start pipeline in the task's CodeLens (or the toast offered after creating it) once the task is written.
2. Each step runs in a new Claude Code session in a terminal of its own — or a new herdr tab when herdr is your launch target. Other launch targets are used for manual actions only, because they cannot give each step a fresh session.
3. The step writes a report beside the task, report-<nn>-<step>.md, in aiWorkspace.agent.reportLanguage, then reports review.
4. You get one prompt: Continue, Rerun or Stop, with Open report. The next step is told to read the earlier reports, and steps after a plan step are told to take the plan path from them. A step that reports without a fresh report gets a "report missing" warning instead.
5. After the last step, Mark done finishes the task.

A step that reports blocked pauses the pipeline; Rerun or Resume from the CodeLens or the task's context menu. Marking the task blocked or done by hand pauses or stops it. Progress shows as ⟳ 2/5 · /ak:plan in the list and grid and as a Pipeline section in the detail view. Every step launch, reruns included, opens a new terminal; close old ones when you are done reading them.

The commands a step runs always come from the built-in chain or your machine-scoped aiWorkspace.pipeline, never from the task index, so a repository cannot choose them. Avoid running manual actions on an auto task while a step is running: without a session id their status reports look the same as the step's.

Marking a task done by hand

Not everything gets finished by an agent. The ✓ button on a task row, in the editor title bar of a task.md, and in the CodeLens marks it done in one click, with an Undo. Manual changes are attributed to you, which is why they do not trigger a notification.

Development

npm install
npm run build      # both bundles plus webview assets
npm test           # typecheck + unit tests, no VSCode needed
npm run package    # build a .vsix and verify what it contains

npm run package fails if the archive is missing the CLI bundle, or if it contains .prompts/, .claude/, sources or tests.