Coding Agents — Daily Workflow¶

The day-to-day cheat sheet for using the Prism CLI from inside an AI coding agent (Claude Code, Cursor, Codex, Windsurf, Devin, Antigravity). Replace Grep/Glob with prism for any code question, run two mandatory triggers before editing or writing helpers, and steer your agent by editing its rules file (AGENTS.md / CLAUDE.md / .cursorrules). Setup is a one-time job — covered in coding-agents-setup.md; this guide is what comes after.

When to read this¶

• You finished Coding Agents — Setup and your IDE can now reach the gateway, and you want to know which command to use for which task.
• Your agent keeps reaching for Grep/Glob inside an indexed repo and you want to steer it toward prism via its rules file.
• You're about to edit an existing function or write a new helper and want to know the right pre-flight check.
• You're dispatching sub-agents (Claude Code's Agent tool, Cursor's background agents) and they keep falling back to Grep on their first tool call.
• You're hitting weird symptoms — wrong-tenant results, stale answers, results from the wrong repo — and want the diagnostic commands.

Substitution table — Grep/Glob → prism¶

This is the rule: never Grep for code inside an indexed repo. prism search is a superset of grep (it finds both exact and semantic matches in one call), and the symbol-aware commands (def, find-refs, body, outline) return structured results in ~200 tokens instead of dumping file contents.

Run prism --help to see the full surface — it changes faster than this guide.

Common commands by task¶

Exploring an unfamiliar area¶

Start with the module map. It ranks files by PageRank, so the top entries are the load-bearing ones.

prism module-map apps/prism/prism/storage
prism module-map apps/prism-console-api
prism map apps/prism                     # alias

Read the top 1–3 files, not all of them. Combine with prism def for the most-mentioned symbols to build a mental model in ~2–4k tokens (vs. ~20k tokens of half-relevant file content via Read/Grep).

Searching for code by behavior¶

prism search "rate limit retry"
prism search "JWT RS256 validation"
prism search "tenant schema isolation" --limit 5
prism grep "ingestion handler"           # alias of search

Tips: describe behavior, not file names. Use the codebase's vocabulary (tenant schema, MCP tool, ingestion handler). If results are weak, rephrase from a different angle — two prism search calls beat one Grep that misses semantic matches.

For broad exploration, run multiple searches in parallel (separate Bash invocations in one message) and synthesise the results:

prism search "file ingestion handler entry point"
prism search "embedding generation pipeline"
prism search "pgvector chunk insertion"

Finding all usages of a symbol¶

prism find-refs "User.save"
prism find-refs "MyClass" --kind callers
prism refs "PgVectorStorageEngine.search"     # alias

find-refs is the right tool for rename/signature-change refactors — its callers field is overlay-aware (overlay caveats covered in branches-and-overlays.md), so refs to your unpushed code show up correctly.

Jumping to a definition or reading a body¶

prism def "handle_search_code"           # file + line + signature, ~200 tokens
prism body "PgVectorStorageEngine.search" # full source in `source_text`
prism outline apps/prism/prism/gateway/mcp_tools.py

outline is cheap — call it before Read on a large file to decide whether you need the whole file or just one function.

Tracing imports¶

prism deps apps/prism/prism/gateway/mcp_tools.py

Files by name pattern¶

prism find matches glob/path patterns over the indexed file list:

prism find "**/*.test.tsx"
prism find "apps/prism/prism/storage/*.py"

For purely-local filename hunting (build artifacts, logs), Glob is still the right tool.

Multi-repo tenants¶

Single-repo tenants: scoping is automatic. Multi-repo tenants: if results look like they're from the wrong repo, pass --repo "Owner/Name":

prism list-repos
prism search "JWT validation" --repo "Fintama/swisper_prism"
prism find-refs "User.save"  --repo "Fintama/helvetiq"

You can also set a per-shell default:

export PRISM_DEFAULT_REPO="Fintama/swisper_prism"

