---
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". 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.12.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

```bash
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](reference/workspace.md) |
| Inventory a whole workspace (code + docs + structure)   | `occ workspace analyze <dir> --format json -o ws.json`                                              | [reference/workspace.md](reference/workspace.md) |
| Inventory / cross-reference office docs in a tree       | `occ workspace documents <dir> --format json`                                                       | [reference/workspace.md](reference/workspace.md) |
| Get document + code metrics for some directories        | `occ <dirs> --format json --structure`                                                              | [reference/workspace.md](reference/workspace.md) |
| Preflight one DOCX / PDF / ODT before reading it        | `occ doc inspect <file> --format json`                                                              | [reference/documents.md](reference/documents.md) |
| Preflight an XLSX workbook (schema, sheets, risks)      | `occ sheet inspect <file> --format json`                                                            | [reference/documents.md](reference/documents.md) |
| Preflight a PPTX / ODP deck                             | `occ slide inspect <file> --format json`                                                            | [reference/documents.md](reference/documents.md) |
| Extract structured table data from a document           | `occ table inspect <file> --format json`                                                            | [reference/documents.md](reference/documents.md) |
| Pull entities/keywords (emails, URLs, dates) from a doc | `occ doc entities <file>`                                                                           | [reference/documents.md](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](reference/code.md)           |
| See an ignore-aware directory tree                      | `occ code dirtree --path . --mode map --format json`                                                | [reference/code.md](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](reference/code.md)           |
| Find a symbol / concept (best-effort)                   | `occ code find fused "<query>" --format json`                                                       | [reference/code.md](reference/code.md)           |
| Find an exact symbol by name or type                    | `occ code find name <Name> --format json`                                                           | [reference/code.md](reference/code.md)           |
| Read one known symbol body                              | `occ code source --node-id <nodeId> --format json`                                                  | [reference/code.md](reference/code.md)           |
| Check parse syntax after edits                          | `occ code check <file> --format json`                                                               | [reference/code.md](reference/code.md)           |
| See who calls X / what X calls                          | `occ code analyze callers <fn>` · `occ code analyze calls <fn>`                                     | [reference/code.md](reference/code.md)           |
| Inspect imports / module coupling                       | `occ code analyze deps <target>` · `occ code analyze coupling <target>`                             | [reference/code.md](reference/code.md)           |
| See which _symbols_ changed in a diff                   | `occ code diff --base <ref> --map-tokens 4096 --format json`                                        | [reference/code.md](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](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.
- **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](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](reference/code.md).
