PostIdea Agent Monitor VS Code Extension

This extension helps developers maintain architectural integrity and track task completion during AI-assisted development sessions.

Features

Two Modes of Operation

Standalone Mode (Task List Only)

• Track task completion without PostIdea connection
• Verify AI agent implementations against your task list
• Session reports showing completed/missed tasks
• No account or project required

Connected Mode (PostIdea Integration)

• Load locked architectural decisions from your PostIdea project
• Real-time detection of code that violates these decisions
• Inline warnings and diagnostics in the editor
• Architecture drift detection
• Configurable detection triggers (on save, on type)

Getting Started

1. Install the extension
2. Click the status bar item (shows "Agent Monitor" by default)
3. Choose your mode:
   • Connect PostIdea Project - Full integration with architecture decisions
   • Use without PostIdea (task list only) - Standalone task tracking

Standalone Mode

Perfect for developers who want to:

• Verify AI agents completed requested tasks
• Track implementation progress
• Get session reports
• Work without PostIdea account

Connected Mode

Ideal for teams using PostIdea who want to:

• Enforce architectural decisions
• Catch drift before code review
• Maintain consistency across sessions
• Validate against locked architecture

Development Setup

To set up the development environment for this extension:

Prerequisites

• Node.js (version 18 or higher)
• VS Code (version 1.80 or higher)
• Yeoman (yo) and generator-code for scaffolding (if starting fresh):

  npm install -g yo generator-code
  

Steps

1. Clone the repository (if you haven't already):

   git clone <repository-url>
   cd postidea-vscode-extension
   

2. Install dependencies:

   npm install
   

3. Compile the extension:

   npm run compile
   

   This produces out/extension.js, which is the entrypoint used by both the development host (F5) and the test runner.

4. Run tests (optional):

   npm test
   

5. Launch the extension in development mode:

   • Open this project in VS Code (code .).
   • Press F5 to open a new Extension Development Host window.
   • In the new window, open a workspace/folder.
   • Click the status bar item or open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P) and search for "Agent Monitor: Connect or Use Standalone" to get started.

Configuration

This extension can be configured via VS Code settings (File > Preferences > Settings). Search for "PostIdea" to see available options:

• postidea.apiBaseUrl: Base URL for the PostIdea API (default: https://postidea.app).
• postidea.enableRealTimeDetection: Enable or disable real-time drift detection (default: true). Only applies in connected mode.
• postidea.detectionTrigger: When to trigger drift detection (onSave, onType, manual; default: onSave). Only applies in connected mode.
• postidea.showInlineWarnings: Show inline warning squiggles in the editor (default: true).
• postidea.ignoredDecisions: Array of decision IDs to ignore during detection. Only applies in connected mode.
• postidea.ignoredFiles: Array of glob patterns for files to ignore (default: ["**/node_modules/**"]).

Commands

• Agent Monitor: Connect or Use Standalone - Choose between standalone mode or PostIdea connection
• Agent Monitor: Disconnect Project - Disconnect from PostIdea and return to standalone mode
• Agent Monitor: Refresh Decisions - Refresh architectural decisions from PostIdea (connected mode only)

Branding and Icon

This extension includes a branded icon (images/icon.png) that appears in the VS Code extensions marketplace and extension panel. The icon asset is configured in package.json and will be included automatically when the extension is packaged for distribution.

Build and Packaging

The extension uses a single runtime artifact (out/extension.js) as the entrypoint, declared in package.json as "main": "./out/extension.js":

• Compilation: npm run compile generates out/extension.js (TypeScript transpiled directly) for development, testing, and F5 launches.
• Bundling: npm run package (called by npm run vscode:prepublish) bundles the extension using esbuild and outputs to the same out/extension.js file, suitable for publishing.

The VSIX package includes out/extension.js and all assets except those listed in .vscodeignore (including dist/ which is never used).

For local development: npm run compile then press F5 to test. For publishing: npm run vscode:prepublish builds and packages for release.

Contributing

See CONTRIBUTING.md for guidelines on how to contribute to this project.