claude-all-hands 1.0.6 → 1.0.7

package/.claude/envoy/README.md

@@ -21,6 +21,15 @@ envoy <group> --help
 | `tavily extract` | Extract full content from URLs |
 | `xai search` | X/Twitter search for community opinions, alternatives, discussions |
 
+### Context7 (External Documentation)
+
+| Tool | Use Case |
+|------|----------|
+| `context7 search` | Find library by name, returns IDs for context command |
+| `context7 context` | Get documentation for known library (use search first) |
+
+*Flow: search → get library ID → context with query*
+
 ### Vertex (Gemini)
 
 | Tool | Use Case |
@@ -44,6 +53,7 @@ envoy <group> --help
 - Pre-synthesized findings → `perplexity research`
 - Raw sources for processing → `tavily search` → `tavily extract`
 - Community opinions/alternatives → `xai search` (can build on previous findings with `--context`)
+- Library documentation → `context7 search <lib>` → `context7 context <id> <query>`
 
 **Vertex:**
 - Arbitrary Gemini query → `vertex ask`
@@ -63,6 +73,7 @@ These tools read files directly and pass to external LLMs. Claude only receives
 | `TAVILY_API_KEY` | tavily | Tavily API key |
 | `VERTEX_API_KEY` | vertex | Google AI API key (Vertex Express) |
 | `X_AI_API_KEY` | xai | xAI Grok API key |
+| `CONTEXT7_API_KEY` | context7 | Context7 API key (upstash.com) |
 | `ENVOY_TIMEOUT_MS` | optional | Global timeout (default: 120000) |
 
 ## Discovery

package/.claude/envoy/package-lock.json

@@ -9,6 +9,7 @@
       "version": "0.1.0",
       "dependencies": {
         "@google/genai": "^0.14.0",
+        "@upstash/context7-sdk": "^0.3.0",
         "@visheratin/tokenizers-node": "0.1.5",
         "@visheratin/web-ai-node": "^1.4.5",
         "chokidar": "^5.0.0",
@@ -522,6 +523,12 @@
         "pino": "*"
       }
     },
+    "node_modules/@upstash/context7-sdk": {
+      "version": "0.3.0",
+      "resolved": "https://registry.npmjs.org/@upstash/context7-sdk/-/context7-sdk-0.3.0.tgz",
+      "integrity": "sha512-kW5UV49mG9hh30sWP7nLq0mF7YHbTtfWrnm1VsT0UFW8mR6ovlYp7anobUh5qOaewSzraq9o2QyY77KVpI1twg==",
+      "license": "MIT"
+    },
     "node_modules/@visheratin/tokenizers-node": {
       "version": "0.1.5",
       "resolved": "https://registry.npmjs.org/@visheratin/tokenizers-node/-/tokenizers-node-0.1.5.tgz",

package/.claude/envoy/package.json

@@ -12,6 +12,7 @@
   },
   "dependencies": {
     "@google/genai": "^0.14.0",
+    "@upstash/context7-sdk": "^0.3.0",
     "@visheratin/tokenizers-node": "0.1.5",
     "@visheratin/web-ai-node": "^1.4.5",
     "chokidar": "^5.0.0",

package/.claude/envoy/src/cli.ts

@@ -30,6 +30,7 @@ async function getInfo(
         TAVILY_API_KEY: process.env.TAVILY_API_KEY ? "set" : "missing",
         VERTEX_API_KEY: process.env.VERTEX_API_KEY ? "set" : "missing",
         X_AI_API_KEY: process.env.X_AI_API_KEY ? "set" : "missing",
+        CONTEXT7_API_KEY: process.env.CONTEXT7_API_KEY ? "set" : "missing",
       },
       timeout_ms: process.env.ENVOY_TIMEOUT_MS ?? "120000",
     },

package/.claude/envoy/src/commands/context7.ts

