grepai

name	grepai
description	Workspace-first GrepAI search workflow for programming agents (v0.34+): project-scoped semantic search, token-efficient output, and reliable fallbacks.

GrepAI Workspace Search (Agent-Focused)

Use this skill when you need to find code by intent in one or more projects inside a GrepAI workspace.

Scope and Priority

• Primary tool for intent-based code search: grepai search.
• Primary context model: --workspace <name> with optional --project <name>.
• Use exact-text tools only for exact literals, symbol names, or imports.

Semantic intent examples:

• "where authentication is enforced"
• "how retries are handled"
• "where config is loaded and validated"

Exact-text examples (do not use semantic search):

• exact function name
• exact env var key
• exact import statement

Current CLI Facts (v0.34.0)

• grepai search supports --workspace <name>.
• grepai search supports repeatable --project <name> (stringArray).
• grepai search supports --path <prefix> to constrain results.
• grepai search supports --limit <n> for result count.
• grepai search supports --json and --toon output modes.
• --compact requires --json or --toon.
• grepai workspace provides multi-project management.
• Workspace storage backends are postgres or qdrant (not GOB).

Agent Defaults

Use these defaults unless the user asks otherwise:

• Output mode: --toon --compact for token efficiency.
• Scope: always include --workspace; add --project when known.
• Query language: English.
• Query style: describe behaviour and intent, not symbol spelling.

Standard Workflow

1. Verify GrepAI availability and workspace context.

   grepai version
   grepai workspace status Projects
   

2. Ensure the workspace is indexed and current.

   grepai workspace status Projects
   

   If workspace metadata or index data is missing, report it and ask the user to run workspace/index setup tasks.

3. Run an initial scoped semantic search.

   grepai search --workspace Projects --project "$(get-project)" \
     "request validation and auth checks" --toon --compact --limit 8
   

4. Refine scope and phrasing iteratively.

   # Multi-project search (repeat --project)
   grepai search --workspace Projects --project api --project web \
     "JWT refresh token rotation" --toon --compact --limit 10
   
   # Restrict to path prefix inside indexed project(s)
   grepai search --workspace Projects --project api --path src/auth \
     "authorization failure handling" --toon --compact --limit 10
   

5. Open top results for full context, then optionally use trace.

   grepai trace callers "ValidateToken" \
     --workspace Projects --project api --toon
   grepai trace callees "HandleLogin" \
     --workspace Projects --project api --toon
   

Query Quality Rules

Good query examples:

• user authentication middleware and token validation
• database retry logic with backoff
• startup config loading from environment

Bad query examples:

• auth
• function
• exact symbol names (use exact-text search for those)

Guidelines:

• 3 to 7 words is usually best.
• Prefer behaviour and outcomes over syntax.

Output Mode Selection

• --toon --compact: default for AI-agent loops.
• --json --compact: when downstream tooling needs JSON parsing.
• Human-readable output: manual debugging only.

Troubleshooting and Recovery

1. Workspace missing (no grepai project found style errors).

   Report the missing workspace and ask the user to create/add projects. Do not run workspace create, workspace add, workspace remove, or workspace delete as part of this skill.

2. Empty index (files/chunks = 0) or stale results.

   grepai workspace status Projects
   

   If the index is empty or stale, report it and ask the user to run indexing.

3. Watcher uncertainty in background mode.

   Report watcher/daemon issues and ask the user to restart watcher services.

4. Embedder/provider failures.

   Verify provider endpoint and model. If using OpenAI provider, verify API key presence.

Fallback Policy

If GrepAI is unavailable or still returns unusable results after setup checks:

1. State the failure mode clearly.
2. Fall back to exact/file-pattern tooling to keep progress.
3. Keep follow-up file reads tightly scoped.

Quick Command Set

# Agent baseline (workspace + single project)
grepai search --workspace Projects --project "$(get-project)" \
  "input validation and error mapping" --toon --compact --limit 8

# Cross-project search (subset)
grepai search --workspace Projects --project core --project cli \
  "configuration merge precedence" --toon --compact --limit 10

# JSON compact for scriptable pipelines
grepai search --workspace Projects --project "$(get-project)" \
  "retry policy implementation" --json --compact --limit 5

Keywords

grepai, workspace search, semantic code search, project-scoped search, toon, compact, agent workflow, token-efficient search, cross-project exploration