codescope is a Node.js command-line tool for OpenAI-powered codebase reviews, suggestions, and token estimates.
- Features
- Requirements
- Installation
- Usage
- Configuration
- Validation
- Security and Operations
- Support
- License
- Links
- Focused review and suggestion profiles for architecture, security, reliability, performance, API design, cross-platform compatibility, dependencies, conventions, and release readiness.
- Comprehensive
allreviews that combine implementation, tests, and Markdown into one structured JSON result. - Token and cost estimates, model selection, reasoning-effort controls, and configurable test timeouts.
- Symlink-safe discovery and documented boundaries for intentional behavior.
- Read-only analysis that does not modify the reviewed repository.
- Node.js 26 or newer
- npm
For package consumers, install the published CLI globally or add it to a project:
npm install -g @eliware/codescope
npm install @eliware/codescope
For repository development, install the checkout's dependencies first:
npm ci
Run the CLI locally from this checkout:
node bin/codescope.mjs --help
node bin/codescope.mjs --version
For this development setup, create a live global npm link from the checkout with npm link. The resulting codescope command points directly at the checkout, so changes are available immediately without reinstalling or republishing. Remove it with npm unlink --global @eliware/codescope when no longer needed.
codescope all
codescope review architecture
codescope suggest new-features
codescope --help
See docs/quick-start.md for the complete owner workflow and profile list. See specs/ for the detailed behavior specifications. See NEW_FEATURE_SUGGESTIONS.md for optional future ideas.
The CLI starts with the process environment, then reads only OPENAI_API_TOKEN from ~/.codescope; unrelated dotenv assignments are ignored and a nonblank process value takes precedence. Its dotenv parser accepts optional export, comments, and quoted values. On Unix, group/world-readable configuration files are rejected. A missing or blank token causes a clear error and exit code 3.
npm test
npm run lint
npm run pack
npm run format:check
git diff --check
codescope all is the main comprehensive review and suggestion command. It reports P0–P3 findings, but only unresolved P0 or qualifying P1 issues block the verdict.
Running codescope with no command displays the single help page. Use codescope review all for the comprehensive review, or codescope suggest all for all improvement suggestions across the review categories plus new-features.
Use codescope prompt "your question" for an ad hoc structured-JSON request. It sends the same complete all context, including test results, but sends no review or suggestion tools. The output is parsed as JSON when possible, but has no Codescope schema: its shape is chosen by the model and is not a stable API contract. Invalid or differently shaped provider output is preserved as raw or best-effort output when possible. Optional --effort= and --model= overrides are supported. Use -- before options when the prompt itself begins with a dash, for example codescope prompt --summarize this repository -- --effort=low.
codescope --help is the single help page. A profile may also be followed by --help to display that same page.
Append --usage to either grouped (codescope review all) or direct (codescope all) syntax to include API usage metadata in the final JSON result.
Append --dry-run to prepare a request derived from the review context and ask OpenAI for its estimated input-token count without running a model review. The option reports the selected model and estimated input tokens; combine it with --usage when you want the count under usage as well.
When --usage is enabled, the result includes estimated_cost_usd calculated from the selected model’s input, cached-input, cache-write, output, and long-context rates. --dry-run reports input-token cost only because no output is generated.
Review profiles that include tests use package metadata, implementation files, test files, test results, and Markdown files. They run npm test in the target repository with a 30-second timeout by default. Use --omit-test-results to skip that command or --test-timeout 120 to override the timeout. Suggestion profiles do not run tests.
Use --effort=none|low|medium|high|xhigh|max to override the default reasoning effort (none).
Use --model=gpt-5.6-luna|gpt-5.6-terra|gpt-5.6-sol to override the default model.
The effort benchmark runs npm test first, then runs none, low, medium, and high with bounded parallelism. If the prerequisite test fails, provider runs are skipped. Results and logs are written under benchmark-results/ in the current working directory. OpenAI and Codescope also support xhigh and max, but repository benchmark runs were slow and inconclusive, so both are excluded from the benchmark matrix. Use npm run benchmark:efforts -- --model=gpt-5.6-terra or --model=gpt-5.6-sol to benchmark another supported model; the selected model and its current rates are recorded in summary.json.
Do not place credentials, tokens, .env files, or runtime state in the repository. Codescope is read-only: it analyzes files and writes one completed structured result without modifying the reviewed repository.
Test-output redaction is best-effort and pattern-based; do not treat it as a guarantee that arbitrary secrets are removed. Custom prompt JSON is provider-defined and has no stable schema, so consumers must validate it themselves.
Use codescope review all for release-readiness review.
Open an issue in the GitHub repository or join the Eliware Discord community.
Released under the MIT License.