Thanks for contributing.
OpenClaude is a rapidly evolving open-source coding-agent CLI with support for multiple providers, local backends, MCP, and a terminal-first workflow. The project is actively developed and updated frequently. Our current focus is on stability and performance — we're prioritizing reliable, well-tested contributions over new feature additions. The best contributions here are focused, well-tested, and easy to review.
- Before You Start
- Proposing New Features
- Pull Requests
- Development Workflow
- AI Agent Guidelines
- Code Style
- Provider Changes
- Local Setup
- Validation
- Community
- Search existing issues and discussions before opening a new thread.
- Check open pull requests for work that overlaps with your contribution. If a PR already exists that addresses the same change, open an issue or discussion first to align on direction — duplicate PRs may be closed without review.
- Use issues for confirmed bugs and actionable feature work.
- Use discussions for setup help, ideas, and general community conversation.
- For larger changes, open an issue first so the scope is clear before implementation.
- For security reports, follow SECURITY.md.
OpenClaude is moving toward a more maintainer-directed roadmap. We are focusing development efforts on stability, performance, and core reliability. As a result, new feature additions are being evaluated more carefully to ensure they align with the project's direction.
Before investing time in a feature PR, please open an issue first to propose and discuss your idea with the maintainers. This isn't about gatekeeping — we genuinely value your ideas and want to help shape them into contributions that fit the project's goals. The conversation will help you understand:
- Whether the feature aligns with our current roadmap
- If similar work is already planned or in progress
- The best approach that maintains project consistency
This step prevents wasted effort on PRs that might otherwise be closed without review simply because the feature doesn't match where we're taking the project. Your idea may be great — it just needs to fit the bigger picture.
Before opening a PR:
- Read this
CONTRIBUTING.mdfile. - Read
AGENTS.mdfor repo-specific coding-agent conventions, validation commands, provider guidance, and architecture rules. - Re-check open and recently closed PRs for duplicates.
- Keep the branch focused on one issue or one clearly scoped improvement.
- Run the checks required for the affected surfaces in Validation before opening the PR. After pushing, monitor CI and automated review until the PR is ready for maintainer review.
Every PR needs a reason. Your PR description must include:
- confirmation that you reviewed both this
CONTRIBUTING.mdfile andAGENTS.md - what changed and why
- the user or developer impact
- the exact checks you ran
- a linked issue when one exists, using
Fixes #123,Closes #123, or another clear link - screenshots when the PR touches UI, terminal presentation, or the VS Code extension
- which provider path was tested when the PR changes provider behavior
The PR author is responsible for a reviewable, merge-ready contribution: passing applicable local checks, green CI on the current revision, and addressed automated review feedback. This applies to the initial PR and follow-up pushes. Keep work in progress as a draft; do not request maintainer review with unresolved PR-owned failures. PRs with merge conflicts will not be reviewed or approved until the conflicts are resolved. Verified pre-existing failures follow the exception in Validation.
Issues are the recommended starting point for anything non-trivial — opening one first helps avoid wasted effort if the change is out of scope or already being worked on. Small fixes, doc corrections, and obvious improvements can stand on their own without a linked issue, as long as the PR description explains the intent.
We use CodeRabbit to assist with PR reviews. CodeRabbit will automatically review your PR and leave comments on potential issues, bugs, or style concerns.
PR authors must follow up on CodeRabbit findings until CodeRabbit approves the current revision, or a maintainer explicitly accepts a documented exception. Fix valid, in-scope findings, reply with the resolution, and request another automated review when needed. A PR may not receive maintainer review while requested fixes remain unaddressed, even if CI is green. Do not leave the maintainer to chase feedback or finish the author's validation.
One important caveat: verify each suggested change against your PR's stated scope and intent before applying it. Automated reviewers can suggest fixes that accidentally force changes to surfaces you never intended to touch, or that quietly pull the PR away from its original framing. When a suggestion would cause that kind of drift:
- you may decline it with a brief justification in the comment thread
- when unsure whether a suggestion is in scope, ask a maintainer before applying or declining it
Declining an incorrect or out-of-scope suggestion with evidence and a clear reason is acceptable. Explain why it is incorrect or would cause scope drift in the comment thread, continue resolving the remaining findings, and seek a maintainer decision if the disagreement still blocks approval. Do not expand the PR merely to obtain automated approval. Silently ignoring findings is not acceptable: every finding needs a fix, a justified decline, or an explicit escalation.
Keep the PR mergeable. Rebase when conflicts need resolving, or when a maintainer identifies a specific upstream change needed for correctness or validation. You do not need to rebase merely because main advanced, you resumed work, or you are pushing a review fix. Ordinary follow-ups can be new commits on the existing branch.
Check relevant upstream changes before acting on stale review feedback. After a rebase or conflict resolution, rerun checks whose inputs or behavior changed under Validation; use the full local preflight when the integration has broad impact.
Before rebasing an already-pushed PR branch, fetch the current remote PR head, record its exact commit SHA, and incorporate any commits that were added to the remote branch. Then fetch upstream main and rebase. Publish with an explicit lease pinned to the PR-head SHA you recorded, never an unguarded --force or an unqualified lease:
git push --force-with-lease=refs/heads/<pr-branch>:<recorded-pr-head-sha> <pr-remote> HEAD:refs/heads/<pr-branch>Pinning the expected SHA prevents a background fetch from silently moving a remote-tracking ref and weakening the lease. If the lease is rejected, stop: fetch and inspect the new remote PR head, incorporate its commits, redo the rebase, and retry with that newly recorded SHA. If the branch is shared or does not allow force-pushes, coordinate with a maintainer and use a repository-approved non-rewriting update path instead of discarding remote work.
Resolve conflicts before requesting review. A branch being behind main is not by itself a reason to rewrite it or repeat unrelated local checks.
Submitting a PR is a commitment to see it through to the end. Review here is in-depth and can take multiple rounds — do not be surprised if every review pass results in follow-up fix requests; that is the normal shape of this project's review process, not a signal that your PR is unwelcome. Please be prepared to:
- Respond to review feedback within 1 week of a maintainer or CodeRabbit review request
- If you need more time, leave a comment explaining your situation and expected timeline
- PRs with no activity for 2 weeks after a review request will be closed as abandoned. At that point, another contributor may pick up the work under a new PR
This policy ensures the project stays maintainable and that contributor queue doesn't grow stale. We understand life happens — a quick note explaining a delay goes a long way.
Once applicable CI is green and automated feedback is resolved, the PR is ready for maintainer review. Maintainers own the final design review, acceptance decision, and merge. They may choose to take over integration or follow-up work, but contributors should not assume that handoff: continue to address new requests unless a maintainer explicitly takes ownership. While waiting, no periodic rebase, full local rerun, or new push is required solely to keep the PR active. Green checks make a PR eligible for review; they do not guarantee acceptance.
If you find yourself getting fix requests on every round, treat that as a signal rather than noise: repeated findings on the same PR usually trace back to a core design issue, with each surface-level patch exposing another symptom. Investigate the root cause of what reviewers are flagging instead of patching the reported problem. And if you are driving the work with an AI agent, this is also the moment to re-evaluate how you are prompting it — vague or narrow prompts produce surface fixes; detailed instructions to investigate the requested change and its surrounding design produce fixes that hold up under review.
We are proactive about closing duplicate PRs. Before submitting, it is your responsibility to check whether a similar PR already exists:
- Search open pull requests for related work
- Check closed pull requests to see if similar work was previously addressed or declined
- If you find an existing PR, engage in that thread rather than opening a new one
Duplicate PRs will likely be closed without review or follow-up. This isn't personal — it's about keeping the review queue focused and efficient.
PRs may be closed without review if they:
- duplicate work already covered by an open pull request
- bundle unrelated fixes, features, or refactors into a single PR without prior discussion and maintainer approval
- add features, refactors, or dependency changes that were not discussed first
- drift from the approved scope of a linked issue
- change the project's language, core runtime, or dependency stack without prior maintainer agreement
- are drive-by contributions with no context, no tests, and no clear purpose
- submit a PR with the PR template ignored — generic filler text or leftover template placeholders (
what changed,provider/model path tested:, etc.) show the description was not written for your PR. These will not be reviewed until corrected and risk being closed without review - are automated bounty-hunting or mass-submitted PRs that provide little meaningful value to the codebase
- are advertisements, sales pitches, or promotional submissions for a product or service — open an issue first to discuss with maintainers if you believe your product or service is relevant to this project
This is not a judgment on the contributor. It is how the project stays reviewable. If your PR is closed, the best next step is to open an issue, clarify the intent, and get alignment before re-submitting.
We want OpenClaude to be a welcoming community, but we must also protect the project's quality and contributor time. The following actions will result in a ban from future contributions:
- Repeated fly-by PRs with no follow-up after review requests
- Repeated submission of duplicate PRs
- Ignoring CodeRabbit findings and waiting for maintainer override
- Automated or mass-submitted PRs that provide little meaningful value
We don't take this lightly. If you're unsure whether your contribution is a good fit, open an issue first — we're happy to help guide you.
Stay within the project's existing technical direction. PRs that shift the codebase to a new language, significantly restructure dependencies, or introduce a new runtime are unlikely to be accepted without prior discussion.
Dependency changes need a clear project benefit — fixing a bug, addressing a security issue, or supporting an approved feature. Preference-based reasoning alone is not enough — explain the concrete benefit.
- Keep PRs focused on one problem or feature.
- Avoid mixing unrelated cleanup into the same change.
- Preserve existing repo patterns unless the change is intentionally refactoring them.
- Add or update tests when the change affects behavior.
- For vendor/integration catalog tests, cover each vendor with one table-driven test of its registry contract (route resolution, default base URL and model, credential env vars, catalog-to-descriptor linkage, and capability/limit values the runtime uses), plus a small number of behavioral tests such as model-discovery keep/drop parsing or availability windows. Do not copy full curated model lists or cache/refresh settings from vendor definitions into tests.
- Test files share a process within each run or shard; restore
mock.moduleregistrations, environment variables, globals, and process state inafterEach/afterAll. - Git discovery honors
GIT_CEILING_DIRECTORIESin both filesystem lookups and Git subprocesses. Use an explicit ceiling for temporary fixtures that must exclude enclosing repositories; a ceiling prevents ascent into that directory without excluding the starting working directory. Separate multiple absolute ceiling directories with the platform's path-list delimiter. - When tests set or delete environment variables, import
snapshotEnvfromsrc/test/envSnapshot.tsusing the appropriate relative.jspath. InbeforeEach, save the named variables before changing them withrestoreEnv = snapshotEnv(keys); pass{ clear: true }when setup needs those variables unset. CallrestoreEnv()inafterEach, or usefinallyfor changes scoped to one test. Restoration preserves previous values, including empty strings, and deletes variables that were previously unset. List only the variables the test changes or deliberately clears; do not replaceprocess.envor blanket-clear unrelated variables. When using the shared mutation lock, snapshot after acquiring it and restore before releasing it. - In timing-sensitive tests, drive timers with Bun's fake timers (
jest.useFakeTimers()andjest.advanceTimersByTime()) instead of racing real delays, and restore real timers during cleanup, so the tests pass in a single-process whole-suite run as well as in the sharded runner. - Await completion promises or explicit readiness signals before asserting asynchronous results. For tests that deliberately suppress readiness, use a short, bounded wait and assert the expected failure.
- For tests that launch real subprocesses, set an explicit per-test timeout longer than the child-process deadline, leaving time for assertions and cleanup. The launcher heap tests use an 8-second child deadline and a 10-second test timeout. Document the reason for the timeout beside the test.
- Update docs when setup, commands, or user-facing behavior changes.
- Website release notes live on GitHub Releases. Do not add manually maintained release-note data to the static site.
AI-assisted and vibe-coded contributions are welcome, but please review your own changes thoroughly before opening a PR. Even frontier models produce subtle bugs, incorrect assumptions, and code that looks right but isn't.
Before submitting, run multiple rounds of review on generated code:
- check for correctness, not just whether it compiles
- verify style consistency with the rest of the codebase
- remove unnecessary changes or auto-generated noise
- confirm adherence to the project's patterns and architecture
- ask your AI assistant "are you sure there are no issues with this code?" — this alone can surface problems that would otherwise slip through
Self-review up front saves everyone time and reduces back-and-forth during maintainer review.
Use the exact marked version in package.json and its bundled TypeScript types;
import marked, Lexer, Token, or Tokens from the package's ESM entry point.
Do not add @types/marked or a separate rendering extension. Use
configureMarked() before terminal lexing and formatToken() / applyMarkdown()
for terminal output; strikethrough parsing is deliberately disabled.
List items can contain paragraph children and checkbox tokens. Preserve list
markers for paragraph children and omit checkbox glyphs in terminal output. Pass
the previous sibling to formatToken() when rendering block sequences so separate
space tokens do not duplicate spacing after headings, tables, or indented code.
Indented code has trailing newlines removed for terminal display and /copy;
fenced code retains its content. Keep streaming boundary calculations on the
complete lexer token stream, including whitespace and each token's raw length.
CLAUDE.md parsing uses its own new Lexer({ gfm: false }) to preserve include
paths. When removing a comment-only HTML block, consume its following whitespace
token too; preserve whitespace with visible comment residue and leave code blocks
untouched. When updating marked, compare representative terminal, table, list,
code, link, streaming, and memory-file output and run the markdown regression tests.
Regenerate the exact dependency pin and lockfile with bun add --exact marked@<version>.
Development scripts run under Bun and use Bun.spawn or Bun.spawnSync.
Use argument arrays and set stdin, stdout, stderr, cwd, environment, and deadlines
explicitly to preserve the command contract. The capture helper in
scripts/subprocess.ts returns UTF-8 stdout and stderr, a nullable status, and
launch, timeout, or output-limit errors for synchronous probes. Check errors and
status before consuming output. Keep the fixed processor probe's platform shell
invocation when testing command wrappers; never interpolate user input into it.
The clean-install verifier retains its existing command runner for cross-platform
package-manager wrappers. The startup benchmark runs under Node to measure its
startup and compile cache; its process calls and the real Node pipe observer in
the test runner's backpressure fixture use Node's process API.
Use the exact execa and chalk pins in package.json and their public ESM
exports and bundled types. Regenerate both pins and the lockfile with
bun add --exact execa@<version> chalk@<version>.
Prefer asynchronous execa(file, args, options); use shell: true only for
commands that need shell syntax. With reject: false, check failed,
timedOut and exitCode before consuming stdout or stderr. Use
SyncOptions for synchronous options. The subprocess is a promise; access
Node child-process event and lifecycle APIs through subprocess.nodeChildProcess.
Use template strings or parseCommandString() for command splitting, and
ipc: true for IPC. Explicit input takes precedence over inherited stdin;
set stdin deliberately, and bound subprocess output with maxBuffer and
execution time with timeout.
Use the shared default chalk instance for terminal styles and the existing
colorize() and theme helpers for theme colors. Keep the VS Code color boost
and tmux clamp in src/ink/colorize.ts. Numeric FORCE_COLOR selects an exact
level (0 disables color, 1 selects 16 colors, 2 selects 256, 3 selects truecolor);
ansi256() and bgAnsi256() downsample at level 1. Use new Chalk({ level })
only when a separate capability level is intentional, as for Apple Terminal
charts. Tests that change chalk.level must restore it, and environment-driven
color detection tests must import in a fresh process.
Keep commander and @commander-js/extra-typings pinned together at exactly
15.0.0; the typings peer requires commander ~15.0.0. Regenerate bun.lock
with bun install after changing both pins. Use their public ESM exports.
Declare positional arguments explicitly, including variadic arguments for commands
that forward subprocess arguments. Excess arguments are rejected by default.
Short flags must be a single character; use --debug-to-stderr in place of the
unsupported -d2e spelling. Dual long flags, such as --yolo and
--dangerously-skip-permissions, are supported. When registering both positive
and negative boolean flags, set an explicit default only if the command needs one;
otherwise the omitted option remains undefined. Keep help and parse-error checks
on the built CLI so command registration is exercised under Node.
Terminal syntax highlighting uses the exact highlight.js pin directly, with
the shared Chalk instance for ANSI colors. Keep the lazy loader and terminal
palette in src/utils/cliHighlight.ts for terminal code and Markdown highlighting
only. Structured diff rendering in src/native-ts/color-diff/index.ts loads
highlight.js separately. Run the highlighting and Markdown regression tests
when changing this dependency or its ANSI renderer.
Keep wrap-ansi pinned to 9.0.2. Version 10 expands tabs into spaces, and
Cursor (src/utils/Cursor.ts) and Ink's style mapping expect the wrapped
text to keep the original characters; with v10, a tab in a text input throws
and exits the session. Only the Node runtime loads the npm package: under Bun,
src/ink/wrapAnsi.ts uses Bun.wrapAnsi, so tests never exercise it.
src/ink/wrapAnsi.test.ts asserts the npm package keeps tabs. Adapt the tab
handling before upgrading past 9.x.
Keep all direct dependencies and devDependencies pinned to exact versions in the root and web manifests. Regenerate the relevant Bun lockfile when changing a pin.
Schema validation uses Zod 4.6.7, pinned exactly in the root development
dependencies and in the root and website resolution overrides. Import
zod/v4 for application schemas, use native conversion through the shared
zodToJsonSchema helper, and preserve validation messages and generated schema
contracts. Follow Schema validation for object
strictness, defaults, error customization, dependency compatibility and SDK
peer handling. Regenerate both lockfiles with bun install after changing
the shared pin.
The static website in web/ uses Astro 7.4.12, @astrojs/check 0.9.12,
and @astrojs/sitemap 3.7.4, all pinned exactly. Install its dependencies
with bun install --cwd web, then run bun run web:typecheck and
bun run web:build from the root. The build includes scripts/verify-dist.ts
to check rendered navigation, release redirects, sprites, and sitemap entries.
Astro's Node.js >=22.23.4 requirement is covered by the repository's
>=24.22.1 runtime floor. Keep compressHTML: true in the site config to
preserve HTML-aware whitespace compression; Astro 7 defaults to JSX whitespace
rules. The site uses Astro templates and typed data without remark or rehype
plugins, so it does not need the optional @astrojs/markdown-remark peer.
If adding those plugins later, install a compatible exact pin and configure
the Markdown processor according to the Astro 7 upgrade guide.
Linting uses ESLint 10.13.0 with @typescript-eslint/parser and
@typescript-eslint/eslint-plugin both pinned to 8.72.0, which support ESLint 10.
Keep these pins compatible and regenerate bun.lock with bun install after
updating them. Run bun run lint from the repository root; ESLint 10 discovers
eslint.config.js from each linted file's directory. The JavaScript flat config
does not require jiti or extend a recommended preset. Keep its explicit rules
and ignores when upgrading. ESLint's Node.js requirement is covered by the
supported Node.js >=24.22.1 runtime.
Keep chokidar pinned exactly to 6.0.0 and use its public ESM exports and
bundled types. Pass literal paths rather than globs. Use backend to select
watching behavior and pollingInterval / pollingBinaryInterval for polling;
awaitWriteFinish.pollInterval is a separate, unchanged option. Skill watching
uses the polling backend under Bun with explicit atomic: true to preserve
atomic-save handling. Await close() when teardown must finish, and create a
new watcher for subsequent subscriptions because closing is terminal. Its
Node.js 22.22 minimum is covered by the supported Node.js >=24.22.1 runtime.
Regenerate bun.lock with bun install after updating the exact pin.
Keep @sentry/node pinned exactly to 11.9.0 and regenerate bun.lock with
bun install after updating it. The optional reporter uses a lazy ESM import
after trust is established. Keep default integrations and tracing disabled,
set attachStacktrace: false, and explicitly disable dataCollection categories
so only vetted messages are reported. Do not add automatic instrumentation or
an OpenTelemetry provider to this path. Run bun test src/utils/sentry.test.ts
when updating the SDK or initialization. Its Node.js minimum is covered by the
supported runtime; self-hosted Sentry requires 26.4.2 or later.
The root overrides block also controls transitive resolutions:
ip-address:10.7.4sets the security floor for the MCP SDK'sexpress-rate-limitdependency path.google-auth-library:11.3.1keeps Google authentication on the same version as the direct dependency. The override accompanies the replacement of the legacy Vertex SDK to remove its deprecated UUID dependency path.lodash-es:4.18.1keeps transitive copies on the security fixes for template code injection and prototype pollution, avoiding the deprecated4.18.0release.node-domexception: the existing shim re-exports the platform's nativeDOMExceptionforfetch-blob, replacing the deprecated polyfill.
If you are an AI agent (Copilot, Cursor, Claude, etc.) working on this codebase, refer to AGENTS.md for project-specific coding guidelines, conventions, and validation commands. Following these guidelines will help your contributions align with the project's patterns and reduce review friction.
In particular: link release-notes navigation to GitHub Releases rather than adding a local changelog page or manually maintained release data.
- Follow the existing code style in the touched files.
- Prefer small, readable changes over broad rewrites.
- Do not reformat unrelated files just because they are nearby.
- Keep comments useful and concise.
When working on diff generation or rendering, import public APIs and types from
diff; the package supplies its own TypeScript declarations, so do not add
@types/diff or import internal library paths. Use diffWordsWithSpace when
rendering must preserve whitespace. Keep patch filenames separate from hunk
content: serialized headers may quote or escape filenames, and parsed patches
can omit filenames. Check the diff and edit-snippet tests when changing these
paths.
Use the exact undici 8.12.3 pin and its public exports and bundled types.
Regenerate bun.lock with bun install after changing the manifest pin.
Its Node.js minimum is covered by the supported >=24.22.1 runtime.
Wrap per-request fetch dispatchers with the public Dispatcher1Wrapper so
Node 24's native fetch can use its legacy callbacks; the wrapper also accepts
the current handler API. setGlobalDispatcher() handles the global bridge.
Undici 8 enables HTTP/2 by default; the bridge keeps legacy requests on HTTP/1.1.
Set proxyTunnel: true to retain CONNECT for plain HTTP targets. Normalize
leading *. bypass entries to . before constructing the environment proxy
dispatcher so apex and subdomain bypasses continue to match the shared helpers.
Keep custom TLS options on Agent.connect for direct requests, including
NO_PROXY bypasses, and on ProxyAgent.requestTls for CONNECT targets.
Use the shared helpers in src/utils/proxy.ts: createAxiosInstance() for
Axios, getWebSocketProxyAgent(url) for Node WebSockets, and getProxyFetchOptions()
for fetch. The Axios and WebSocket helpers apply NO_PROXY bypasses before
selecting an agent. getWebSocketProxyUrl(url) supplies Bun's native WebSocket proxy
option. Lowercase proxy environment variables take precedence over uppercase
variants on the Axios, WebSocket, and fetch/undici paths. The shared helpers read
no_proxy before NO_PROXY using ??, so an empty lowercase no_proxy is kept
and does not fall back to NO_PROXY.
https-proxy-agent is pinned exactly to 9.1.0 and remains an external runtime
module in scripts/externals.ts. Use its public named ESM exports, such as
import { HttpsProxyAgent } from 'https-proxy-agent', and the constructor
new HttpsProxyAgent(proxyUrl, options). Both it and agent-base are ESM
packages requiring Node.js 20 or later; use OpenClaude's supported Node.js
>=24.22.1 runtime. Keep dependency updates exact and generate bun.lock with
bun add --exact https-proxy-agent@<version>.
Keep TLS verification enabled. Configure NODE_EXTRA_CA_CERTS before starting
the CLI when a custom CA is needed. For runtime certificate configuration, the
shared CA loader reads that file and the TLS helpers supply explicit options;
clear the CA and mTLS caches after configuration changes. Structured I/O
environment updates to TLS or proxy settings refresh CA, mTLS, and proxy caches
and global agents; effective bypass-list changes do the same. Proxy-agent
constructor options configure the connection to the proxy. Supply target TLS
options on the HTTPS request, using getWebSocketTLSOptions() where applicable;
do not assume constructor ca options also trust the target inside a CONNECT
tunnel. Run bun test src/utils/proxy.connect.test.ts src/utils/proxy.test.ts
when changing these paths to verify HTTPS CONNECT routing and NO_PROXY
bypass with certificate validation enabled.
OpenClaude supports multiple provider paths. Before contributing provider changes, review the relevant documentation to ensure your implementation follows the expected patterns:
- start with
docs/integrations/overview.mdfor an understanding of how integrations are structured - use the focused how-to guides under
docs/integrations/how-to/for new vendors, gateways, models, anthropic proxies, and/usagesupport - PRs that skip documented patterns or introduce inconsistent provider behavior may be sent back for rework
When submitting provider changes:
- be explicit about which providers are affected
- avoid breaking third-party providers while fixing first-party behavior
- test the exact provider/model path you changed when possible
- call out any limitations or follow-up work in the PR description
- do not assign or use provider tags — these are controlled by maintainers and will be applied during review
Use Node.js >=24.22.1 (Node 26 recommended/default) and Bun 1.4.4 (tracked in .bun-version).
Keep @types/node on the Node 24 major to match the minimum supported runtime, even when developing on Node 26. Pin it to an exact published 24.x version; the type package version does not need to match the Node.js runtime patch version.
Install dependencies:
bun installBuild the CLI:
bun run buildSmoke test:
bun run smokeFull local check:
bun run checkRun the app locally:
bun run devIf you are working on provider setup or saved profiles, useful commands include:
bun run profile:init
bun run dev:profileThis section is the authoritative local validation contract; AGENTS.md and the PR template defer to it. Select checks by what the change can affect, not just its size. Applicable lint, static checks, type checks, and regression tests are mandatory. A focused test pass does not replace these checks, and green CI does not excuse deliberately skipping applicable local validation.
CI evaluates the complete PR diff, including after a small follow-up push. PR Checks skips code jobs for Markdown/docs-only PRs unless .github/ is touched; otherwise its code filter selects all unit shards, static checks, type checks, and launcher checks, not individual subsystems. The web job is selected independently. The intent scan runs on every PR, and every PR Checks job runs on pushes to main. See .github/workflows/pr-checks.yml for exact filters.
The stable checks are PR checks required, Install hygiene required, and VS Code launcher required. Each reports on every PR: selected jobs must pass, while jobs for untouched surfaces may skip. Failed change detection, failed or cancelled jobs, and unexpectedly skipped applicable jobs fail the corresponding check. Documentation-only PRs still run the intent scan and existing CodeQL checks; they do not wait for unrelated application, install, or extension jobs.
For repository administrators: after these workflows are merged into main, add these three check names to the branch ruleset as required checks from GitHub Actions, preserving the existing CodeQL requirements. Do not require individual matrix jobs or path-filtered workflow names. Enable the requirements only after the workflows are available on the base branch; existing PRs may need an update to pick up the new jobs. Keep the requirement to update branches before merging disabled unless a separate policy change is intended.
Before the initial PR, apply this table to the complete proposed diff. Combine rows when more than one surface is affected. Before a follow-up push, apply it to the update since the last successfully validated revision, subject to the reuse rules below.
| Affected surface | Required local validation |
|---|---|
| Prose-only Markdown/docs, including PR-template wording, with no executable examples or site/build inputs changed | Review rendering, links, and documented commands for accuracy; git diff --check; PR intent scan. No application build, lint, typecheck, or unit suite is required solely for prose. |
| CLI, SDK, providers, shared source, root tests or scripts | Core checks below, plus the regression tests for the changed behavior and affected callers. Use the full preflight for broad impact. |
Website content, assets, templates or tooling under web/, or shared inputs affecting the site |
Website typecheck/build below and relevant site tests. Add core/full checks when root code or shared tooling is also affected. |
| Root dependencies/lockfile, runtime/toolchain pins, lint/type/build/test configuration, CI workflows, or changes spanning shared runtime behavior | Full local preflight below, plus website checks when its inputs are affected. |
| VS Code extension | npm --prefix vscode-extension/openclaude-vscode run lint and bun run --cwd vscode-extension/openclaude-vscode test; add core checks if CLI behavior is affected. Windows launcher changes also need the launcher test in .github/workflows/vscode-launcher.yml; disclose local platform limits and follow that CI result. |
For a documentation change to executable examples, run the relevant commands/tests as well. A Markdown extension does not make executable content safe to leave unchecked. When the impact is uncertain, broaden validation; do not guess that a check is inapplicable.
- Rerun the applicable lint, static and type checks whenever their inputs change. For a root code/test fix, run the core checks and affected regression tests; the full unit suite is not required merely because another commit is being pushed.
- Reuse a successful result only while its inputs, dependencies, configuration and relevant upstream behavior are unchanged. Record the previously validated revision and which results remain applicable. Rebase/conflict resolutions invalidate affected results, not automatically every result.
- A prose-only follow-up to a code PR can reuse its earlier code validation, but CI still evaluates the whole PR. A dependency, shared-runtime or configuration change requires broader validation even if its diff is one line.
- Update the PR's testing notes with the new commands/results, the validation scope, and reasons for any inapplicable or blocked checks. An unrun, failed or incomplete applicable check is not a pass; document a blocker and keep the PR in draft until it is resolved or a maintainer explicitly accepts an exception.
- After every push, monitor CI and CodeRabbit, diagnose failures and fix PR-owned problems before requesting maintainer review. Initial and follow-up CI success remains the author's responsibility. Do not repeatedly push known failures and leave maintainers to investigate them.
Install root dependencies with bun install --frozen-lockfile before validation in a fresh checkout, and again when the root manifest or lockfile changes. An unchanged, successfully installed dependency tree may be reused between follow-ups. Keep lockfiles in sync; a cache hit does not replace the required checks.
Core checks for root code/test changes:
bun run check:static
bun run typecheck:fast
bun run typecheck:type-tests
node bin/openclaude --versioncheck:static includes ESLint, the any-usage budget, the smoke build, and deadcode checks. It is also the static-check command run by CI. bun run lint runs ESLint alone; do not run it a second time after a successful check:static unless its inputs changed. ESLint's current configuration warns on explicit any and excludes the website and extension; the separate budget check enforces the tracked limits. A passing root lint does not replace those surfaces' own checks.
Add focused tests using the guarded runner (replace the example path):
bun run test ./path/to/test-file.test.tsInclude affected callers and integration paths, not only the edited file. Run bun run test:conversation-arc or bun run test:context-efficiency when changing those feature paths; their flags differ from the default unit pass. For provider changes, test the affected provider/model path as described above.
Full local preflight for broad changes (use this instead of separately running check:static and the same unit tests):
bun run check
bun run typecheck:fast
bun run typecheck:type-tests
node bin/openclaude --versionRun the compile-cache-disabled launcher check below whenever core or full checks apply. Run the PR intent scan before every push, including documentation changes. The scan reads commits: commit the validated changes before scanning HEAD, and rerun it if you add or amend commits before pushing. A scan of an unchanged HEAD does not cover uncommitted edits.
The security scan requires the commit ancestry needed to find the PR's merge base. Check whether your clone is shallow:
git rev-parse --is-shallow-repositoryIf that prints true, fetch the rest of the current branch's history before running the preflight (replace the default remote if your PR branch is tracked elsewhere):
git fetch --unshallowPR intent scan (fetching does not rebase your branch):
git fetch https://github.com/Twigpine/openclaude.git main
bun run security:pr-scan -- --base FETCH_HEAD --head HEADCompile-cache-disabled launcher check, when core or full checks apply, using the syntax for your shell:
Bash, zsh, and similar shells:
NODE_DISABLE_COMPILE_CACHE=1 node bin/openclaude --versionPowerShell:
& {
$previousValue = [Environment]::GetEnvironmentVariable('NODE_DISABLE_COMPILE_CACHE', 'Process')
try {
$env:NODE_DISABLE_COMPILE_CACHE = '1'
node bin/openclaude --version
$launcherExitCode = $LASTEXITCODE
if ($launcherExitCode -ne 0) {
throw "Launcher compatibility check failed with exit code $launcherExitCode"
}
} finally {
[Environment]::SetEnvironmentVariable('NODE_DISABLE_COMPILE_CACHE', $previousValue, 'Process')
}
}If the PR can affect the website — including changes under web/, root or web dependency and lock files, shared site assets or content, or build/toolchain configuration used by the site — also run:
bun install --cwd web --frozen-lockfile
bun run web:typecheck
bun run web:buildNotes on the local preflight:
bun run typecheck:fastruns Bun's builtin type checker againsttsconfig.jsonand is the CI typecheck. Its wrapper resolves the config relative to the script and runs from outside the repository because the package'scheckscript shadowsbun checkinside the project. Usebun run typecheck:fastfrom the root or a subdirectory; from elsewhere, usebun run --cwd /path/to/openclaude typecheck:fast.bun run typecheck:type-testsalso runs in CI and uses TypeScript for focused type assertions. Keep thetypescriptdevDependency for these assertions, ESLint, and@astrojs/check.- PR Checks caches Bun package downloads using OS-scoped keys derived from
bun.lockfor root installs andweb/bun.lockfor web installs, with separate restore prefixes. Dependency installs still run with--frozen-lockfileon cache hits. Keep the relevant lockfile in sync with dependency changes and run the required local preflight regardless of cache status. bun run checkrunscheck:static(ESLint, the any-usage budget, smoke build, and deadcode checks), then the full unit pass (test:full) — do not run those separately, or you execute work twice.bun run testruns test files in a shared process and requires Bun's completed JUnit report as well as a successful exit.test:fullruns all eight native Bun shards serially to release memory between groups. Usebun run scripts/run-tests.ts --shards=N --shard-index=Kwith the same test flags to run only shard K of N.test:fullthen applies the same completion check to the conversation-arc pass and the context-efficiency pass withHISTORY_SNIPenabled. Every shard must produce a complete report; a failed shard does not prevent the remaining shards from running. A test that terminates the runner early fails the command, even if it exits with code zero. Each shard has a ten-minute deadline (override with--shard-timeout-ms=<milliseconds>), reports its start/end and elapsed time, and kills its process group on timeout or cancellation. A timeout stops the remaining shards and exits nonzero. On Linux, shard output is relayed from temporary regular files; diagnostics remain visible during execution. Temporary reports and logs are removed after the check. CI runscheck:staticinsmoke-and-tests, runs the eight unit shards as parallelunit-testsjobs, and runs each dedicated feature pass once indedicated-tests. Each unit shard builds the CLI before testing. CI caps these jobs at 15 minutes each and the other jobs at five minutes.- Fetching upstream
mainby URL avoids assuming that a fork checkout'soriginpoints at Twigpine/openclaude.FETCH_HEADis the fetched upstream tip. The scan deliberately uses localHEADso it includes commits that have not been pushed yet; CI uses the pushed PR head SHA after the push. - The web CI job runs on PRs that change
web/**, rootpackage.jsonorbun.lock,.bun-version, or.github/workflows/pr-checks.yml, and on every push tomain. Contributors do not need to run the web suite locally for changes that cannot affect the site. - The full preflight covers the same command families as PR Checks, but focused local validation deliberately runs fewer tests. Neither reproduces CI exactly in one shell. When selected, CI runs static checks with Node 26 available for smoke checks, runs the unit shards and dedicated feature passes under Node 26, separately builds and checks launcher compatibility under Node 24.22.1 and 26, separately builds and launches under exact Node 24.22.1, and executes every job on a clean runner.
If a local or GitHub CI check fails, first determine whether the PR owns the failure. Treat a failure as pre-existing only when you can reproduce it on the PR's current base (or link to the same failure on a current main CI run) and the PR neither changes the causal surface nor claims to fix that problem.
For a verified pre-existing failure:
- record the failing check, relevant output, and base commit or
mainCI run in the PR - note the pre-existing failure in the PR summary or testing notes so maintainers can track it separately; link an existing issue when one is already available
- explain briefly why the failure is unrelated to the PR
The contributor may then proceed and is not responsible for repairing that failure in the current PR. A maintainer may still need to rerun or waive a required GitHub check, or land the separate fix, before branch protection permits a merge. Failures caused by the PR, or in behavior the PR claims to fix, remain the author's responsibility and must be resolved.
PRs with unresolved PR-owned CI failures are not ready for maintainer review and will not be merged. All applicable CI must pass on the final revision before merge; jobs legitimately skipped by their path filters are not failures. Verified pre-existing failures follow the exception above.
These are not enforced by CI but are worth running locally before submitting.
Additional local TypeScript check against the same tsconfig.json:
bun run typecheckProvider/runtime diagnostics:
bun run doctor:runtimePlease be respectful and constructive with other contributors.
Maintainers may ask for:
- narrower scope
- focused follow-up PRs
- stronger validation
- docs updates for behavior changes
That is normal and helps keep the project reviewable as it grows.