Contributing to MiniCode

Contributing to MiniCode

Thanks for contributing to MiniCode.

MiniCode welcomes pull requests, but the project has a clear scope: it is meant to stay small, readable, and close in spirit to Claude Code's core design direction.

This document explains the baseline expectations for contributions.

Core Principles

1. Keep the project lightweight

Please avoid introducing overly complex design changes.

MiniCode is intentionally small. New contributions should preserve:

• a compact codebase
• direct control flow
• low conceptual overhead
• easy traceability from user action to model loop, tool call, and UI update

Changes that add large abstractions, deep indirection, or framework-heavy rewrites are usually not a good fit unless they are clearly necessary.

2. Stay aligned with Claude Code's design direction

Because of the nature of this project, new features should remain close to Claude Code's source-level design direction wherever possible.

That does not mean copying everything mechanically. It means:

• prefer similar architectural ideas over unrelated inventions
• preserve the same mental model when adapting a feature
• avoid introducing product behavior that clearly diverges from the Claude Code style without a strong reason

MiniCode is a lightweight adaptation, not an unrelated terminal agent project.

Contribution Expectations

3. Prefer small, incremental changes

PRs should be easy to review.

Please prefer:

• focused changes over broad refactors
• one feature or one fix per PR
• changes that can be explained clearly in a short PR description

If a feature is large, split it into smaller steps whenever possible.

4. Preserve existing interaction patterns

When changing the CLI, TUI, tool loop, permissions, MCP handling, or skills behavior:

• preserve the current user-facing rhythm unless there is a strong reason to change it
• avoid breaking existing commands and workflows
• avoid introducing surprising behavior changes without documenting them

5. Keep safety boundaries intact

MiniCode includes important safety boundaries around:

• file modification review
• path access
• command execution
• approval flow

New contributions should not weaken these boundaries casually.

If a change affects safety behavior, explain it clearly in the PR.

6. Prefer explicitness over cleverness

This project is also meant to be studied.

Please prefer:

• readable code over clever compactness
• explicit data flow over hidden magic
• simple utilities over premature abstraction

If a design is harder to understand, it should also bring clear value.

7. Keep dependencies minimal

Avoid adding new dependencies unless they materially improve the project.

Before adding one, ask:

• can this be done with existing code?
• does the dependency fit the lightweight nature of the project?
• will it make the codebase harder to maintain or understand?

8. Update docs when behavior changes

If a PR changes user-facing behavi