Skip to content

Contributing to Provider-Aware Statusline

Thanks for your interest. This repository is an engineering notebook as much as a tool: the Provider-Aware Statusline is the installable product, and the research, findings, ADRs, and design documents are the evidence trail that says why it works.

Inbound license

By submitting a contribution you agree that it will be licensed under this repository's dual-license model:

  • Code / executables / config — MIT
  • Documentation / knowledge / media — CC BY 4.0

See LICENSING.md for the full mapping. If your change adds a source file, include the // SPDX-License-Identifier: MIT header.

Engineering principle

Investigate first. Design second. Implement last.

This project treats evidence as a first-class deliverable. Before changing behavior, understand the actual data flow — and record what you verify. A claim that "Claude Code does X" is only project knowledge when it has been observed locally or traced to an authoritative source.

How to work here

  1. Open an issue or PR first for anything non-trivial. Small fixes are fine directly.
  2. Preserve evidence. External research stays verbatim in Research/. Local observations belong in Findings/. Conclusions move up to Knowledge-Base.md, Architecture.md, and Decisions.md only when they are supported by evidence.
  3. No secrets. Never commit the contents of .claude/settings.local.json or any token, prompt, or request content. Use .claude/settings.local.example.json with placeholders instead.
  4. Keep the statusline a reader. The tool never writes, never guesses a value it cannot source, and degrades toward the requested model on every failure. Preserve that invariant.

Running the tests

npm test

The contract suite (Statusline/test/statusline.test.js) is 68 tests covering every display state, the failure fallback chain, and the V2 pipeline. It runs with zero dependencies on Node 18+.

Before a release, the repository must be clean of machine-specific identifiers (absolute home paths, usernames, hostnames, local gateway ports) and free of broken links:

node Scripts/check-markdown-links.js

Code of conduct

Please read CODE_OF_CONDUCT.md. Be respectful, be evidence-based, and assume good intent.