occ

name	occ
description	Use the occ CLI to explore unfamiliar repositories and office documents efficiently for AI coding tasks. occ ("Office Cloc and Count") emits token-budgeted, JSON-first output for three jobs: workspace reconnaissance with "occ describe" and "occ workspace analyze"; office-document and table triage for DOCX, PDF, XLSX, PPTX, ODT, ODS, and ODP with "occ doc inspect", "occ sheet inspect", "occ slide inspect", and "occ table inspect"; and code exploration for JS/TS, Vue SFC, Python, Go, Rust, Java, C/C++, Kotlin, and other tree-sitter-backed languages with "occ code map", "occ code source", "occ code check", "occ code find", "occ code analyze", "occ code dirtree", "occ code diff", and "occ git diff"/"occ git cochange". It also tracks entities across renames and moves with "occ code entities", "occ code impact", "occ code blame", "occ code log", and "occ code context", and serves the same capabilities to MCP clients with "occ mcp". Reach for it whenever you need to understand a codebase or a set of office files without burning context reading everything, or whenever the user mentions occ.
metadata	{"version":"0.14.0"}
license	MIT

occ — Office Cloc and Count

occ is a read-only analysis CLI that helps an agent understand a repository or a set of office documents cheaply, before spending context reading files in full. It never modifies the target project. It shells out to a vendored scc for code metrics and to git for git context.

Design principles to lean on:

• JSON-first — pass --format json to almost any command for machine-parseable output.
• Token-budgeted — occ code map/pack and occ code diff accept --map-tokens <n> (and the root scan accepts --token-budget <n>). Pair with --tokenizer o200k_base (or cl100k_base) for an exact BPE budget instead of the default heuristic estimate.
• Structural for named symbols/relations, shell for text/config/quick facts — use occ code map, occ code find name, occ code source, and occ code analyze callers when the target is a symbol, call path, class tree, or import relationship. Use rg, grep, or direct file reads for strings, config keys, generated files, and one-off facts.
• Stream large output to a file — for big maps/packs/analyses, add -o <file> and read it back selectively rather than flooding the conversation.

Invocation

occ <command> ...            # if installed globally (npm i -g @cesarandreslopez/occ)
npx @cesarandreslopez/occ <command> ...   # without a global install

Run occ --help or occ <group> --help to see every flag.

Decision table — pick the right command

If you need to…	Start with	Deep reference
Tell what kind of project a directory is	occ describe <dir> --format json	reference/workspace.md
Inventory a whole workspace (code + docs + structure)	occ workspace analyze <dir> --format json -o ws.json	reference/workspace.md
Inventory / cross-reference office docs in a tree	occ workspace documents <dir> --format json	reference/workspace.md
Get document + code metrics for some directories	occ <dirs> --format json --structure	reference/workspace.md
Preflight one DOCX / PDF / ODT before reading it	occ doc inspect <file> --format json	reference/documents.md
Preflight an XLSX workbook (schema, sheets, risks)	occ sheet inspect <file> --format json	reference/documents.md
Preflight a PPTX / ODP deck	occ slide inspect <file> --format json	reference/documents.md
Extract structured table data from a document	occ table inspect <file> --format json	reference/documents.md
Pull entities/keywords (emails, URLs, dates) from a doc	occ doc entities <file>	reference/documents.md
Get oriented in an unfamiliar codebase	occ code map --path . --map-tokens 8000 --tokenizer o200k_base -o map.md	reference/code.md
See an ignore-aware directory tree	occ code dirtree --path . --mode map --format json	reference/code.md
Pull file contents within a token budget	occ code pack --path . --map-tokens 8000 --tokenizer o200k_base -o pack.md	reference/code.md
Find a symbol / concept (best-effort)	occ code find fused "<query>" --format json	reference/code.md
Find an exact symbol by name or type	occ code find name <Name> --format json	reference/code.md
Read one known symbol body	occ code source --node-id <nodeId> --format json	reference/code.md
Hash a symbol body / re-check it later for drift	occ code symbol-hash --file <path> --name <name> --format json	reference/code.md
Check parse syntax after edits	occ code check <file> --format json	reference/code.md
See who calls X / what X calls	occ code analyze callers <fn> · occ code analyze calls <fn>	reference/code.md
Inspect imports / module coupling	occ code analyze deps <target> · occ code analyze coupling <target>	reference/code.md
List / re-check cross-module seams (+ co-change)	occ code seams --since "90 days ago" --format json · occ code seams --resolve <seamKey>	reference/code.md
See which symbols changed in a diff	occ code diff --base <ref> --map-tokens 4096 --format json	reference/code.md
List changed files / bounded patch / churn / co-change	occ git changed · occ git diff --patch --map-tokens 2048 · occ git churn · occ git cochange	reference/git.md

Recommended agent workflows

• Land in a new repo: occ describe . --format json → occ code map --path . --map-tokens 8000 --tokenizer o200k_base -o map.md, read the map, then drill in with occ code find / occ code analyze.
• Read a symbol precisely: occ code map --map-format json → take nodeId from the relevant symbol → occ code source --node-id <nodeId> --format json.
• Find name then read: occ code find name TypeName --format json → if one match, occ code source --node-id <nodeId>; if ambiguous, rerun with --file or --type.
• Trace impact: occ code analyze callers targetFn --format json before broad text search; use candidates and valid node kinds from ambiguous output to refine the query.
• Post-edit syntax gate: run occ code check <changed-file> --format json; it exits nonzero only when valid is false.
• Review a change: occ git changed → occ code diff --base <base> --format json for symbol-level scope → occ git diff --patch --map-tokens 4096 for a bounded patch.
• Estimate blast radius: occ git cochange --target <path> --format json for historically coupled files, then use occ code dirtree --focus-path <dir> --mode map for structural neighborhood context.
• Pin a symbol, detect drift later: occ code symbol-hash --file <path> --name <name> --format json, persist key + bodyHash, later rerun the same query — a changed hash means the body changed even if the symbol moved lines; not_found/ambiguous means the key itself drifted.
• Map the strongest module relationships: occ code seams --since "90 days ago" --format json ranks cross-module seams by co-change lift; persist seamKey and re-check with occ code seams --resolve <seamKey> (a missing answer is drift, not clean).
• Process a document drop: occ <dir> --format json for the inventory → occ doc/sheet/slide inspect --format json per file → occ table inspect to pull tabular data → read only what matters.

Notes

• For the full flag list of every command, read reference/commands.md.
• Languages with first-class code support: JavaScript, TypeScript, Vue SFC, Python, Go, Rust, Java, C/C++, Kotlin, Ruby, PHP, C#, Scala, and Swift.
• --format json is the integration surface; tabular output is for humans.
• Embedding occ in a long-running host (an editor/agent integration that holds an index across turns)? The code graph also has an in-process API — fuzzy searchSymbols, index-to-context projection, changed-focus repo maps, directory trees, git co-change, store freshness probes, and a health().features map to feature-detect across versions. See the programmatic surface in reference/code.md.