jsrc

Imported from joadpe/jsrc (SKILL.md). Install upstream with npx skills add joadpe/jsrc. Copyright stays with the author.

jsrc — Java Source Code Navigator for Agents

What is jsrc?

A CLI tool that lets you navigate and inspect large Java codebases without reading source files. It parses code structure (classes, methods, annotations, inheritance, dependencies) and returns compact JSON optimized for LLM context windows.

For small/local agents (4-8K context): Use jsrc skill --budget tiny or jsrc skill --budget small to get a slim command guide optimized for your budget. This SKILL.md provides comprehensive documentation for all use cases.

When to use jsrc

• You need to understand a Java codebase structure without reading every file
• You need to find a specific class, method, or annotation across thousands of files
• You need to trace call chains or understand class hierarchies
• You need to check dependencies or detect code smells

When NOT to use jsrc

• Don't read .java files directly if jsrc can answer your question
• Don't parse jsrc text output — always use --json
• Don't skip --index on large codebases (>100 files) — without it, full-parse commands take minutes

Required setup

# Java 21+ and Maven required
java -version
mvn --version

# Build jsrc
cd /path/to/jsrc
mvn clean compile

Critical workflow

Step 1: Index the codebase (do this FIRST)

cd /path/to/codebase
jsrc index

This parses all Java files and saves a persistent index to .jsrc/index.bin. Only needed once — subsequent runs auto-refresh changed files.

• First run on 8,000 files: ~14 minutes
• Incremental (after changes): <2 seconds
• All query commands use the index automatically

Step 2: Orient yourself

cd /path/to/codebase
jsrc overview --json

Returns: total files, classes, interfaces, methods, package list. ~77ms with index.

Step 3: Query as needed

Always use --json. All commands work with or without explicit source root (defaults to .).

Commands reference

Global flags

• --json — machine-readable JSON output (always use this)
• --metrics — append execution metrics to stderr
• --signature-only — compact method output (1 line per method)
• --fields name,packageName — limit JSON to specific fields (saves tokens)
• --config path — use custom config file instead of .jsrc.yaml
• --budget <profile> — budget profile: tiny|small|standard (default: standard)
• --limit N — maximum items in output lists
• --no-budget-meta — omit _budget metadata from JSON output

Budget Profiles for Small/Local Agents

For models with limited context (4-8K tokens), use budget profiles to enforce hard output limits:

# Get slim agent guide for your budget (recommended)
jsrc skill --budget tiny       # ~2KB guide for 4K context
jsrc skill --budget small      # ~3KB guide for 8K context
jsrc skill --budget tiny --json  # Machine-readable version

# Set budget via flag (highest priority)
jsrc --budget tiny overview --json

# Or via environment variable
export JSRC_BUDGET=small

# Or in .jsrc.yaml
# budget: tiny

Profiles:

• tiny: ~4K context, 10-item limit, core commands only (index, overview, mini, read, scope, callers, validate)
• small: ~8K context, 30-item limit, most commands except heavy ones (context, call-chain, dump)
• standard: No restrictions (default)

Behavior:

• Tiny/small force --json output automatically
• Tiny degrades: summary → runs as mini, read Class → denies with suggestion to read specific method
• Denied commands exit with code 2 + structured error JSON
• All object-shaped output includes _budget metadata showing applied limits (array outputs preserve contract)

Quick start for tiny budget:

export JSRC_BUDGET=tiny
jsrc skill --json              # Get slim command guide for tiny budget
jsrc overview --json
jsrc mini ClassName --json     # summary auto-degrades to this under tiny
jsrc read ClassName.methodName --json  # whole-class reads denied under tiny

Exit codes

• 0 — OK, results found
• 1 — OK, but no results matched
• 2 — Bad arguments (invalid input, unknown command)
• 3 — I/O error

Invariants

1. Always use --json — text output is for humans, not agents
2. Run --index first on any new codebase — without it, navigation commands parse on-the-fly (slow)
3. Index auto-refreshes — if files changed since indexing, jsrc re-parses only those files automatically
4. stdout = data, stderr = diagnostics — parse stdout only
5. --signature-only saves tokens — use it when you don't need full method metadata
6. --metrics reports timing — use it to verify index is working (should be <1s)

Output format (JSON)

All JSON output is compact (no pretty-print) to minimize tokens.

overview

{"totalFiles":8323,"totalClasses":13335,"totalInterfaces":163,"totalMethods":12680,"totalPackages":124,"packages":["com.app","com.app.service"]}

classes

[{"name":"OrderService","packageName":"com.app","qualifiedName":"com.app.OrderService","startLine":10,"endLine":50,"isInterface":false,"isAbstract":false,"methodCount":5}]

