ctxpack

Local-first CLI for indexing codebases and retrieving context for agents.

Requirements

• bun>=1.3.0
• ripgrep (rg)
• docker

When to use

• You need to search code from external repos or local folders.
• You need hybrid/text/vector retrieval with optional agent exploration.
• You need direct file access over indexed resources (ls, grep, read, glob).

Example triggers:

"Find where auth middleware is enforced in repo X."
"Trace indexing pipeline and compare text vs vector retrieval."
"Read src/lib/search.ts around score fusion logic."

Bootstrap (fresh project)

ctxpack                # Show setup status
ctxpack setup          # Create ./ctxpack.config.jsonc if missing
ctxpack skill          # Install skill: npx skills add iboughtbed/ctxpack --skill ctxpack
ctxpack connect openai # OAuth flow; or: ctxpack connect --provider <id> ...
ctxpack serve          # Start local server (default http://localhost:8787)

Core workflow

1. Add resources

ctxpack add <url-or-path> [--name <name>] [--type git|local] [--branch <branch>] [--commit <sha>] [--paths <a,b>] [--notes <text>] [--index] [--global]

ctxpack add https://github.com/acme/platform --type git --name acme-platform --index
ctxpack add ./services/api --type local --name api-local --paths src,package.json --index

2. Sync and index

ctxpack sync <name-or-id> [...] [--all] [--global]
ctxpack index <name-or-id> [...] [--all] [--sync] [--global]
ctxpack job <job-id>

ctxpack sync acme-platform
ctxpack index acme-platform --sync   # sync + index in one step
ctxpack job 6b0e3c66-2b27-4d75-9aa6-725a3e9f2b0f

3. Query

ctxpack ask "Where is request-level model config applied?" -r acme-platform
ctxpack search "hybrid score fusion" --raw -r acme-platform --top-k 8
ctxpack search "trace indexing pipeline" --research --async -r acme-platform
ctxpack research-status <job-id>

4. Direct file access

All direct file commands require --resource.

ctxpack ls --resource <name-or-id> [--path <subpath>]
ctxpack grep <pattern> --resource <name-or-id> [--paths a,b] [--case-sensitive]
ctxpack read <filepath> --resource <name-or-id> [--start-line N] [--end-line N]
ctxpack glob <pattern> --resource <name-or-id>

ctxpack ls --resource acme-platform --path apps/honojs/src
ctxpack grep "resolveModelConfig" --resource acme-platform --paths apps/cli/src
ctxpack read apps/cli/src/index.tsx --resource acme-platform --start-line 380 --end-line 470
ctxpack glob "**/*.test.ts" --resource acme-platform

Key options

ctxpack search "oauth fallback behavior" \
  --mode hybrid \
  --alpha 0.35 \
  --top-k 12 \
  --resource acme-platform \
  --stream \
  --verbose

Remote mode

ctxpack remote link --key <api-key> [--endpoint <url>]
ctxpack remote unlink
ctxpack remote add ...
ctxpack remote resources
ctxpack remote ask ...
ctxpack remote rm <resource-id>

Guardrails

• Run ctxpack resources to list available resources before querying.
• Prefer ctxpack ask for general QA; use search when you need explicit control over mode, raw output, or research depth.
• All direct file commands (ls, grep, read, glob) require --resource.
• Indexing into the vector database requires an API key for an embedding model (set via ctxpack connect).