@@ -0,0 +1,176 @@
+/**
+ * Context7 API commands - library documentation search and context retrieval.
+ *
+ * Flow: search (find library) → context (get docs for known library)
+ */
+
+import { Command } from "commander";
+import { BaseCommand, type CommandResult } from "./base.js";
+import { Context7, Context7Error, type Library } from "@upstash/context7-sdk";
+
+/** Shared base for Context7 commands - DRY for auth + error handling */
+abstract class Context7BaseCommand extends BaseCommand {
+  protected requireApiKey(): CommandResult | Context7 {
+    const apiKey = process.env.CONTEXT7_API_KEY;
+    if (!apiKey) {
+      return this.error("auth_error", "CONTEXT7_API_KEY not set");
+    }
+    return new Context7({ apiKey });
+  }
+
+  protected async withTimeout<T>(fn: () => Promise<T>): Promise<[T, number]> {
+    const start = performance.now();
+    const timeout = new Promise<never>((_, reject) =>
+      setTimeout(() => reject(new Error("timeout")), this.timeoutMs)
+    );
+    const result = await Promise.race([fn(), timeout]);
+    return [result, Math.round(performance.now() - start)];
+  }
+
+  protected handleError(e: unknown, extraHint?: string): CommandResult {
+    if (e instanceof Context7Error) {
+      return this.error("api_error", e.message, extraHint);
+    }
+    if (e instanceof Error && e.message.includes("timeout")) {
+      return this.error("timeout", `Request timed out after ${this.timeoutMs}ms`);
+    }
+    return this.error("api_error", e instanceof Error ? e.message : String(e));
+  }
+}
+
+class Context7SearchCommand extends Context7BaseCommand {
+  readonly name = "search";
+  readonly description = "Search for libraries by name, returns IDs for context command";
+
+  defineArguments(cmd: Command): void {
+    cmd
+      .argument("<library>", "Library name to search (e.g., react, fastify)")
+      .argument("[query]", "Optional query for relevance ranking")
+      .option("--limit <n>", "Max results (default: 5)", parseInt);
+  }
+
+  async execute(args: Record<string, unknown>): Promise<CommandResult> {
+    const clientOrError = this.requireApiKey();
+    if ("status" in clientOrError) return clientOrError;
+
+    const library = args.library as string;
+    const query = (args.query as string) ?? `How to use ${library}`;
+    const limit = (args.limit as number) ?? 5;
+
+    try {
+      const [libraries, durationMs] = await this.withTimeout(() =>
+        clientOrError.searchLibrary(query, library)
+      );
+
+      if (!Array.isArray(libraries)) {
+        return this.error("api_error", "Unexpected response format from Context7");
+      }
+
+      const results = libraries.slice(0, limit).map((lib: Library) => ({
+        id: lib.id, // Required for context command
+        name: lib.name,
+        description: lib.description,
+        snippets: lib.totalSnippets,
+        trust: lib.trustScore,
+      }));
+
+      return this.success(
+        {
+          query: library,
+          results,
+          usage: results.length > 0
+            ? `Use: envoy context7 context "${results[0].id}" "your question"`
+            : undefined,
+          ...(results.length === 0 && {
+            suggestion: "Library not found. Try different search term or library may not be indexed.",
+          }),
+        },
+        {
+          result_count: results.length,
+          command: "context7 search",
+          duration_ms: durationMs,
+        }
+      );
+    } catch (e) {
+      return this.handleError(e);
+    }
+  }
+}
+
+class Context7ContextCommand extends Context7BaseCommand {
+  readonly name = "context";
+  readonly description = "Get documentation context for a known library (use search first)";
+
+  defineArguments(cmd: Command): void {
+    cmd
+      .argument("<libraryId>", "Library ID from search (e.g., /facebook/react)")
+      .argument("<query>", "What you need docs for (e.g., 'hooks usage')")
+      .option("--text", "Return plain text instead of JSON (better for direct LLM use)");
+  }
+
+  async execute(args: Record<string, unknown>): Promise<CommandResult> {
+    const clientOrError = this.requireApiKey();
+    if ("status" in clientOrError) return clientOrError;
+
+    const libraryId = args.libraryId as string;
+    const query = args.query as string;
+    const useText = args.text as boolean;
+
+    try {
+      if (useText) {
+        // Plain text mode - directly usable in LLM prompts
+        const [content, durationMs] = await this.withTimeout(() =>
+          clientOrError.getContext(query, libraryId, { type: "txt" })
+        );
+
+        return this.success(
+          {
+            library: libraryId,
+            query,
+            content,
+          },
+          {
+            format: "text",
+            command: "context7 context",
+            duration_ms: durationMs,
+          }
+        );
+      }
+
+      // JSON mode - structured docs
+      const [docs, durationMs] = await this.withTimeout(() =>
+        clientOrError.getContext(query, libraryId, { type: "json" })
+      );
+
+      if (!Array.isArray(docs)) {
+        return this.error("api_error", "Unexpected response format from Context7");
+      }
+
+      const documentation = docs.map((doc) => ({
+        title: doc.title,
+        content: doc.content,
+        source: doc.source,
+      }));
+
+      return this.success(
+        {
+          library: libraryId,
+          query,
+          docs: documentation,
+        },
+        {
+          doc_count: documentation.length,
+          command: "context7 context",
+          duration_ms: durationMs,
+        }
+      );
+    } catch (e) {
+      return this.handleError(e, "Ensure libraryId is valid (from search results)");
+    }
+  }
+}
+
+export const COMMANDS = {
+  search: Context7SearchCommand,
+  context: Context7ContextCommand,
+};