summary ClassName

{"name":"OrderService","packageName":"com.app","qualifiedName":"com.app.OrderService","file":"src/main/java/com/app/OrderService.java","modifiers":["public"],"isInterface":false,"methods":[{"name":"create","signature":"public Order create(String name)","startLine":15,"returnType":"Order"}]}

search

[{"name":"process","className":"Service","file":"Service.java","startLine":10,"endLine":25,"signature":"public void process(String input)","returnType":"void","modifiers":["public"],"parameters":[{"type":"String","name":"input"}]}]

metrics (stderr)

{"command":"overview","elapsedMs":77,"filesScanned":8323,"resultsFound":13335}

Performance (with index)

Without index, full-parse commands on 8,323 files take 12+ minutes.

Playbooks — What command to use when

Decision tree

What do you need to do?
│
├─ FIX A BUG (have stacktrace/error)
│  1. jsrc read Class.method --json     ← read the failing method
│  2. jsrc mini Class --json            ← understand the class (compact)
│  3. jsrc impact Class.method --json   ← who else is affected?
│  4. jsrc validate Class.fix --json    ← verify fix before writing
│
├─ ADD/EXTEND A FEATURE
│  1. jsrc scope "keywords" --json      ← find WHERE the feature lives
│  2. jsrc mini TopMatch --json         ← understand the class (compact)
│  3. jsrc read Class.existingMethod --json  ← see the PATTERN to follow
│  4. jsrc related Class --json         ← what else to read?
│  5. jsrc checklist Class.method --json ← plan the change
│  6. jsrc validate Class.newMethod --json  ← verify names before writing
│
├─ UNDERSTAND A CODEBASE (new to you)
│  1. jsrc overview --json              ← how big? how many packages?
│  2. jsrc classes --json               ← list all types
│  3. jsrc scope "keyword" --json       ← find area of interest
│  4. jsrc mini Class --json            ← quick summary of key classes
│  5. jsrc related Class --json         ← explore neighborhood
│
├─ REVIEW/AUDIT CODE
│  1. jsrc smells Class --json          ← code smells
│  2. jsrc deps Class --json            ← dependency analysis
│  3. jsrc hierarchy Class --json       ← inheritance tree
│  4. jsrc check --json                 ← architecture rule violations
│
├─ CHANGE A METHOD SIGNATURE
│  1. jsrc impact Class.method --json   ← how many callers?
│  2. jsrc callers Class.method --json  ← exact caller list
│  3. jsrc checklist Class.method --json ← step-by-step plan
│
└─ VERIFY BEFORE WRITING CODE
   1. jsrc validate Class.method --json ← does it exist?
   2. jsrc type-check Class.method --json ← return type correct?

Token budget guide (for small models)

Rules for small models (≤8K)

For 4K context (use --budget tiny or export JSRC_BUDGET=tiny):

1. NEVER cat a Java file — use jsrc read Class.method for specific methods
2. NEVER jsrc summary — use jsrc mini instead (10× smaller)
3. NEVER jsrc context, call-chain, dump, tour, or map — denied under tiny budget
4. ALWAYS start with jsrc scope when you don't know where code is
5. ALWAYS validate method names before generating code
6. Read methods, not classes — read Class.method not read Class
7. All list outputs automatically limited to 10 items

For 8K context (use --budget small or export JSRC_BUDGET=small):

1. Can use jsrc summary for moderate-sized classes
2. List outputs limited to 30 items
3. Heavy commands still denied (context, call-chain, etc.)
4. Use jsrc skill --json to see available commands for your budget

AI Agent Commands (new)

Commands designed specifically for AI agent workflows:

# Anti-hallucination: verify method exists, suggest closest if not
jsrc validate Class.method --json
jsrc validate Class.method(Type1,Type2) --json

# Ultra-compact summary (<500 chars) for small context windows
jsrc mini ClassName --json

# Related classes ranked by coupling score
jsrc related ClassName --json

# Change impact: transitive callers + risk level
jsrc impact Class.method --json

# Task planner: find relevant classes by keywords
jsrc scope "keyword1 keyword2" --json

# Step-by-step change guide
jsrc checklist Class.method --json

# Return type verification
jsrc type-check Class.method --json

Configuration (.jsrc.yaml)

Optional. Place in project root:

sourceRoots:
  - src/main/java
  - src/generated/java
excludes:
  - "**/test/**"
  - "**/generated/**"
javaVersion: "21"

With config, source root argument is optional — jsrc uses sourceRoots[0] or pwd.