Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
159 lines (121 loc) · 3.99 KB

CONTRIBUTING.md

File metadata and controls

159 lines (121 loc) · 3.99 KB

Contributing to Claude Code Scientist

Thank you for your interest in contributing! This project aims to democratize scientific research by providing autonomous research capabilities to anyone with access to Claude Code.

Ways to Contribute

1. Run Cortex (Self-Improvement Loop)

The most valuable contribution is running the Cortex agent between your research sessions. Cortex analyzes past sessions, diagnoses issues, and generates improvements.

# After finishing a research session:
./session.sh cortex

# When Claude opens, run:
/cortex

Cortex will:

  • Trace what actually happened in prior sessions
  • Identify failure patterns and inadequacies
  • Generate fixes and improvements
  • Commit changes with clear messages

Then submit your improvements as a PR!

2. Report Issues

Found a bug or have a suggestion? Open an issue with:

  • Clear description of the problem
  • Steps to reproduce (if applicable)
  • Session ID or transcript excerpt (if relevant)
  • Expected vs actual behavior

3. Submit Pull Requests

PRs are welcome for:

  • Bug fixes
  • New skills or agents
  • Improved prompts
  • Documentation
  • Test coverage

Development Setup

# Clone the repository
git clone https://github.com/rhowardstone/Claude-Code-Scientist.git
cd Claude-Code-Scientist

# Install dependencies
pip install -e ".[dev]"

# Run tests
python -m pytest tests/ -v

Code Standards

Python Code

  • Follow PEP 8
  • Type hints encouraged (not required)
  • Docstrings for public functions
  • Keep files focused (single responsibility)

CLAUDE.md / Skills / Agents

  • Clear, actionable instructions
  • Document "why" not just "what"
  • Include failure modes and how to handle them
  • Add battle scars to .claude/docs/CORE.md when you learn something

Commit Messages

type: Short description

Longer explanation if needed.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Types: fix, feat, docs, test, refactor, perf

Pull Request Process

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Run tests (python -m pytest tests/ -v)
  5. Commit with clear messages
  6. Push to your fork
  7. Open a PR against main

PR Checklist

  • Tests pass
  • No new pyright errors in changed files
  • Documentation updated if needed
  • No absolute paths or machine-specific config
  • No API keys or secrets committed

Running Research Sessions

Start a New Session

./session.sh new "Your research goal here"
claude

Resume a Session

./session.sh list
./session.sh resume <session_id>
claude

Run Cortex for Self-Improvement

./session.sh cortex
# In Claude:
/cortex

Architecture Overview

Claude Code Scientist
├── .claude/
│   ├── CLAUDE.md        # Research Director prompt
│   ├── agents/          # Specialized subagents
│   ├── skills/          # Orchestration workflows
│   ├── hooks/           # Validation automation
│   ├── rules/           # Conventions
│   └── docs/            # Battle scars, architecture
│
├── craig/               # Python utilities
│   ├── literature/      # Literature search & KG
│   ├── pipeline/        # Phase implementations
│   └── cli/             # Command-line tools
│
├── mcp-servers/         # MCP server for literature
└── workspace/           # Session artifacts (gitignored)

Key Principles

  1. Provenance is everything - Every claim needs DOI + quote + page
  2. No simulation trap - Run actual tools, not simulations
  3. Honesty over completion - Missing evidence > false evidence
  4. Open access only - No SciHub or pirated papers
  5. Local-first - Minimize API calls where possible

Questions?

  • Open an issue for bugs or feature requests
  • Check existing issues before creating new ones
  • Be respectful and constructive

License

By contributing, you agree that your contributions will be licensed under the MIT License.