Resolution order: --repo flag > PRISM_DEFAULT_REPO env var > git remote auto-detect.

Health / diagnostics¶

prism ping       # gateway reachable + token accepted (yes/no)
prism whoami     # which tenant_id the token resolves to
prism doctor     # full diagnostic: auth, env vars, git context, overlay

whoami is the fastest way to catch a wrong-tenant token (common after switching accounts). doctor is the heavy diagnostic — covers everything ping and whoami do, plus env-var checks, git context resolution, and the overlay section (current branch, resolved overlay, diff file count, whether git fetch ran). Run prism doctor --no-fetch to skip the pre-resolution fetch.

Edit-time triggers (mandatory)¶

Two triggers are non-optional. Skipping them is the most expensive failure mode in agent-assisted code — duplicated helpers and broken callers — and both costs go away in one round-trip.

Before editing existing code → prism prepare-edit¶

prism prepare-edit "User.save"
prism prepare-edit "PgVectorStorageEngine.search"
prism prepare-edit "handle_search_code"

Returns, in one JSON response: full source (source_text), all callers grouped by file (callers / symbol_references), nearby tests with the specific test functions that exercise the code (tests), Cursor rules that apply to the file (rules), and warnings about unsafe patterns (warnings).

The warnings field is the highest-value part. Read each warning before planning the edit:

A warning is a heads-up, not a stop sign — but every warning needs a deliberate decision recorded in your plan, not a silent bypass.

Skip prepare-edit only for: typo/wording fixes to comments, trivial formatting (whitespace, import sort), test-only edits inside the test file you're already looking at, files outside the indexed repo. Don't skip for any edit that changes a function body (even "one-line" changes — they may cross hidden invariants captured in warnings), adding parameters, changing return types, or renames (use find-refs first).

For rename / signature change, run both — prepare-edit for warnings and role; find-refs for completeness:

prism prepare-edit "User.save"
prism find-refs    "User.save"

Before writing a new helper → prism check¶

prism check "validate JWT signature against JWKS"
prism check "retry HTTP request with exponential backoff"
prism check "convert snake_case to camelCase"
prism check "parse ISO 8601 datetime with timezone"

Returns existing symbols ranked by semantic similarity to your intent. Interpret the score:

• High (>0.8) + matching signature → reuse it. Import and call.
• Medium (0.6–0.8) → read the source via prism body "<Symbol>" to confirm fit. Often a near-miss is good enough with a tiny adapter.
• Low (<0.6) + no obvious match → write the helper. Place it next to similar code (the results show where similar utilities live).

If you find yourself thinking "I'll just write a quick helper for X" — stop and run prism check "X" first. Helper duplication (parallel parse_iso_datetime / parse_timestamp / to_datetime functions that diverge over time) is the most common quality regression in agent-assisted code. check prevents it in one round-trip.

The full edit loop¶

1. prism check "<intent>"          # only if writing NEW helper
2. prism prepare-edit "<Symbol>"   # before editing existing code
   ↓
3. Edit / Write                    # make the change
   ↓
4. prism find-refs "<Symbol>"      # confirm no caller slipped past

Editing AGENTS.md / CLAUDE.md / .cursorrules to steer your agent¶

Your IDE's agent reads a rules file at session start: AGENTS.md (Codex, Devin, generic), CLAUDE.md (Claude Code), .cursorrules or .cursor/rules/*.mdc (Cursor). That file is the most reliable way to make the substitution table above stick. Without it, the agent will reach for Grep on every fresh session no matter how many times you've corrected it in chat.

The minimum content to paste into the project's rules file:

## MANDATORY: Prism CLI for code navigation

This repo is indexed by Prism. Use `prism` instead of Grep/Glob for any
code question. Glob is allowed ONLY for filename patterns (e.g. `**/*.test.tsx`).
Read is fine when you already know the exact path.

