Contribution Guide
Relevant source files
The following files were used as context for generating this wiki page:
CCS is a multi-provider profile and runtime manager for Claude Code and compatible CLIs, built using Bun, TypeScript, and React. This guide outlines the workflows, standards, and technical requirements for contributing to the project, ensuring changes remain consistent with the architecture and maintainable over time.
Contributors should focus on maintaining parity between the CLI and the Dashboard UI while adhering to the established CI/CD gates and testing protocols. Security vulnerabilities must be reported privately as per Security Reporting.
Sources: CONTRIBUTING.md:1-5, README.md:1-5, AGENTS.md:104-108
Project Architecture and Repo Map
The repository is organized into distinct areas covering the CLI runtime, the web server/API layer, and the React-based dashboard.
| Area | Main Paths | Typical Follow-up |
|---|---|---|
| CLI Runtime | src/, lib/, config/, scripts/ | Add/update tests in tests/ |
| Dashboard UI | ui/src/ | Run cd ui && bun run validate |
| Web Server & Config APIs | src/web-server/, src/api/, src/config/ | Add unit or integration coverage |
| Documentation | README.md, docs/, CONTRIBUTING.md | Keep user-facing docs in sync |
| Static Assets | assets/ | Verify screenshots and references |
Sources: CONTRIBUTING.md:14-20, AGENTS.md:20-25
Development Workflow
The development process follows a branch-and-PR model targeting the dev branch.
A diagram showing the standard flow from identifying a task to merging a Pull Request.
Sources: CONTRIBUTING.md:7-12, CLAUDE.md:7-11
Environment Setup
Local development requires Node.js and Bun. Contributors must isolate their development environment to avoid affecting their primary CCS configuration.
Prerequisites and Installation
- Node.js:
>=18 - Bun:
>=1.0 - GitHub CLI (
gh): Optional, for terminal-based PR management.
# Clone and install
git clone https://github.com/YOUR_USERNAME/ccs.git
cd ccs
bun install
cd ui && bun install && cd ..
Path Isolation
CCS reads/writes to ~/.ccs/. To prevent data corruption during testing, use CCS_HOME to redirect storage.
- Unix:
export CCS_HOME="$(mktemp -d)" - PowerShell:
$env:CCS_HOME = Join-Path $env:TEMP ("ccs-" + [guid]::NewGuid())
Sources: CONTRIBUTING.md:33-47, CONTRIBUTING.md:112-125
Standards and Guidelines
Coding Standards
- Language: TypeScript and Bun are the primary runtimes.
- Errors: Use typed errors from
src/errors/error-types.ts(e.g.,ConfigError,NetworkError). - Logging: Use
createLogger(...)for diagnostic logging. - CLI Output: Use ASCII characters only for status indicators:
[OK],[!],[X],[i]. - Environment: Ensure TTY-awareness and respect
NO_COLOR.
Sources: CLAUDE.md:15-18, scripts/maintainability-metrics.js:20-40
Commit and Branching Style
The project enforces Conventional Commits to facilitate automated release notes and versioning via semantic-release.
- Prefixes:
feat/*(features),fix/*(bug fixes),docs/*(documentation). - Commits: Use
feat:,fix:, ordocs:prefixes. Avoid vague messages like "fix stuff" or "WIP".
Sources: CONTRIBUTING.md:49-60, CONTRIBUTING.md:179-191
Validation and Testing
Contributors must run local validation suites before submitting PRs.
Validation Commands
| Command | Scope |
|---|---|
bun run format | Code formatting |
bun run lint:fix | Linting and auto-fixes |
bun run validate | Fast gate (typecheck, lint, fast tests) |
bun run validate:ci-parity | Full gate (builds, e2e, and all tests) |
Sources: CONTRIBUTING.md:136-153, AGENTS.md:58-64
CI/CD Pipeline
The repository utilizes three automation lanes:
- CI: Runs on PRs to
devandmain(Review gate). - Push CI: Runs after merges to
dev(Quality signal). - Dev Release: Publishes
@devpackage (Automation).
Sources: CONTRIBUTING.md:65-72, CLAUDE.md:86-91
Automated AI Review
The project uses a self-hosted PR-Agent for AI code reviews.
- Triggered via the
.github/workflows/ai-review.ymlworkflow. - Comment
/reviewon a PR to request a fresh analysis. - Reviewer instructions are maintained in
.pr_agent.toml.
Sources: CONTRIBUTING.md:83-93, scripts/code-reviewer.ts:1-10
Maintainability Metrics
The project tracks specific maintainability goals monitored by scripts/maintainability-metrics.js.
| Metric | Target / Requirement |
|---|---|
| Typed Errors | Use CCSError subclasses; >40% adoption in core subdomains. |
| Logger Coverage | Subdomains should not have zero createLogger calls. |
| File Size | Avoid files exceeding 400 or 600 lines of code (LOC). |
| Console Usage | Avoid console.error/warn in hotpaths; use ErrorManager instead. |
Sources: scripts/maintainability-metrics.js:9-60
Security Reporting
Security vulnerabilities are not handled through public issues. Contributors must use the private reporting path.
- Report form: GitHub Security Advisories
- Guideline: Do not disclose exploit details, leaked credentials, or risks in public forums before a fix is shipped.
Sources: CONTRIBUTING.md:200-208, SECURITY.md
Conclusion
Contributing to CCS requires a balance of CLI and Dashboard feature parity, strict adherence to TypeScript and Bun standards, and rigorous local validation. By following the branch protocols and maintainability metrics, contributors help ensure the project remains a stable and reliable tool for managing Claude Code runtimes.
Sources: CONTRIBUTING.md:1-10, AGENTS.md:104-108