Personaut Extension

🚀 Public Preview | v0.1.6

Personaut is your empathetic AI development assistant that helps you build applications from idea to implementation. Chat with AI, gather user feedback, and generate full-stack applications - all within VS Code!

An AI-powered VS Code extension with feature-based architecture and centralized agent management.

✨ Features

💬 Chat

Conversational AI assistant powered by Google Gemini or AWS Bedrock. Get help with coding, debugging, architecture decisions, and more. Chat with any of your created personas to get feedback from their perspective. All conversations are saved for future reference.

📊 Feedback

Gather authentic user feedback through AI-powered persona interviews. Generate realistic user personas, conduct automated interviews, and synthesize insights to inform your product decisions.

🏗️ Build Mode ⚠️ Experimental

Transform your ideas into working applications through a guided multi-stage workflow:

• Idea → Define your application concept
• Users → Identify target personas and demographics
• Features → Generate user stories and feature sets through persona interviews
• Stories → Create detailed user stories mapped to features
• Design → Create UX flows, screen designs, and generate Look & Feel
• Finalize → Export comprehensive project documentation (task list, steering document, requirements)

⚠️ Important: Build Mode is experimental and currently only works for new projects. It will scaffold a fresh React/Next.js/Vue/Flutter application in an empty directory. Adding to existing projects is not yet supported.

Supported Frameworks:

• React (Create React App)
• Next.js
• Vue.js
• Flutter (experimental)

Known Issues: See the Known Issues section below for current limitations.

🎯 Quick Start

Installation

1. Download the personaut-extension-0.1.6.vsix file.
2. Open VS Code.
3. Install the extension: Press Cmd+Shift+P (or Ctrl+Shift+P) and run Extensions: Install from VSIX...
4. Select the VSIX file.
5. Open the Personaut sidebar to start!

⚠️ Upgrading from v0.1.2 or earlier?
Chat storage has been migrated to a new format. If you experience issues, run Personaut: Refresh Extension from the Command Palette (Cmd+Shift+P) to clear old data.

See: Setup Guide for detailed instructions.

⚙️ Configuration Required

Before using Personaut, you must configure an AI provider:

1. Open VS Code Settings (Cmd+, or Ctrl+,)
2. Search for "Personaut"
3. Choose your provider:
   • Google Gemini: Enter your Gemini API key
   • AWS Bedrock: Enter AWS credentials (access key, secret key, region)
4. Save and reload VS Code

💡 Tip: Get a free Gemini API key at ai.google.dev

System Requirements

• VS Code: Version 1.90.0 or higher
• Node.js: Required for Build Mode (v18+ recommended)
• npm: Required for Build Mode project scaffolding
• Internet connection: Required for AI provider API calls

💬 Chatting with Personas

After creating personas in the Feedback section:

1. Open the Chat tab
2. Click the persona selector dropdown
3. Choose a persona to chat with
4. Get feedback from their unique perspective!

💡 Tip: Personas remember their backstory and will respond in character based on their demographics and preferences.

📁 Data Storage

All your data is stored locally:

• Conversations: ~/.gemini/antigravity/conversations/
• Build Projects: .personaut/ folder in your workspace
• API Keys: VS Code Secure Storage (encrypted)
• Settings: VS Code Settings (JSON)

🔒 Privacy: Your data never leaves your machine except for AI API calls to your configured provider.

📊 Current Status

• ✅ Chat: Full conversational AI with history and context management
• ✅ Feedback: AI-powered persona interviews and insight synthesis
• ✅ Build Mode: Complete Planning Phase (Idea → Design) with multi-agent workflows
• ✅ Code Generation: Automated screen generation with React/Next.js/Vue/Flutter support
• ✅ Data Persistence: Robust file-based storage for all features
• ⚠️ Screenshots: Dev server optimization in progress (see Known Issues)

See: Roadmap for status.

🔒 Security

All critical security vulnerabilities have been fixed:

• ✅ Path traversal protection
• ✅ Input validation
• ✅ Workspace boundaries
• ✅ Error sanitization