| Old habit | Use this |
|---|---|
| Grep "symbol"          | prism grep "symbol"          |
| Grep "User.save"       | prism find-refs "User.save"  |
| Find a definition      | prism def "User.save"        |
| Read a function body   | prism body "User.save"       |
| Symbols in a file      | prism outline <path>         |
| Architecture overview  | prism module-map <path>      |
| Module imports         | prism deps <path>            |

## Edit-time triggers (mandatory)

- Before writing a new helper / utility / wrapper: `prism check "<intent>"`.
- Before editing an existing function/class/method: `prism prepare-edit "<Symbol>"`.
- Before renaming/changing signature of an exported symbol: `prism find-refs "<Symbol>"`.

Run `prism --help` for the full command surface.

Phrase the triggers as imperatives, not advisories. Agents will rationalize skipping advisory steps ("the plan already has the info") when given an out. The pattern that works in practice:

"MANDATORY (do not skip): before any Edit/Write to existing code, run prism prepare-edit "<Symbol>". Paste its output into your reasoning. Skipping with reasoning like 'plan has the info' is not acceptable — prism's callers + warnings fields surface things the plan can't (new callers added since the plan was written, public-API drift, missing tests)."

For team-wide enforcement, see the strict-mode hooks at .claude/snippets/prism-strict-hooks.json (off by default — they hard-block Grep/Glob and can break legitimate uses like reading logs outside the indexed repo).

Where the rules file lives per IDE¶

If your IDE isn't listed, check its docs — most modern coding agents converge on AGENTS.md as the lingua franca. See coding-agents-setup.md for per-IDE setup detail.

Sub-agent dispatch — the propagation rule¶

When you dispatch a sub-agent (Claude Code's Agent tool, Cursor's background agents, parallel-fan-out patterns), the sub-agent starts fresh. It does NOT see the parent conversation. It inherits the project rules file, but terse dispatch prompts produce sub-agents that reach for Grep on their first tool call regardless of what the rules file says.

The fix: every dispatch prompt for code work must include a one-liner orientation plus the specific prism commands fit for the task. Minimum content:

"Use the prism CLI for code navigation. Run prism --help to see commands. Prefer prism over Grep/Glob for any code search inside this repo."

Plus the task-specific commands. Examples by sub-agent type:

Exploration / research sub-agent:

[your task description]

Use the `prism` CLI for code navigation:
- Start with `prism module-map <relevant-path>` to orient.
- Use `prism search "<query>"` instead of Grep for code search.
- Use `prism find-refs "<Symbol>"` to find usages.
- Use `prism def "<Symbol>"` for go-to-definition (~200 tokens).

Avoid Grep/Glob for code search — they miss semantic matches.

Implementation sub-agent (lane-executor, etc.):

[your task description]

## Prism CLI usage (MANDATORY — not advisory)

- Before editing any existing symbol: `prism prepare-edit "<Symbol>"`.
  Paste its output (warnings, callers, nearby tests) into your reasoning.
  Skipping with reasoning like "plan has the info" is not acceptable.
- Before writing any new helper / utility / wrapper: `prism check "<intent>"`.
  If it returns a high-scoring match, reuse instead of duplicating.
- After non-trivial edits: `prism find-refs "<Symbol>"` to confirm no caller
  was missed.

Use `prism search` / `prism find-refs` instead of Grep for code search inside
this repo.

Code-review sub-agent:

[your task description]

Use `prism find-refs "<Symbol>"` to verify all callers of a changed symbol were updated.
Use `prism search "<query>"` (not Grep) to find related code.
Use `prism module-map <path>` to understand the area being reviewed.

Parallel sub-agents: when dispatching N agents in one message, include the propagation paragraph in every prompt. Sub-agents don't share state — one learning prism doesn't help the others.

FAQ¶

Q: When should I use prism grep vs prism find-refs vs prism search?¶

