Skip to content

GETTING_STARTED.md

Latest commit

 

History

History
142 lines (99 loc) · 10.9 KB

GETTING_STARTED.md

File metadata and controls

142 lines (99 loc) · 10.9 KB
Raw

Install and run codexqa

简体中文

HTML documentation for search engines: openqa.cn. This page is the GitHub source.

Install one skill at a time on Cursor, Claude Code, Codex, or OpenClaw. This page walks codexqa-defect-analyzer because it has a CLI you can smoke-test. The same command also takes --skill codexqa-skill-router, --skill codexqa-code-analyzer, --skill codexqa-change-analysis, --skill codexqa-code-wiki, --skill codexqa-rootcause-analyzer, --skill codexqa-code-reviewer, --skill codexqa-requirement-analyzer, --skill codexqa-testcase-generator, --skill codexqa-testdata-generator, and --skill codexqa-jev-browser. Prefer codexqa-skill-router when you are unsure which worker to install — it can match and fetch workers on demand. codexqa-code-analyzer, codexqa-change-analysis, codexqa-code-wiki, codexqa-rootcause-analyzer, and codexqa-code-reviewer use the separate codexqa symbol-graph CLI; codexqa-defect-analyzer is Python-orchestrated and also uses that CLI for live graphs; codexqa-skill-router needs Python 3.10+ for discover/ensure; codexqa-jev-browser runs its own TypeScript CLI on Playwright Chromium.

What you give each skill is different (FAQ). What a finished report looks like: README · Overview of all skills.

Requirements

