Skip to main content

Extension Architecture

This page documents the architecture of the Huckleberry Task Manager extension for developers interested in understanding how it works or contributing to its development.

Architectural Overview​

Huckleberry is built on a modular architecture with clean separation of concerns. The extension is divided into the following main components:

huckleberry-extension/
├── src/
│   ├── extension.ts            # Main entry point
│   ├── types.ts                # TypeScript type definitions
│   ├── config.ts               # Configuration defaults
│   ├── config/                 # Configuration management
│   ├── services/               # Core business logic
│   ├── handlers/               # Command handlers
│   ├── tools/                  # Language model tools
│   └── utils/                  # Utility functions

Extension Entry Point​

The extension.ts file serves as the entry point for the VS Code extension. It handles:

  • Extension activation and deactivation
  • Command registration
  • Chat participant registration
  • Language model tool registration

Core Components​

Task Management System​

The Task Management System (services/taskManager.ts) is responsible for:

  • Creating, updating, and deleting tasks
  • Storing and retrieving task data
  • Enforcing task structure and validation
  • Managing task relationships and dependencies

Chat Integration​

The Chat Participant (services/chatParticipant.ts) integrates with VS Code's chat interface, allowing:

  • Natural language interaction with the task manager
  • Command parsing and intent recognition
  • Response formatting and presentation

Language Model Tools​

The Language Model Tools (tools/) allow VS Code's language model (like GitHub Copilot) to directly interact with Huckleberry's functionality:

  • Tool registration and discovery
  • Validation and execution of tools
  • Result formatting for the language model

Agent Mode Implementation​

The Agent Mode implementation (tools/) allows VS Code's AI assistants (like GitHub Copilot) to directly interact with Huckleberry's functionality:

  • createTask: Creates a new task with optional priority
  • initializeTracking: Sets up task tracking in a workspace
  • scanTodos: Converts TODO comments to tasks
  • listTasks: Lists and filters tasks
  • markTaskDone: Completes a task
  • updateTaskPriority: Changes a task's priority level

These tools are registered with VS Code's Language Model Tools API, enabling seamless integration with AI assistants in agent mode. While users experience these as "Agent Mode Features," they're implemented as Language Model Tools in the codebase.

File System Interaction​

The File System Service (services/fileSystem.ts) manages all interactions with the workspace file system:

  • Task persistence to JSON and Markdown files
  • Workspace scanning for TODOs
  • File watching for changes

Detailed Architecture​

Request Flow​

When a user interacts with Huckleberry through chat, the request flows as follows:

  1. Input: User types @Huckleberry create a task to implement authentication
  2. Chat Participant: Receives the message and extracts the intent
  3. Command Router: Identifies the appropriate command handler
  4. Command Handler: Processes the command, invoking the necessary services
  5. Task Manager: Performs the requested operation on the task data
  6. Persistence Layer: Stores changes to the file system
  7. Response Formatter: Generates a human-readable response
  8. Output: Response displayed in the chat interface

Language Model Tool Flow​

When a language model uses a Huckleberry tool:

  1. Tool Invocation: LM calls a registered tool with parameters
  2. Tool Validation: Parameters are validated for correctness
  3. Service Layer: Tool routes to the appropriate service
  4. Operation: The requested operation is performed
  5. Result Formatting: Results are formatted for the language model
  6. Response: Structured data returned to the language model

Key Services​

Task Service​

/**
 * Core service for managing tasks
 */
export class TaskService {
  /**
   * Creates a new task with the provided details
   * @param title Task title
   * @param description Optional task description
   * @param priority Task priority level
   * @returns The created task object
   */
  public async createTask(
    title: string, 
    description?: string, 
    priority?: TaskPriority
  ): Promise<Task>;

  /**
   * Updates an existing task
   * @param taskId The ID of the task to update
   * @param updates Object containing the fields to update
   * @returns The updated task
   */
  public async updateTask(
    taskId: string, 
    updates: Partial<Task>
  ): Promise<Task>;

  // Additional methods for task management...
}

TODO Scanner Service​

/**
 * Service for scanning the workspace for TODO comments
 */
export class TodoScannerService {
  /**
   * Scans the workspace for TODO comments and creates tasks
   * @param pattern Optional glob pattern to filter files
   * @returns Array of created tasks
   */
  public async scanTodos(pattern?: string): Promise<Task[]>;
}

Language Model Tool Provider​

/**
 * Provider for registering Language Model tools
 */
export class LanguageModelToolProvider {
  /**
   * Registers all Huckleberry tools with the VS Code Language Model API
   * @param context Extension context
   */
  public registerTools(context: vscode.ExtensionContext): void;
}

Extension Lifecyle​

Activation​

The extension activates when:

  • A workspace is opened
  • A command is executed
  • The chat interface is used

On activation, the extension:

  1. Initializes services and dependencies
  2. Registers commands with VS Code
  3. Registers chat participants
  4. Registers language model tools
  5. Sets up file system watchers

Deactivation​

On deactivation, the extension:

  1. Saves any pending changes
  2. Disposes of file system watchers
  3. Releases resources

Testing Strategy​

The extension uses a combination of:

  • Unit Tests: For testing individual components in isolation
  • Integration Tests: For testing component interactions
  • End-to-End Tests: For testing the extension in a real VS Code environment

Performance Considerations​

Huckleberry is designed to be lightweight and responsive by:

  • Loading task data lazily when needed
  • Processing files asynchronously
  • Using efficient data structures for task management
  • Minimizing filesystem operations

Security Model​

Huckleberry follows these security principles:

  • Local Storage: All task data remains in the user's workspace
  • No External Services: No data is sent to external servers
  • Permission Based: Only accesses files within the workspace
  • Validation: All inputs are validated before processing

Integration Points​

Huckleberry integrates with VS Code through:

  • Command API: For registering and executing commands
  • Chat API: For chat participant integration
  • Language Model API: For AI-assisted task management
  • Workspace API: For file system access and workspace configuration

Contributing​

Before contributing to the extension architecture:

  1. Familiarize yourself with the VS Code Extension API
  2. Follow the project's TypeScript coding standards
  3. Maintain separation of concerns between components
  4. Write unit tests for new functionality
  5. Document public APIs with JSDoc comments

For more details on contributing, see the Development guide.