Skip to main content

​
Synopsis

Search across all thread content and return matching lines with file paths and line numbers.

​
Usage

watercooler search <query> [options]

​
Arguments

​
query
string
required
Search query string (case-insensitive text search)

​
Options

​
--threads-dir
string
Threads directory path. Defaults to ./watercooler or $WATERCOOLER_DIR.

​
Examples

​
Basic text search

watercooler search "authentication flow"
Output: 
/path/to/watercooler/feature-auth.md:15: Implemented OAuth2 authentication flow with PKCE.
/path/to/watercooler/feature-auth.md:42: The authentication flow handles edge cases including token refresh.
/path/to/watercooler/api-redesign.md:8: Authentication flow will be integrated in phase 2.

​
Search for specific term

watercooler search "TODO"
Output: 
/path/to/watercooler/feature-auth.md:23: TODO: Add rate limiting to login endpoint
/path/to/watercooler/api-redesign.md:56: TODO: Document error codes

​
Search for decision records

watercooler search "Decision:"
Output: 
/path/to/watercooler/feature-auth.md:12: Decision: Use OAuth2 with PKCE for authentication
/path/to/watercooler/api-redesign.md:34: Decision: REST API with GraphQL for complex queries

​
Search in custom directory

watercooler search "bug" --threads-dir ~/projects/myapp/threads

​
Case-sensitive patterns

# Search is case-insensitive, but you can pipe to grep for case-sensitive
watercooler search "oauth" | grep "OAuth"

​
Output Format

Results are formatted similar to grep output: 
<file path>:<line number>: <matching line>
FieldDescription
File pathAbsolute path to the thread file
Line numberLine number where match was found
Matching lineComplete line containing the search query

​
Search Behavior

  • Case-insensitive: Searches ignore case by default
  • Full-text: Searches entire file content including frontmatter, titles, and bodies
  • Multi-file: Searches all thread files in the directory
  • Plain text: No regex support (plain string matching)

​
Common Use Cases

​
Find recent decisions

watercooler search "decided" | tail -10

​
Find all PRs mentioned

watercooler search "PR #"

​
Find blockers

watercooler search "blocked"
watercooler search "waiting for"

​
Find specific agent mentions

watercooler search "Agent: Claude"

​
Audit trail for specific feature

watercooler search "user authentication"

​
Integration with Shell Tools

​
Count occurrences

watercooler search "OAuth" | wc -l

​
Get unique file matches

watercooler search "authentication" | cut -d: -f1 | sort -u

​
Search and open in editor

watercooler search "TODO" | head -1 | cut -d: -f1 | xargs code

​
Filter by date (if timestamps in content)

watercooler search "2024-03-15"

​
Performance Considerations

  • Search is linear across all files in the threads directory
  • For large thread collections (>1000 files), consider using dedicated indexing
  • The command reads all files; performance scales with total content size
For more complex search needs, consider:
  1. MCP tools: Use watercooler_search MCP tool for semantic search capabilities
  2. Smart query: Use watercooler_smart_query for natural language questions
  3. External tools: Combine with ripgrep or ag for regex support:
rg -i "oauth.*token" $(watercooler list --open-only | cut -f6)
  • list - List threads
  • search - MCP search tool with semantic capabilities
  • smart-query - Natural language query (MCP)

Build docs developers (and LLMs) love

Get started for freeTalk to us