A: prism grep is an alias of prism search — same command, two names. Use search/grep when looking for code by behavior or freeform string. Use find-refs when you have an exact symbol name and want all usages grouped by kind (call / import / def / assignment). For exact-symbol queries, find-refs is more precise; for fuzzy or behavioral queries, search.

Q: My agent ignores the rules file and keeps using Grep. What do I do?¶

A: Three escalations: (1) phrase the rule as an imperative ("MANDATORY: use prism"), not an advisory; (2) put the substitution table directly in the rules file so the agent has the answer at hand; (3) for hard enforcement, paste .claude/snippets/prism-strict-hooks.json into .claude/settings.json under hooks.PreToolUse — this hard-blocks Grep/Glob tool calls. See "Editing AGENTS.md / CLAUDE.md / .cursorrules" above.

Q: I changed a function locally, but prism body returns the old code. Why?¶

A: The source_text field is not yet overlay-aware (Tier-2 fix in flight) — same applies to outline, def, search, and prepare-edit's source_text field. The response sets overlay_consumed: false to make this explicit. Workaround: for the file you've already edited locally, prefer Read <file> over the source_text field. The callers, tests, rules, and warnings fields are overlay-aware and remain trustworthy — only the body of the symbol-under-edit may lag. find-refs is fully overlay-aware. See branches-and-overlays.md for full overlay coverage.

Q: How do I dispatch a sub-agent without it falling back to Grep on the first call?¶

A: Include a one-liner in the dispatch prompt: "Use the prism CLI for code navigation. Run prism --help to see commands. Prefer prism over Grep/Glob for any code search inside this repo." Then list the specific prism commands for the task. The sub-agent doesn't see your conversation history, so the dispatch prompt is the only place to install this discipline. See "Sub-agent dispatch — the propagation rule" above.

Q: I'm about to write parse_iso_datetime — do I really need to run prism check first?¶

A: Yes. parse_iso_datetime is exactly the duplicate-helper pattern check was built to prevent. It costs one round-trip and saves you from adding the third near-identical datetime parser to a codebase that already has two. If the search returns nothing similar, write the helper — but check first, every time. This is the cheapest discipline in the workflow.

Q: prism prepare-edit returns found: false for a symbol I just wrote on a feature branch. What now?¶

A: The branch overlay can be >1 hour behind during active branch work, so prepare-edit can't see symbols introduced on the feature branch yet. The fallback is immediate, not lazy: Read /absolute/path/to/the_file.py. Don't retry prepare-edit in a wait-loop — each retry costs a round-trip and rarely succeeds during an active session. For symbols on main (e.g., extending an existing function), prepare-edit works fine even if the overlay is still indexing — the default-branch index is independent. See branches-and-overlays.md for the full overlay lifecycle.

Q: How do I know if results are stale?¶

A: Every response carries indexed_at and index_age_seconds. Under 3600s (1 hour) → fresh, trust it. Over 3600s → the index may be lagging recent collaborator pushes; auto-overlay covers find-refs for your local edits, but for body/outline/def/search you may want to Read files you've edited. Re-trigger indexing from the Console if results lag collaborator pushes consistently.

Q: I get results from the wrong repo. How do I scope to one?¶

A: Pass --repo "Owner/Name" per command, or set PRISM_DEFAULT_REPO=Owner/Name in your shell. Run prism list-repos to see which repos this tenant has indexed. Resolution order: --repo flag > PRISM_DEFAULT_REPO env var > git remote auto-detect.

Related¶

• Coding Agents — Setup — install the CLI, configure PRISM_TOKEN / PRISM_BASE_URL, wire up your IDE's rules file. Do this first; everything in this guide assumes it's done.
• Branches & Overlays — when to register a long-lived feature-branch overlay, how the CLI auto-resolves the nearest overlay, what resolved_overlay_branch and _overlay mean in tool responses, the force-push caveat.
• Glossary — canonical definitions for overlay, MCP, gateway, PageRank, Token, and other terms used throughout this collection.