Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
105 lines (72 loc) · 3.63 KB

CONTRIBUTING.md

File metadata and controls

105 lines (72 loc) · 3.63 KB

Contributing to Catenary

Thank you for your interest in contributing to Catenary! This project aims to bridge the gap between AI agents and professional development tools.

How to Contribute

  1. Fork the repository on GitHub.
  2. Clone your fork locally.
  3. Create a branch for your feature or bug fix.
  4. Implement your changes.
  5. Test your changes using cargo test.
  6. Lint your code using cargo clippy and cargo fmt.
  7. Submit a Pull Request to the main branch.

Code Style

  • We follow standard Rust idioms and conventions.
  • Ensure all code is formatted with rustfmt.
  • Ensure no warnings are generated by clippy.
  • Add documentation comments for public APIs.

Testing

Catenary uses a mix of unit tests and integration tests.

  • Unit Tests: Located in the same file as the code (e.g., src/lib.rs).
  • Integration Tests: Located in tests/. These spawn real LSP servers (like rust-analyzer or bash-language-server). Ensure you have the necessary tools installed if you are modifying relevant tests.

Local Development & Testing

To test your changes end-to-end with Claude Code or Gemini CLI without publishing to a marketplace:

1. Build Catenary

Build the release binary:

cargo build --release

The binary will be located at target/release/catenary.

2. Install Plugin/Extension

Catenary ships plugin/extension manifests for both Claude Code and Gemini CLI. These bundle hooks for editing enforcement, command filtering, and agent lifecycle tracking, plus an MCP connection for session management and workspace root discovery.

Claude Code

# Install as a local marketplace plugin
/plugin marketplace add /path/to/Catenary
/plugin install catenary@catenary

The plugin includes:

  • MCP connection for session management and root discovery
  • PreToolUse hook — editing state enforcement and command filtering
  • Lifecycle hooks — session start/end, turn tracking, agent stop

Gemini CLI

# Link the local extension for development
gemini extensions link /path/to/Catenary

The extension includes:

  • MCP connection for session management and root discovery
  • BeforeTool hook — editing state enforcement and command filtering
  • Lifecycle hooks — session start/end, turn tracking, agent stop

3. Iterate

After making changes, rebuild and reinstall:

cargo install --path .

This places the updated binary at ~/.cargo/bin/catenary. Restart your Claude Code or Gemini CLI session to pick up the new binary.

If you change hook definitions in plugins/catenary/hooks/hooks.json or hooks/hooks.json, run catenary doctor to check whether the installed hooks match the new definitions:

Hooks:
  Claude Code 1.3.6 (directory) ✗ stale hooks (reinstall: claude plugin uninstall catenary@catenary && claude plugin install catenary@catenary)
  Gemini CLI  1.3.6 (linked)    ✓ hooks match

Reinstall the plugin/extension as indicated to pick up the new hooks.

Licensing and Copyright

Catenary is dual-licensed.

By contributing to Catenary, you agree that your contributions will be licensed under its GNU Affero General Public License v3.0 (or later).

Additionally, by submitting a Pull Request, you grant Mark Wells Dev a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute your contributions and such derivative works under the project's licenses (including the Commercial License).

This ensures the project can remain sustainable and legally sound while staying open source.