---
name: composto
description: Token-efficient JS/TS code investigation. Use when exploring unfamiliar code, tracing symbol usage, understanding a file before editing, debugging cross-file behavior, or gathering context for a review/plan. Trigger phrases include "where is X used", "how does Y work", "what calls this", "before I change this", "understand this module", or any time you'd otherwise read many files to trace a symbol.
---

# composto - targeted JS/TS code context

`composto` digests code relationships (imports, callers, signatures, control flow) and returns focused answers instead of raw file dumps. Use it to avoid reading dozens of files when you only need to understand how a symbol or module behaves.

## When to reach for it

- **Before editing** an unfamiliar file - run `ir <file> L1` to see signatures + imports without reading the whole thing.
- **Debugging** cross-file behavior - use `context --target <symbol>` to get the target raw + neighbors as IR.
- **Tracing impact** of a proposed change - find callers/consumers without grep spam.
- **Pre-planning** - gather context for a plan or refactor without blowing the context window.
- **Pre-review** - surface patterns and callers the diff alone doesn't show.

Skip it for: non-JS/TS code, single-file edits you already understand, or pure config changes.

## Commands

```bash
composto ir <file> <layer>                              # single file, L0-L3
composto context <scope> --target <symbol> --budget N   # targeted, budget-capped
composto context <scope> --budget N                     # smart context across scope
composto scan [path]                                    # codebase health issues
composto trends [path]                                  # health trends
```

## Layers

- **L0** - file list + function locations (skeleton)
- **L1** - adds imports + signatures (default for "understand this")
- **L2** - control flow detail
- **L3** - raw source

Start at L1. Escalate only if L1 doesn't answer the question.

## Scope rules

- **Never run at repo root.** Always pass a feature-scoped path: `packages/providers/notion`, `apps/nokta/app/rpc`, `app/src/components/chat`.
- Match scope to the question. Tracing an RPC call? Scope to `apps/nokta/app/rpc` + `packages/rpc`.
- Use `--budget` (e.g. 4000) to cap tokens on wide scopes.

## Output rules

- Cite `file:line` for every claim you make from composto output.
- Inline only essential signatures in your response - do not dump raw composto output to the user.
- If the target isn't JS/TS or doesn't exist, say so and fall back to Grep/Read.

## Examples

```bash
# Understand a file before editing
composto ir apps/nokta/app/rpc/ChatRpc.ts L1

# Trace a symbol across a feature
composto context packages/providers/notion --target syncPages --budget 4000

# Cross-package: where is SurrealDBService used in RPC handlers?
composto context apps/nokta/app/rpc --target SurrealDBService --budget 3000
```