See: Architecture for security details.

🐛 Bugs

All critical bugs have been resolved:

• ✅ Message routing complete
• ✅ Handler implementations complete
• ✅ AI provider initialization fixed

See: Roadmap for issue tracking.

⚠️ Known Issues

Build Mode - Experimental (v0.1.5)

New Projects Only

• Issue: Build Mode currently only supports creating new projects from scratch.
• Impact: Cannot add Build Mode-generated code to existing projects.
• Workaround: Use Build Mode to create a new project in an empty directory, then manually integrate the generated code into your existing project if needed.
• Status: Existing project support planned for future release.

Screenshot Caching

• Issue: During the build process, the dev server runs continuously for all screens, which can result in cached or stale screenshots. Additionally, screenshots may be captured even when webpack compilation fails.
• Impact: Generated screenshots may not accurately reflect the latest code changes.
• Workaround: Delete the generated project and start a fresh build if screenshots appear incorrect.
• Fix: Scheduled for v0.1.5 (December 24, 2025) - The dev server will be restarted per screen for fresh screenshots.

See: GitHub Issue for technical details.

📁 Directory Structure

personaut/
├── src/
│   ├── core/              # Core services
│   │   ├── agent/         # Agent and AgentManager (lifecycle management)
│   │   ├── providers/     # AI provider implementations (Gemini, Bedrock)
│   │   ├── tools/         # Tool implementations (File, Terminal, Browser, MCP)
│   │   ├── integrations/  # External integrations (MCP, Terminal)
│   │   └── prompts/       # System prompts for different modes
│   ├── features/          # Feature modules
│   │   ├── build-mode/    # Build mode feature
│   │   ├── chat/          # Chat feature with ConversationManager
│   │   ├── personas/      # Personas feature
│   │   ├── feedback/      # Feedback feature
│   │   └── settings/      # Settings feature
│   ├── shared/            # Shared utilities and services
│   │   ├── services/      # Validation, storage, error handling
│   │   ├── types/         # TypeScript type definitions
│   │   └── utils/         # Utility functions
│   ├── presentation/      # SidebarProvider (routing layer)
│   ├── di/                # Dependency injection container
│   ├── webview/           # React UI (needs implementation)
│   └── extension.ts       # Extension entry point
├── __tests__/             # Test files
│   ├── integration/       # Integration tests
│   └── properties/        # Property-based tests
└── docs/                  # Documentation

🧪 Testing

# Run all tests
npm test

# Run specific test
npm test -- BuildModeHandler

# Watch mode
npm test -- --watch

Results: 655 tests passing, 22 test suites passing

📚 Documentation

Essential Reading

1. Setup & Quick Start - Get the environment and UI running.
2. Project Roadmap - Future plans and status.

Architecture

• System Architecture
• Feature Guide
• Project Structure

Security

• See Architecture for security overview.

🚀 Development

Build

npm run compile

Watch Mode

npm run watch

Package

vsce package

🔧 Architecture Highlights

Centralized Agent Management

The AgentManager provides:

• Factory Pattern: Creates agents with proper configuration per conversation
• Lifecycle Management: Handles agent creation, disposal, and cleanup
• Resource Management: LRU cache with configurable limits (default: 10 agents, 5min timeout)
• Capability Registry: Tracks agent capabilities for discovery and validation
• Message Queuing: Sequential message processing to prevent race conditions
• Error Recovery: Abort/restart, webview reconnection, conversation export

Automatic Conversation Persistence

• Auto-Save: Messages automatically saved via onDidUpdateMessages callback
• Retry Logic: Exponential backoff (3 attempts) for save failures
• Schema Migration: Automatic V1→V2 migration with validation
• Round-Trip Integrity: Conversation data preserved across save/load cycles

Multi-Agent Communication

• Agent-to-Agent Messaging: Secure communication through shared conversations
• Capability Discovery: Agents can query each other's available tools
• Security Validation: Session ownership and permission checks
• Message Sanitization: Content sanitization to prevent injection attacks

Feature-Based Structure

Each feature is self-contained with:

• Handler (message routing)
• Service (business logic)
• Types (TypeScript interfaces)
• Tests (unit + property-based)

Security First

• Input validation on all handlers
• Path traversal protection
• Workspace boundary enforcement
• Error message sanitization
• API keys stored in VS Code secure storage

Dependency Injection

• Clean service registration
• Easy testing and mocking
• Loose coupling between components

📝 Key Files

Entry Points

• src/extension.ts - Extension activation and DI container setup
• src/presentation/SidebarProvider.ts - Webview management and message routing
• src/webview/App.tsx - UI entry point (needs implementation)

Core Agent System

• src/core/agent/AgentManager.ts - Centralized agent lifecycle management
• src/core/agent/Agent.ts - Individual AI agent implementation
• src/core/agent/AgentTypes.ts - Agent configuration types
• src/shared/types/AgentErrorTypes.ts - Comprehensive error types

Conversation Management

• src/features/chat/services/ConversationManager.ts - Persistence, migration, pagination
• src/features/chat/services/ChatService.ts - Message routing and agent coordination
• src/shared/utils/retryUtils.ts - Retry logic with exponential backoff

AI Providers

• src/core/providers/GeminiProvider.ts - Google Gemini integration
• src/core/providers/BedrockProvider.ts - AWS Bedrock integration
• src/core/providers/NativeIDEProvider.ts - VS Code native AI integration

Feature Services

• src/features/build-mode/services/BuildModeService.ts - Build mode with agent integration
• src/features/feedback/services/FeedbackService.ts - Feedback with agent integration
• src/features/personas/services/PersonasService.ts - Personas with agent integration
• src/features/settings/services/SettingsService.ts - Settings with agent notification

Feature Handlers

• src/features/build-mode/handlers/BuildModeHandler.ts
• src/features/chat/handlers/ChatHandler.ts
• src/features/personas/handlers/PersonasHandler.ts
• src/features/feedback/handlers/FeedbackHandler.ts
• src/features/settings/handlers/SettingsHandler.ts

Dependency Injection

• src/di/Container.ts - Service registration and resolution

🤖 AgentManager API

The AgentManager is the central component for managing AI agent lifecycles across conversations.

Core Methods

Agent Lifecycle

// Get or create an agent for a conversation
await agentManager.getOrCreateAgent(conversationId, mode);

// Dispose a specific agent
await agentManager.disposeAgent(conversationId);

// Dispose all agents (called during extension deactivation)
await agentManager.disposeAllAgents();

Message Handling

// Send a message with automatic queuing
await agentManager.sendMessage(
  conversationId,
  input,
  contextFiles,
  settings,
  systemInstruction,
  isPersonaChat
);

// Switch between conversations (< 500ms target)
await agentManager.switchConversation(fromId, toId, mode);

Settings Management

// Update settings (triggers reinitialization if critical settings changed)
await agentManager.updateSettings(settings);

// Manually reinitialize all agents
await agentManager.reinitializeAgents();

Capability Management

// Register a capability for an agent
agentManager.registerCapability(conversationId, capability);

// Get all capabilities for an agent
const capabilities = agentManager.getCapabilities(conversationId);

// Query if an agent has a specific capability
const hasCapability = agentManager.queryCapability(conversationId, 'tool-name');

Error Recovery

// Abort and restart an unresponsive agent
const newAgent = await agentManager.abortAndRestartAgent(conversationId);

// Export conversation data for critical errors
const jsonData = await agentManager.exportConversationData(conversationId);

// Handle webview disconnection/reconnection
const states = await agentManager.handleWebviewDisconnection();
await agentManager.handleWebviewReconnection(webview, states);

Resource Management

// Get active agent count
const count = agentManager.getActiveAgentCount();

// Check if agent exists
const exists = agentManager.hasAgent(conversationId);

// Validate agent-to-agent communication
const allowed = agentManager.validateAgentCommunication(fromId, toId);

Configuration

