Out-of-code Insights

Out-of-code Insights is a Visual Studio Code extension that allows you to add annotations, comments, and notes without modifying your source files. It is ideal for avoiding clutter in your code with temporary comments or making the code unnecessarily heavy.

🌐 Connect with Me

You can find me on these platforms:

We’d love to hear your thoughts, feedback, and ideas! Feel free to join the conversation on GitHub Discussions and connect with the community.

Why use Out-of-code Insights?

• Non-intrusive annotations: Add comments without altering the source code, keeping your files clean and organized.
• Optimized for code reviews: Facilitate team communication by adding comments directly on the relevant lines.
• Avoid code clutter: Maintain clarity and readability of your code by avoiding unnecessary comments.
• Annotations on all file types: Add annotations to any file in your project, including source code, Markdown, JSON, XML, text, etc.
• Intelligent change tracking: Annotations automatically follow file changes as long as edits are made within Visual Studio Code.
• Personalization: Adapt the extension to your needs with various configuration options.
• Threaded discussions: Reply to annotations to create threads and enhance collaboration.
• Advanced annotation management: Move, filter, sort, and navigate annotations with ease.
• Batch Edit Annotations: Modify multiple annotations simultaneously to save time and effort.
• Keyword Search: Quickly find annotations by searching for specific keywords.
• Filter by Severity: Categorize and view annotations based on their severity levels.
• Show AI Suggestion: Display simulated suggestions from AI.
• Show Github Copilot Suggestion: Display simulated suggestions from GitHub Copilot.
• Auto-Resolve Stale Annotations: Automatically handle annotations that are no longer relevant or outdated.

(add in v1.0.3 - Activity bar)

(PNG binary file)

Key Features

• Add annotations: Insert comments or notes on specific lines without modifying the source file, regardless of file type.
• View and manage annotations: See all your annotations in a dedicated panel, modify, delete, or reply to them.
• Toggle annotation visibility: Enable or disable annotation visibility in the editor.
• Move annotations: Drag annotations directly within the editor. Annotations follow their assigned lines; simply position above or below a line to move it.
• CodeLens integration: Manage annotations directly from the editor with CodeLens integration.
• Filter and sort annotations: Filter and sort annotations in the panel for efficient management.
• Export and import: Export your annotations to share or back them up, and import them into other projects.
• Batch Edit Annotations: Modify multiple annotations at once to streamline your workflow.
• Keyword Search: Quickly locate annotations by searching for specific terms or phrases.
• Filter by Severity: Organize annotations based on their severity to prioritize tasks.
• Show AI Suggestion: View simulated suggestions from AI to enhance your annotations.
• Show Copilot Suggestion: View simulated GitHub Copilot suggestions within your annotations for enhanced productivity.
• Auto-Resolve Stale Annotations: Automatically resolve annotations that are no longer relevant, keeping your workspace clean.

Installation

1. Open Visual Studio Code.
2. Access the Extensions Manager:
   • Click the Extensions icon in the sidebar.
   • Or use the shortcut Ctrl+Shift+X (Cmd+Shift+X on Mac).
3. Search for the extension:
   • Type "Out-of-code Insights" in the search bar.
4. Install the extension:
   • Click "Install" next to the appropriate result.
5. Restart Visual Studio Code (if required).

Usage

Adding an Annotation

• Using the context menu:
  • Right-click on the line where you want to add an annotation.
  • Select Add Annotation.
• Using keyboard shortcuts:
  • Place your cursor on the desired line.
  • Press Ctrl+Alt+A (Windows/Linux) or Cmd+Alt+A (Mac).

Editing or Deleting an Annotation

• Using the context menu:
  • Right-click on the line containing the annotation.
  • Select Edit Annotation or Delete Annotation.
• Using keyboard shortcuts:
  • Edit an annotation:
    • Press Ctrl+Alt+E (Windows/Linux) or Cmd+Alt+E (Mac).
  • Delete an annotation:
    • Press Ctrl+Alt+D (Windows/Linux) or Cmd+Alt+D (Mac).

Viewing and Managing Annotations

