How to Add an Annotation in Context Hub: Command Syntax and Examples

To add an annotation in Context Hub, run chub annotate <id> "<note>" where <id> is the entry identifier and <note> is your annotation text.

Context Hub, developed by Andrew Ng's team at andrewyng/context-hub, is an open-source CLI tool for managing contextual documents and AI skills. Adding annotations allows you to attach persistent local notes to any entry, ensuring important context survives across sessions and appears automatically in future chub get calls.

The chub annotate Command Syntax

The primary interface for adding annotations is the chub annotate command, registered in cli/src/commands/annotate.js.

Basic Usage

To attach a note to a specific entry:

chub annotate <id> "<note>"

For example, to annotate the Stripe API entry:

chub annotate stripe/api "Needs raw body for webhook verification"

Command Flags

The annotate command supports several flags defined in the command registration:

• --clear – Removes the annotation for the specified ID
• --list – Displays all stored annotations
• --json – Outputs results in JSON format instead of human-readable text

How Annotations Work Under the Hood

When you run chub annotate, the system executes a precise workflow involving several core library modules.

Command Registration and Parsing

In cli/src/commands/annotate.js, the registerAnnotateCommand function handles argument parsing and flag detection. It validates the input and delegates to the appropriate library functions based on whether --clear, --list, or a standard annotation is requested.

Annotation Storage Logic

The cli/src/lib/annotations.js file implements the CRUD operations:

• writeAnnotation(id, note) – Creates or overwrites the JSON file for the given ID
• readAnnotation(id) – Retrieves the annotation data
• clearAnnotation(id) – Deletes the annotation file
• listAnnotations() – Returns all stored annotations

Configuration and File Paths

The cli/src/lib/config.js module provides getChubDir(), which resolves to the user's ~/.chub directory. Annotations are stored as individual JSON files inside ~/.chub/annotations/, with filenames derived from the entry ID.

Output Formatting

After operations complete, cli/src/lib/output.js formats the results. The output() function handles the --json flag to switch between terminal-friendly text and structured JSON output.

Practical Examples

Adding Your First Annotation

Attach a reminder to a specific API documentation entry:

chub annotate openai/api-v2 "Check rate limit headers before production deploy"

Clearing an Annotation

Remove a note when it is no longer relevant:

chub annotate openai/api-v2 --clear

Listing All Annotations

Review all your stored notes across entries:

chub annotate --list

Programmatic Access

You can interact with annotations directly in JavaScript:

import { readAnnotation, writeAnnotation } from '@aisuite/chub/cli/src/lib/annotations.js';

// Write an annotation
writeAnnotation('stripe/api', 'Verify webhook signatures');

// Read it back
const ann = readAnnotation('stripe/api');
console.log(ann.note);  // "Verify webhook signatures"
console.log(ann.updatedAt);  // ISO timestamp

Summary

• Use chub annotate <id> "<note>" to attach persistent notes to any Context Hub entry.
• Annotations are stored as JSON files in ~/.chub/annotations/ and managed via cli/src/lib/annotations.js.
• The annotate command supports --clear, --list, and --json flags for full CRUD operations.
• All annotations automatically appear in future chub get calls for the annotated entry.

Frequently Asked Questions

Where are annotations stored locally?

Annotations are stored as individual JSON files in the ~/.chub/annotations/ directory. Each file corresponds to a single entry ID and contains the note text and timestamp. This path is determined by the getChubDir() function in cli/src/lib/config.js.

Can I overwrite an existing annotation?

Yes. Running chub annotate <id> "<new-note>" on an ID that already has an annotation will overwrite the previous JSON file with the new content and updated timestamp. The writeAnnotation function in cli/src/lib/annotations.js handles this automatically.

How do I view annotations when retrieving an entry?

When you run chub get <id>, any existing annotation for that ID automatically appears in the output. The retrieval logic checks the ~/.chub/annotations/ directory for a matching file and displays the note alongside the entry content.

Is there a way to export annotations?

While there is no dedicated export command, you can use chub annotate --list --json to output all annotations as structured JSON to stdout, which you can redirect to a file for backup or processing. The --json flag triggers the JSON formatter in cli/src/lib/output.js.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}