package/.claude/skills/research-tools/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: research-tools
-description: External research via envoy commands. Use for "search the web", "research [topic]", "extract URL content", "find sources". Provides Tavily (search/extract), Perplexity (deep research), Grok (X/Twitter). Curator/researcher agents only.
+description: Use for research needs. IE "search the web", "research [topic]", "extract URL content", "find sources". Provides Tavily (search/extract), Perplexity (deep research), Grok (X/Twitter).
 ---
 
 <objective>
-External research capability for curator/researcher agents. Web search, deep research with citations, and real-time social signals via envoy commands.
+External research capability for agents. Web search, deep research with citations, and real-time social signals via envoy commands.
 </objective>
 
 <quick_start>
@@ -17,6 +17,14 @@ envoy tavily search "query"
 
 # Extract URL content
 envoy tavily extract "url1" "url2"
+
+# Library documentation search (Context7)
+envoy context7 search "react"
+envoy context7 search "fastify" "middleware patterns"
+
+# Get library docs for known library (Context7)
+envoy context7 context "/facebook/react" "hooks usage"
+envoy context7 context "/fastify/fastify" "routing" --text
 ```
 </quick_start>
 
@@ -25,6 +33,7 @@ envoy tavily extract "url1" "url2"
 - GitHub content: use `gh` CLI instead of extract
 - All commands return JSON - parse `data.content` or `data.results`
 - Use TODAY's date for time-sensitive queries: `date +%Y-%m-%d`
+- Context7 requires search → context flow (search gives libraryId for context)
 </constraints>
 
 <workflow>
@@ -35,6 +44,7 @@ Clarify: What to learn? What for? Depth needed?
 <step name="choose_tool">
 | Need | Tool | Cost |
 |------|------|------|
+| Library docs (known library) | `context7 search` → `context7 context` | Low |
 | Broad question, synthesis | `perplexity research` | High |
 | Synthesis + real-time validation | `perplexity research --grok-challenge` | Higher |
 | X/Twitter community insights | `xai search` | Medium |
@@ -50,6 +60,12 @@ All tools return JSON. Parse `data.content` or `data.results` for findings.
 <examples>
 <command_reference>
 ```bash
+# Context7 (library documentation)
+envoy context7 search "react"                              # Find react libraries
+envoy context7 search "fastify" "middleware handling"      # Search with query context
+envoy context7 context "/facebook/react" "hooks"           # Get docs (JSON)
+envoy context7 context "/facebook/react" "hooks" --text    # Get docs (plain text)
+
 # Perplexity (deep research)
 envoy perplexity research "query"
 envoy perplexity research "query" --grok-challenge
@@ -72,13 +88,36 @@ gh issue view {number} --repo {owner}/{repo}
 <decision_tree>
 ```
 Need information?
+├─ How does library X work? → context7 search "X" → context7 context "<id>" "question"
+├─ Library docs for codebase dependency? → context7 search → context7 context
 ├─ Know exact URL? → tavily extract
 ├─ Need to find sources? → tavily search → extract promising URLs
 ├─ Tech research for planning? → perplexity research --grok-challenge
+├─ Implementation patterns/best practices? → perplexity research
 └─ Quick answer, no validation? → perplexity research
 ```
 </decision_tree>
 
+<context7_flow>
+Context7 is for library/package documentation. Two-step flow:
+
+1. **Search**: Find the library and get its ID
+```bash
+envoy context7 search "react"
+# Returns: { results: [{ id: "/facebook/react", name: "React", ... }] }
+```
+
+2. **Context**: Get docs for specific questions using the ID
+```bash
+envoy context7 context "/facebook/react" "useState and useEffect"
+# Returns: { docs: [{ title, content, source }] }
+```
+
+**Tips for minimal context usage:**
+- Use `--text` for direct LLM consumption (no JSON parsing)
+- Be specific in query to get relevant docs only
+</context7_flow>
+
 <output_format>
 ```markdown
 ## Research: [Topic]
@@ -100,10 +139,13 @@ Actions based on findings.
 - Skipping scope clarification before research
 - Not parsing JSON response properly
 - Using from non-curator/researcher agents
+- Calling context7 context without searching first (need libraryId)
+- Using context7 for non-library questions (use perplexity instead)
 </anti_patterns>
 
 <success_criteria>
 - JSON response: `status: success` with `data` containing findings
 - Sources/citations included for synthesis queries
 - Content extracted for known URLs
+- Context7: Valid libraryId used in context command
 </success_criteria>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-all-hands",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "CLI for syncing Claude agent configurations to all-hands repository",
   "type": "module",
   "bin": {