CodeSetup AI VS Code Extension

CodeSetup AI is the Visual Studio Code UI for the codesetup CLI. It helps users set up repositories, manage multi-repo workspaces, generate prompts, run workspace actions, and review token/cost usage without memorizing every CLI command.

Current Version

If you package the current UI fixes, also bump package.json from 0.0.1 to the next extension version, for example 0.0.2, and rebuild the VSIX.

What This Application Does

CodeSetup AI adds a CodeSetup AI view to the VS Code Activity Bar. From that view users can:

• Check whether the CodeSetup CLI is installed and working.
• Set up the current repository for Codex or Claude.
• Open generated files such as AGENTS.md, ai-context, prompts, and skills.
• Configure a multi-repo workspace with repos, features, and shared context.
• Register FRS, database schema, API spec, architecture, and UI reference context.
• Generate a fresh workspace database design from shared FRS context.
• Manage feature status, dependencies, parent features, pipeline actions, and completion.
• Run workspace validation, plan, project artifact generation, and workflow commands.
• View token and cost totals for feature work and workspace runs.
• View recent AI sessions and copy resume commands.
• Open CodeSetup logs and help files from inside VS Code.

Main Concepts

CodeSetup CLI

The extension is a UI wrapper around the codesetup command-line tool. The CLI owns the actual setup, validation, database design, prompt generation, feature management, and workspace execution behavior.

Single Repo Mode

If the opened folder is a normal repository, the extension checks for CodeSetup files such as:

• AGENTS.md
• ai-context
• prompts
• skills

Workspace Mode

If the opened folder contains codesetup-workspace.json, the extension treats it as a multi-repo workspace. It shows registered repos, active feature, current stage, shared context, database design state, usage totals, and workflow actions.

When users choose Workspace mode in onboarding, the flow continues into Configure Workspace, where they can register repos and shared contexts before opening the dashboard.

Feature Management

Feature Management is the workspace control panel for delivery work. Users can:

• Create and select features.
• See current status and stage.
• Track parent/dependency relationships.
• See blocked features when dependencies are not complete.
• Generate project prompts and run the feature pipeline.
• Mark a feature complete.
• Review token and cost totals for the feature.

The token column should show only the number, such as 6.5k. The cost column should show only the amount, such as $0.0302.

Workspace Database Design

Workspace Database Design creates the initial database schema package from shared FRS context before repo-specific implementation starts.

User flow:

1. Open a workspace folder.
2. Add at least one shared context with type frs.
3. Enable fresh database design for the workspace.
4. Run database design from the UI.
5. The extension invokes:

codesetup workspace database design --force --yes --ci

6. The CLI generates the database design output and registers the generated schema as shared context, usually workspace-database-schema.
7. Feature project generation can then use that schema context.

Requirements

• Visual Studio Code 1.90.0 or newer.
• Node.js and npm for development.
• TypeScript, installed through npm dependencies.
• CodeSetup CLI on PATH, configured through codesetup.cliPath, or available as a bundled executable.
• Codex CLI or Claude Code CLI for AI execution, enrichment, database design, and workspace runs.

On Windows x64, the extension can use a bundled CLI if resources/bin/win32-x64/codesetup.exe exists and the user approves bundled CLI usage.

Install Dependencies

npm install

Build Extension

npm run compile

The compiled JavaScript is written to out/.

Run Locally

1. Open CodeSetupVSExtension/ in VS Code.
2. Run npm install.
3. Run npm run compile.
4. Press F5 to start an Extension Development Host.
5. In the new VS Code window, open a repository or CodeSetup workspace.
6. Click the CodeSetup AI icon in the Activity Bar.

User Flow

1. User opens a repository or workspace in VS Code.
2. Extension checks for the CLI.
3. User chooses Single Repo or Workspace onboarding.
4. For Single Repo, the extension runs codesetup setup --platform <platform>.
5. For Workspace, the user registers repos and shared context.
6. User adds an FRS document as shared context.
7. User optionally runs Workspace Database Design to create the first schema.
8. User creates or selects a feature.
9. User attaches the required shared context to the feature/repos.
10. User validates the workspace.
11. User generates project prompts.
12. User runs the pipeline or opens generated prompts manually.
13. User reviews token/cost totals in Feature Management.
14. User completes the feature after delivery is done.

Workspace Commands

The extension can run these CLI commands:

codesetup workspace status
codesetup workspace validate --ci
codesetup workspace plan
codesetup workspace project --feature-name <feature> --ci
codesetup workspace run
codesetup workspace run --bootstrap-setup
codesetup workspace database design --force --yes --ci
codesetup workspace feature complete --name <feature>

The extension asks for confirmation before commands that may invoke an AI CLI across one or more repos.

Extension Settings

CLI Resolution Order

In auto mode, the extension checks:

1. codesetup.cliPath, if configured.
2. codesetup on the system PATH.
3. Bundled CLI, if approved and available.

Useful Commands

• CodeSetup AI: Refresh
• CodeSetup AI: Version
• CodeSetup AI: Status
• CodeSetup AI: Validate Environment
• CodeSetup AI: Setup This Repo
• CodeSetup AI: Open Onboarding
• CodeSetup AI: Open Dashboard
• CodeSetup AI: Manage Workspace
• CodeSetup AI: Preview Workspace Plan
• CodeSetup AI: Generate Workspace Artifacts
• CodeSetup AI: Run Workspace Workflow
• CodeSetup AI: Build Prompt for Current Stage
• CodeSetup AI: Open Pipeline Prompts
• CodeSetup AI: Open CodeSetup Logs
• CodeSetup AI: Verify CLI Install
• CodeSetup AI: Use Bundled CLI

Project Structure

.
|-- package.json                  VS Code extension manifest
|-- tsconfig.json                 TypeScript configuration
|-- resources/                    Extension icon and optional bundled CLI files
|-- src/
|   |-- extension.ts              Extension activation entry point
|   |-- commands/                 VS Code command handlers
|   |-- core/                     Shared constants and types
|   |-- services/                 CLI, workspace, prompt, skill, and session services
|   |-- utils/                    Workspace and configuration helpers
|   |-- views/                    CodeSetup AI sidebar tree view
|   `-- webview/                  Dashboard and setup webviews
`-- out/                          Compiled JavaScript output

Troubleshooting

Development Notes

Common development commands:

npm install
npm run compile
npm run watch

Before publishing or packaging:

npm run compile
vsce package