Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

CLI worker pools default to cpus-1 each with no user-facing cap — index builds can saturate many-core machines

Open
  • Is something wrong?
#2,527 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
45/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
javascript, node.js
Domain
cli, performance

Research direction

The report names lib/dist/extraction/parse-pool.js, lib/dist/mcp/query-pool.js, lib/dist/resolution/resolver-pool.js, the README, and CLI help for index and init. Start by reading how those pools resolve their sizes and where configuration and verbose startup output are handled. Done means the existing environment knobs are documented and a user-facing thread limit bounds aggregate worker usage, with resolved pool sizes shown at startup.

Written by the indexing model from the issue text.

Description

Title: CLI worker pools default to cpus-1 each with no user-facing cap — index builds can saturate many-core machines

Type: enhancement (missing resource-control knob) + documentation gap

Environment

  • macOS, Apple Silicon (darwin-arm64), 18 logical CPUs, 47 GB RAM
  • @colbymchenry/codegraph v1.6.1, global npm install (~/.codegraph/versions/v1.6.1, node CLI)

Observed behavior

  • A co-installed VS Code extension's native engine saturated my whole machine during a full index (load average 38 on 18 cores, ~1700 %CPU in ps). I reported that to its own maintainers separately — but on inspecting the CLI's source I found the same unbounded-pool pattern here, and throttled proactively. I have not isolated a CLI-only runaway reproduction; this report is about the configuration gap, not a claim of a CLI crash.

Findings (from the installed v1.6.1 source)

Three independently-sized worker pools, each defaulting to cpus - 1:

  1. lib/dist/extraction/parse-pool.js — resolveParsePoolSize(envVal, cpuCount) returns Math.max(1, Math.min(cpuCount - 1, DEFAULT_PARSE_POOL_CAP)) → 17 parse workers on an 18-core machine.
  2. lib/dist/mcp/query-pool.js — resolvePoolSize(envVal, cpuCount) returns Math.max(1, Math.min(cpuCount - 1, MAX_POOL_SIZE)) → 17 query workers.
  3. lib/dist/resolution/resolver-pool.js — ResolverPool.resolvePoolSize sizes its own pool from os.availableParallelism().

Because these run concurrently during index / init, the pools can collectively occupy every core, leaving no headroom — the machine is unresponsive for the duration of the build.

Working but undiscoverable knobs — these exist in code but are not documented anywhere I could find:

Env var Effect Where
CODEGRAPH_PARSE_POOL_SIZE caps the parse pool extraction/parse-pool.js
CODEGRAPH_QUERY_POOL_SIZE caps the query pool (0 = disable, serve reads in-process) mcp/query-pool.js
CODEGRAPH_PARALLEL_RESOLVE_MIN minimum refs before the resolver pool engages resolution/resolver-pool.js
CODEGRAPH_NO_PARALLEL_RESOLVE=1 kill switch, sequential resolution resolution/resolver-pool.js

There is no equivalent in user-facing config: codegraph index --help and codegraph init --help expose no thread/worker option, and codegraph.json (project config) has no thread setting.

Requests

  1. Document the env knobs above in the README — they are the only cap that exists today, and I only found them by grepping lib/dist.
  2. Add a first-class limit — e.g. maxThreads in codegraph.json and/or a --threads flag on index/init/sync — applied across all pools together (parse + query + resolve + embedding), so one number bounds total engine CPU.
  3. Default to leaving headroom. cpus - 1 per pool is reasonable for one pool; with three pools running concurrently the sum can hit the full core count. Either size pools from a budget (total ≤ ½ or ¾ of cores) or cap the aggregate.
  4. --verbose already prints worker lifecycle/memory info — please also print the resolved pool sizes at startup so users can confirm the cap took effect.

Current workaround (verified working) — export CODEGRAPH_PARSE_POOL_SIZE=5 and CODEGRAPH_QUERY_POOL_SIZE=4 (rayon/tokio env vars do not apply to this Node CLI; those are only for the native Rust engine build).

Dominant language
C
Stars
73.2k
Forks
4.7k
Avg merge
2h 16m
Merged PRs (30d)
423

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from colbymchenry/codegraph

All issues in colbymchenry/codegraph

Similar issues

More C issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.