Common Agent Piping Patterns Using Context Hub: A Technical Guide

Context Hub (chub) implements a stateless, JSON-first CLI architecture that enables AI agents to compose complex retrieval workflows by piping search and fetch commands through standard shell utilities like jq and xargs.

Context Hub is an open-source tool developed by Andrew Ng to streamline context management for AI coding agents. The repository implements a pipeline-friendly architecture that allows agents to chain commands without interactive sessions. Mastering these common agent piping patterns using Context Hub enables developers to automate context gathering for Claude Code, Cursor, and other AI assistants.

Core Architecture for Agent Pipelines

Dual-Mode JSON Output

Every Context Hub command supports dual-mode output controlled by the global --json flag. The output() helper in cli/src/lib/output.js (lines 1-14) detects this flag and switches between human-readable text and strict JSON output. This design ensures that agents can parse command results programmatically while maintaining readability for human debugging.

Stateless Command Design

The CLI implements two primary stateless operations for piping. The chub search command, defined in cli/src/commands/search.js (lines 48-63), returns a structured JSON envelope containing {results: [...], total: N, query: "..."}. Each result item includes a stable id field suitable for downstream consumption.

The chub get command in cli/src/commands/get.js (lines 56-64 and 90-97) accepts these identifiers and returns full document objects containing {id, type, content, path, ...} along with optional additionalFiles and annotation fields. This deterministic interface allows agents to fetch content without maintaining session state.

Practical Agent Piping Patterns

Search-to-Fetch Pipeline

The canonical workflow chains search results directly into fetch operations. This pattern extracts the first result ID and retrieves the corresponding document:

# Search for a concept and extract the top result ID

ID=$(chub search "stripe payments" --json | jq -r '.results[0].id')

# Fetch the document and write it locally

chub get "$ID" --lang js -o .context/stripe.md

The search command emits JSON, jq extracts the id field, and get consumes that identifier to fetch the JavaScript variant of the content.

Bulk Retrieval with xargs

For scenarios requiring multiple documents, agents can pipe result arrays through xargs to parallelize fetches:

chub search "stripe" --json \
  | jq -r '.results[:3][].id' \
  | xargs -n1 chub get -o .context/

This pipeline selects the top three results, extracts their IDs, and invokes chub get once per ID. Each invocation writes its own <id>.md file into the output directory.

Batch Processing Multiple IDs

The get command accepts multiple space-separated identifiers in a single invocation, reducing process overhead:

chub get openai/chat-api stripe/payments -o .context/

This command retrieves both documents in one execution, automatically looping through the provided IDs and writing each result to <id>.md in the target directory.

Installing Skills for Claude Code

Agents can install complete skills by combining the --full flag with specific output directories:

# Install a single skill file

chub get pw-community/login-flows -o .claude/skills/login-flows/SKILL.md

# Copy the complete skill directory including helpers

chub get pw-community/login-flows --full -o .claude/skills/login-flows/

The --full flag retrieves companion files alongside the main SKILL.md, placing the entire capability where Claude Code can discover it automatically.

Advanced Retrieval Patterns

Discovering Additional Files

The JSON output from get includes an additionalFiles field listing auxiliary assets. Agents can inspect this metadata before fetching specific references:

# List available auxiliary files

chub get acme/widgets --json | jq '.additionalFiles'

# Retrieve a specific reference file

chub get acme/widgets --file references/advanced.md

This pattern enables selective fetching of large reference materials only when needed.

Handling Annotations

Per-document agent notes stored in cli/src/lib/annotations.js are emitted as the annotation field in JSON mode. These annotations provide machine-readable metadata that agents can use to filter or prioritize content without parsing the full text.

Summary

• Dual-mode output in cli/src/lib/output.js enables seamless switching between human-readable and JSON formats via the --json flag.
• Search command (cli/src/commands/search.js) returns stable IDs in a structured envelope, while get command (cli/src/commands/get.js) resolves those IDs to full content with optional additionalFiles.
• Stateless pipelines allow agents to chain chub search with jq and xargs to automate complex retrieval workflows without session management.
• Batch operations support multiple IDs in a single get invocation, and the --full flag enables complete skill installation for agent frameworks like Claude Code.

Frequently Asked Questions

How does Context Hub handle JSON output for agent pipelines?

Context Hub implements a dual-mode output system in cli/src/lib/output.js that detects the global --json flag. When present, the output() helper switches from human-readable text to strict JSON output, allowing agents to parse command results programmatically using standard tools like jq.

Can Context Hub fetch multiple documents in a single command?

Yes. The chub get command accepts multiple space-separated IDs in a single invocation, as implemented in cli/src/commands/get.js. Additionally, you can pipe multiple IDs from jq or xargs to batch retrieve documents efficiently without launching separate processes for each fetch.

What shell utilities work best with Context Hub piping?

Standard Unix utilities pair effectively with Context Hub: jq for parsing and extracting fields from JSON output, xargs for executing chub get on multiple IDs, and standard shell pipes (|) to chain chub search with subsequent commands. These tools leverage the line-oriented JSON structure documented in docs/design.md.

How do I install a Context Hub skill into Claude Code?

Use the chub get command with the --full flag to retrieve the complete skill directory including companion files, then output directly to Claude Code's skills folder. For example: chub get pw-community/login-flows --full -o .claude/skills/login-flows/. This places the SKILL.md and any helpers where Claude Code can discover them automatically.

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