• Open the annotations panel:
  • Use the View Annotations command from the Command Palette (Ctrl+Shift+P or Cmd+Shift+P).
  • Or click the annotations icon in the status bar.
• Toggle annotation visibility:
  • Use the Toggle Annotation Visibility command to make annotations visible or hidden in the editor.
  • Shortcut: Ctrl+Alt+T (Windows/Linux) or Cmd+Alt+T (Mac).

Moving Annotations

• Move an annotation within the editor:
  • Position your cursor on the line above or below the annotation.
  • Use the Move Annotation Up or Move Annotation Down commands available in the context menu or annotations panel.
  • Annotations automatically follow their lines when you modify code within Visual Studio Code.

Replying to an Annotation

• Add a comment to an existing annotation:
  • In the annotations panel, select the annotation you want to reply to.
  • Click Reply to add a comment and start a thread.

Filtering and Sorting Annotations

• Filter annotations:
  • Use the filtering options in the annotations panel to display annotations by file or author.
• Sort annotations:
  • Sort annotations by date, number of comments, etc., for efficient management.

Batch Editing Annotations

• Modify multiple annotations:
  • Open the annotations panel.
  • Select the annotations you wish to edit.
  • Use the Batch Edit Annotations command to apply changes to all selected annotations simultaneously.

Keyword Search

• Search for annotations by keyword:
  • Use the Keyword Search feature in the annotations panel.
  • Enter the desired keyword to filter annotations containing that term.

Filter by Severity

• Categorize annotations:
  • Use the Filter by Severity option to display annotations based on their assigned severity levels (e.g., info, warning, error).

Show AI Suggestion

• View simulated suggestions:
  • Use the Show AI Suggestion command to display simulated suggestions from AI within your annotations. Select a line in the code editor, right-click to bring up the context menu. In the "out-of-code-insight" submenu, select the "AI Suggest Annotation" option, and it will provide an annotation for that line.
  • If you want to disabled or enabled AI Suggest, you can do it in the settings.
  • Press Ctrl+Shift+P to open the Command Palette.
    • Type the name of the command (for example, Update OpenAI Key or Reset OpenAI Key).
  • Important: Ensure you have an OpenAI API key configured to access this feature.

Show Copilot Suggestion

• View simulated suggestions:
  • Use the Show Copilot Suggestion command to display simulated GitHub Copilot suggestions within your annotations. Select @out-of-code-insights to see the suggestions.

Auto-Resolve Stale Annotations

• Automatic management:
  • Enable Auto-Resolve Stale Annotations to automatically handle annotations that are outdated or no longer relevant.

Configure the annotations.json File Path

• Set the path to the annotations file:
  • Access the extension settings.
  • Enter the desired path in the Path to annotations file field. Include the file name (e.g., annotations.json), if you not specify the file name, the extension will use the default name (annotations.json).
  • Per default, the annotations file is located in the .out-of-code-insights/annotations.json directory of your project.
  • If you change the path, ensure that the directory exists and is accessible. All project using the extension will use this path after the change, else the extension will use the default path in each project.

Exporting and Importing Annotations

• Export Annotations to JSON

  • Use the Export Annotations to JSON command to export all annotations to a JSON file.
  • Command: annotations.exportJSON

• Import Annotations from JSON

  • Use the Import Annotations from JSON command to import annotations from a JSON file.
  • Command: annotations.importJSON

Managing Annotations

• If annotations are not visible, you can use the Toggle Annotation Visibility command to show or hide them. CTRL+ALT+T (Windows/Linux) or CMD+ALT+T (Mac) is the shortcut for this command. A conflict with another extension can cause this issue, like Github Copilot Chat extension.

• Toggle Annotation Pin

  • Pin or unpin annotations to keep important notes visible.
  • Command: annotations.pinToggle

• Convert Annotation to GitHub Issue

  • Convert your annotations into GitHub issues for better tracking and management.
  • Command: annotations.convertToIssue

Enhanced Features

• Show Copilot Suggestion (Simulated)

  • Display simulated GitHub Copilot suggestions within your annotations to enhance productivity.
  • Command: annotations.showCopilotSuggestion