const config: AgentManagerConfig = {
  webview: vscode.Webview,
  tokenStorageService: TokenStorageService,
  conversationManager: ConversationManager,
  maxActiveAgents: 10,        // Default: 10
  inactivityTimeout: 300000,  // Default: 5 minutes (ms)
};

const agentManager = new AgentManager(config);

Automatic Features

• Message Persistence: All messages automatically saved via onDidUpdateMessages callback
• Retry Logic: Save operations retry 3 times with exponential backoff
• Resource Cleanup: Inactive agents disposed after timeout (default: 5 minutes)
• LRU Eviction: Least recently used agents disposed when limit reached
• Periodic Cleanup: Runs every 5 minutes to clean up inactive agents
• Comprehensive Logging: All operations logged with context for debugging

⚙️ Settings That Require Agent Restart

When these settings are changed, all active agents are automatically disposed and recreated with the new configuration:

Critical Settings (Trigger Reinitialization)

• provider - AI provider selection (gemini, bedrock, nativeIde)
• geminiApiKey - Google Gemini API key
• geminiModel - Gemini model selection
• awsAccessKey - AWS access key for Bedrock
• awsSecretKey - AWS secret key for Bedrock
• awsRegion - AWS region for Bedrock
• awsProfile - AWS profile name
• awsUseProfile - Whether to use AWS profile
• bedrockModel - Bedrock model selection

Non-Critical Settings (No Restart Required)

• theme - UI theme
• autoRead - Auto-read file permissions
• autoWrite - Auto-write file permissions
• autoExecute - Auto-execute command permissions
• rateLimit - Rate limit configuration (see Token Monitoring below)
• rateLimitWarningThreshold - Warning threshold percentage (see Token Monitoring below)

📊 Token Monitoring

Personaut includes built-in token usage monitoring to help you manage API costs and prevent unexpected charges.

Settings

Setting	Default	Description
personaut.rateLimit	100,000	Maximum tokens allowed per conversation
personaut.rateLimitWarningThreshold	80	Percentage of limit at which to show warning (1-100)

Commands

Command	Description
Personaut: Reset Token Usage	Reset the token counter for tracking
Personaut: View Token Usage	Display current token usage statistics
Personaut: Set Conversation Limit	Set a custom token limit

How It Works

1. Tracking: Every LLM call records input and output tokens
2. Accumulation: Tokens accumulate across messages in a conversation
3. Warning: When usage reaches the warning threshold (default 80%), a notification is displayed
4. Enforcement: When the limit is reached, new LLM calls are blocked with a clear error message
5. Persistence: Token usage is saved and restored across VS Code sessions

Token Estimation

When providers don't return token counts, Personaut estimates using a conservative formula:

• Estimation rate: ~4 characters per token
• Minimum: 1 token for any non-empty text

Troubleshooting

"Token limit exceeded" error:

• Use Personaut: Reset Token Usage command to reset the counter
• Increase personaut.rateLimit in settings
• Use Personaut: Set Conversation Limit for conversation-specific limits

Usage seems high:

• Token counts include both input (your messages + context) and output (AI responses)
• System prompts and tool definitions also consume tokens
• Long conversations accumulate tokens quickly

Warnings not appearing:

• Check that rateLimitWarningThreshold is set correctly (1-100)
• Warnings only appear once per threshold crossing (reset clears this)

How It Works

1. User changes settings via SettingsService
2. SettingsService saves to VS Code config + secure storage
3. SettingsService calls agentManager.updateSettings()
4. AgentManager checks if critical settings changed
5. If critical: disposes all agents, clears registry
6. Next agent request creates fresh agent with new settings

🎯 Next Steps

Immediate

1. Apply quick fix to get UI working
2. Test all features
3. Package extension

Short-term

1. Add user documentation
2. Performance optimization
3. User feedback collection

Long-term

1. Create spec for UI refactoring
2. Extract feature components
3. Add UI component tests
4. Implement remaining features

🤝 Contributing

See CONTRIBUTING.md in the project root.

📄 License

See LICENSE in the project root.

---

Need Help?

• Check Setup Guide to get UI working
• Check Roadmap for overall status
• Check Architecture for security info