Use Node.js, npm/npx, Git, and a coding agent able to read skill files and run commands. codexqa-code-analyzer, codexqa-change-analysis, and codexqa-code-wiki require Node.js 18 or newer; codexqa-jev-browser requires Node.js 20 or newer. codexqa-testcase-generator requires Python 3.10+ (invoke via that skill's scripts/tcg-python). The codexqa-defect-analyzer Python pipeline is exercised with Python 3.11 locally and in CI:

python3 --version   # 3.10+; 3.11 recommended (codexqa-defect-analyzer / codexqa-testcase-generator)
node --version      # for CodexQA CLI / other skills
npx --version
git --version

codexqa-defect-analyzer may install optional SAST tools via scripts/install_sast_tools.sh / ensure_tools.py. Live graph analysis needs @openqa-cn/codexqa on PATH. Packaging tests for other skills may still require Bash, rsync, zip, and unzip. See data and network behavior.

Install from GitHub

npx skills add openqa-cn/codexqa --skill codexqa-defect-analyzer

Choose an agent interactively. Default scope is the current project. For Codex across projects:

npx skills add openqa-cn/codexqa --skill codexqa-defect-analyzer --agent codex --global

Use --copy if you prefer copies to agent-directory symlinks. Installation locations are managed by the third-party skills installer; use its output to locate the installed skill. Installation does not prove that a complete analysis works on that agent.

Verify from a local checkout

Before pushing, inspect locally available skills without installing:

npx skills add . --list

To install this checkout, run from the repository root:

npx skills add . --skill codexqa-defect-analyzer --agent codex --copy

For a CLI-only smoke check, no model or private platform is needed:

python3 skills/codexqa-defect-analyzer/scripts/run_scan.py --help
(cd skills/codexqa-defect-analyzer && npm test)

npm test runs the Python pipeline and policy-fixture suites (prefers Python 3.11). It does not run a live agent Stage1/Stage2 scan. Run the boundary-case example for a known-good and seeded-defect pair (fixture verification only).

Start the agent workflow

Open a new session after installation. Provide a local repo path, PR/diff intent, upload, or paste. Example request:

Use codexqa-defect-analyzer to scan my repository at /abs/path/to/repo for this PR. Run Agent LLM Detection (Stage1/Stage2) and return report_scan.json findings ordered P0–P3.

Expect deterministic collect + agent handoff, then report_scan.json / .md / .html. Inspect tooling_status.missing when scanners are absent. Keep findings under human review.

Update and remove

Use the third-party installer's help to inspect its current options:

npx skills --help
npx skills list
npx skills update
npx skills remove codexqa-defect-analyzer --agent codex

For global installations add --global where supported. Back up configuration and task data before updating or removing an installed directory. The default skill stores data inside its installation; updates must not be used as a backup mechanism.

Other published skills

npx skills add openqa-cn/codexqa --skill codexqa-code-analyzer
npx skills add openqa-cn/codexqa --skill codexqa-change-analysis
npx skills add openqa-cn/codexqa --skill codexqa-code-wiki
npm install -g @openqa-cn/codexqa

npx skills add openqa-cn/codexqa --skill codexqa-skill-router
npx skills add openqa-cn/codexqa --skill codexqa-rootcause-analyzer
npx skills add openqa-cn/codexqa --skill codexqa-code-reviewer
npx skills add openqa-cn/codexqa --skill codexqa-requirement-analyzer
npx skills add openqa-cn/codexqa --skill codexqa-testcase-generator
npx skills add openqa-cn/codexqa --skill codexqa-testdata-generator
npx skills add openqa-cn/codexqa --skill codexqa-jev-browser

The codexqa-code-analyzer, codexqa-change-analysis, codexqa-code-wiki, codexqa-rootcause-analyzer, codexqa-code-reviewer, codexqa-defect-analyzer, and codexqa-skill-router Skills are published in this repository. @openqa-cn/codexqa is the separately distributed, closed-source local code-analysis engine; indexes and sessions live under ~/.codexqa/. See codexqa-code-analyzer known limitations, codexqa-change-analysis known limitations, codexqa-code-wiki known limitations, codexqa-rootcause-analyzer known limitations, codexqa-code-reviewer known limitations, codexqa-defect-analyzer known limitations, and codexqa-skill-router known limitations.

For a model-free codexqa-code-analyzer / codexqa-code-wiki smoke check, index a local checkout and inspect its summary:

codexqa --help
codexqa index /path/to/repo
codexqa stats /path/to/repo
codexqa wiki inputs /path/to/repo --kind architecture --limit 8

--help should list the CLI commands. A successful stats call should report indexed files, symbols, and languages. For change review, rebuild the index with --diff-base <ref>; without a diff base, changed symbols remain default and there is no change set to review. wiki inputs should print community / digest JSON without calling a model.

After install, start a new agent session and point it at the skill. Inputs differ:

  • codexqa-skill-router needs a user request to route (and Python 3.10+). It matches the bundled/live catalog and can run ensure_skill.py to fetch a worker beside the router. See its README.
  • codexqa-code-analyzer needs a local repository. For change review, index it with a baseline such as origin/main; indexes live under ~/.codexqa/. See its README.
  • codexqa-change-analysis needs a local repository and one git baseline (for example origin/main). It writes an HTML change-impact report at the repo root and adds new test files for uncovered points; existing tests are not edited. See its README.
  • codexqa-code-wiki needs a local repository; its brief step indexes it. It writes a one-page HTML architecture wiki; it does not review a change. See its README.
  • codexqa-rootcause-analyzer needs exception evidence (stack / log / dump) plus a git URL, local dir, file, or already-open workspace. See its README.
  • codexqa-defect-analyzer needs a diff, repo, upload, or paste for a code-risk scan. See its README.
  • codexqa-code-reviewer needs a local checkout, codexqa + jq on PATH, and (for PR mode) --diff-base. See codexqa-code-reviewer README.
  • codexqa-requirement-analyzer needs requirement documents, not a repo. See What you give it.
  • codexqa-testcase-generator needs local requirement materials (file, directory, paste, or HTTPS document URL this turn). Optional knowledge dir / Git URL. After Exec, expect Markdown under testcase/cases/ plus testdesign/testcase_generation_report.html. Smoke: ./scripts/tcg-python scripts/close_stage.py --self-check (and check_run_gate.py / generate_case_report.py --self-check) from the skill directory. See its README.
  • codexqa-testdata-generator needs a construct request, cases, or an API source — not application source. See What you give it.
  • codexqa-jev-browser needs a UI case (YAML / Markdown / API) or a natural-language goal plus a URL. Run npm install in the skill directory first; live auto / generate --goal also need a model key in .env. See its README.

Sample prompts for each skill: root README · Quick start.

Method write-ups: How it works index. What to bring: FAQ.

Troubleshooting

Symptom Check
Skill not listed from GitHub The skill must be committed and pushed to the repository being installed
Agent does not discover the skill Selected agent, project/global scope, and whether a new session is required
Unknown .ts extension Node runtime and TypeScript stripping environment
Missing plan Provide repository/branch and business materials; degraded loading does not mean sufficient materials
Static/call-graph analysis unavailable Tool installation result, PATH, permissions, and network access
codexqa command not found or graph query is empty Install @openqa-cn/codexqa, check PATH, confirm the repository was indexed, and use --diff-base for change review. For codexqa-code-wiki, run its scripts/wiki.mjs brief, which indexes and exports for you
Local report link does not open Open the returned HTML file in a browser

For support include the commit, Node version, OS, agent/version, command, and sanitized error. Do not upload source or task directories containing private data.