• Auto-Resolve Stale Annotations

  • Automatically resolve annotations that are outdated or no longer relevant.
  • Command: annotations.autoResolveStale

• Batch Edit Annotations in File

  • Modify multiple annotations simultaneously within a file to streamline your workflow.
  • Command: annotations.batchEdit

• Keyword Search in Annotations

  • Quickly locate annotations by searching for specific keywords.
  • Command: annotations.keywordSearch

• Filter Annotations by Severity

  • Organize annotations based on their severity levels for better prioritization.
  • Command: annotations.filterBySeverity

Important Notes

• File modification:
  • To ensure annotations track file changes correctly, always modify files within Visual Studio Code. External modifications may disrupt annotation tracking.
• Compatibility with all file types:
  • You can add annotations to any file in your project, including source code, Markdown, JSON, XML, text, etc.
• Annotation storage:
  • Annotations are stored in a JSON file named annotations.json, located by default in the .out-of-code-insights directory of your project.
  • Include this file in your version control repository if you want to preserve annotation history and share comments with your team.
• OpenAI API Key Management:
  • The extension uses your OpenAI API key for AI-powered features.
  • The key is securely stored using VS Code's Secret Storage, ensuring that your key is protected and only accessible by this extension.
  • To remove or update your OpenAI API key:
    1. Open the Command Palette:
       • Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (Mac).
    2. Type: Developer: Clear Extension Secret Storage.
    3. Select Your Extension:
       • In the list that appears, select Out-of-Code Insights.
    • This will clear all secrets stored by the extension, including your OpenAI API key.

Configuration

Customize the extension according to your needs by modifying the available settings:

• Username (annotation.username): Specifies the name that will appear as the annotation author.
  • Important: Update the username to properly identify authors.
• Enable annotations (annotation.enableAnnotations): Toggles annotation visibility in the editor.
• Custom colors (annotation.colors):
  • Customize annotation colors, highlight background, and comment borders for both light and dark themes.
• Enable CodeLens (annotation.codelens.enable): Toggles CodeLens integration.
• Show commands in CodeLens (annotation.codelens.showCommands): Toggles command display in CodeLens.
• Batch Edit Annotations (annotation.batchEdit): Enable or disable the batch editing feature.
• Keyword Search (annotation.keywordSearch): Configure settings for keyword-based annotation searching.
• Filter by Severity (annotation.filterBySeverity): Set preferences for severity-based annotation filtering.
• Advanced settings:
  • Change detection delay (annotation.debounceDelay)
  • Maximum annotations per file (annotation.maxAnnotationsPerFile)

Access settings:

1. Go to File > Preferences > Settings (or Code > Preferences > Settings on Mac).
2. Search for annotation to view all available settings.

Keyboard Shortcuts

Action	Shortcut (Windows/Linux)	Shortcut (Mac)
Add an annotation	Ctrl+Alt+A	Cmd+Alt+A
Edit an annotation	Ctrl+Alt+E	Cmd+Alt+E
Delete an annotation	Ctrl+Alt+D	Cmd+Alt+D
Show annotations panel	Ctrl+Alt+S	Cmd+Alt+S
Toggle annotation visibility	Ctrl+Alt+T	Cmd+Alt+T
Batch Edit Annotations	Ctrl+Alt+B	Cmd+Alt+B
Keyword Search	Ctrl+Alt+K	Cmd+Alt+K
Filter by Severity	Ctrl+Alt+F	Cmd+Alt+F
Show AI Suggestion	Ctrl+Alt+G	Cmd+Alt+G
Auto-Resolve Stale Annotations	Ctrl+Alt+R	Cmd+Alt+R

Below is the complete list of commands (available via Ctrl+Shift+P) in a tabular format, suitable for inclusion in your README. Each command can be run by opening the Command Palette (Ctrl+Shift+P) and typing its name:

Action	Command	Description
Add Annotation	annotations.add	Adds a new annotation to the current line of code.
Reply to Annotation	annotations.reply	Adds a reply/comment to an existing annotation.
Clear All Annotations	annotations.clearAll	Removes all annotations from the project.
Delete Annotation	annotations.delete	Deletes the annotation on the current line.
Edit Annotation	annotations.edit	Edits the annotation on the current line.
Toggle Annotations Display	annotations.toggleDisplay	Shows or hides all annotations in the editor.
Navigate to Annotation	annotations.navigate	Jumps directly to the specified annotation.
Export Annotations to JSON	annotations.exportJSON	Exports all annotations to a JSON file.
Import Annotations from JSON	annotations.importJSON	Imports annotations from a JSON file.
Toggle Annotation Pin	annotations.pinToggle	Pins or unpins the annotation at the current line.
Batch Edit Annotations in File	annotations.batchEdit	Updates all annotations within the current file at once.
Keyword Search in Annotations	annotations.keywordSearch	Searches annotations by a keyword.
AI Suggest Annotation	annotations.aiSuggest	Requests an AI-generated annotation for the current line of code.
Move Annotation Up	annotations.moveUp	Moves the annotation on the current line up by one line.
Move Annotation Down	annotations.moveDown	Moves the annotation on the current line down by one line.
Show Annotations Panel	annotations.show	Opens the annotations panel to view and manage all annotations.
Update OpenAI Key	annotations.updateOpenAIKey	Prompts you to enter a new OpenAI API key.
Reset OpenAI Key	annotations.resetOpenAIKey	Clears the stored OpenAI API key, requiring a new key on the next AI call.

Additional Features

• Renamed or deleted files: Automatically updates or removes annotations when files are renamed or deleted.
• Export and import annotations: Share or back up annotations, and import them into other projects.
• Status bar integration: Displays the number of annotations in the status bar for quick access.
• Navigate to annotations: Quickly jump to a specific annotation from the annotations panel.
• Advanced customization: Adjust the extension’s behavior to suit your preferences.
• Batch Edit Annotations: Efficiently manage multiple annotations with batch editing capabilities.
• Keyword Search: Enhance your workflow by searching annotations using specific keywords.
• Filter by Severity: Organize annotations based on their severity levels for better prioritization.
• Show AI Suggestion: Benefit from simulated suggestions to improve your annotation process.
• Auto-Resolve Stale Annotations: Maintain a clean workspace by automatically resolving outdated annotations.

Tree View and Activity Bar

The Out-of-Code Insights extension includes a Tree View and an Activity Bar for efficient annotation management. Here is a detailed description of these features:

Tree View

The Tree View allows you to visualize and manage annotations in a structured manner. It is accessible via the Activity Bar in Visual Studio Code.

• Grouping by file: Annotations are grouped by file, making navigation and management easier.

Example Usage

• Annotation display: Each file contains a list of annotations with details such as the author, date, and annotation message.
• Annotation actions: You can navigate to an annotation, edit it, delete it, or add comments directly from the Tree View.

Activity Bar

The Activity Bar adds a dedicated icon for Out-of-Code Insights in the Visual Studio Code sidebar. Clicking this icon opens the Tree View of annotations.

• Quick access: The Activity Bar provides quick access to all annotations in your project.
• Centralized management: All annotations are centralized in a single view, making them easier to manage and navigate.

Example Usage

1. Open the Tree View:

   • Click the Out-of-Code Insights icon in the Activity Bar.
   • The Tree View opens, displaying annotations grouped by file.

2. Navigate to an annotation:

   • Click on an annotation in the Tree View.
   • The code editor automatically positions itself on the line of the selected annotation.

3. Edit or delete an annotation:

   • Right-click on an annotation in the Tree View.
   • Select Edit or Delete from the context menu.

4. Add a comment:

   • Select an annotation in the Tree View.
   • Click Reply to add a comment to the annotation.

These features enhance annotation management by providing an overview and management tools directly integrated into the Visual Studio Code interface.

Contribution

Contributions are welcome! Feel free to suggest improvements, report issues, or submit pull requests.

License

See the LICENSE file for more information.

Conclusion

Out-of-code Insights helps you manage comments and notes in your projects without cluttering your source code. By providing a platform for non-intrusive annotations, precise change tracking, and seamless integration into your development environment, this extension is a practical tool for developers and teams looking to improve collaboration and productivity.

---

Try Out-of-code Insights today and streamline your workflow without overloading your code!