Contributing to PicoClaw

Thank you for your interest in contributing to PicoClaw! This project is a community-driven effort to build the lightweight and versatile personal AI assistant. We welcome contributions of all kinds: bug fixes, features, documentation, translations, and testing. PicoClaw itself was substantially developed with AI assistance — we embrace this approach and have built our contribution process around it.

Ways to Contribute

Bug Reports

Open an issue using the bug report template

Feature Requests

Open an issue using the feature request template; discuss before implementing

Code Contributions

Fix bugs or implement features following our workflow

Documentation

Improve READMEs, docs, inline comments, or translations

Testing

Run PicoClaw on new hardware, channels, or LLM providers and report results

For substantial new features, please open an issue first to discuss the design before writing code. This prevents wasted effort and ensures alignment with the project’s direction.

Getting Started

Fork and Clone

Fork the repository on GitHub
Clone your fork locally:

git clone https://github.com/<your-username>/picoclaw.git
cd picoclaw

Add the upstream remote:

git remote add upstream https://github.com/sipeed/picoclaw.git

Development Setup

Prerequisites

Go 1.25 or later
make

Build Commands

make build       # Build binary (runs go generate first)
make generate    # Run go generate only
make check       # Full pre-commit check: deps + fmt + vet + test

Running Tests

make test                                    # Run all tests
go test -run TestName -v ./pkg/session/      # Run a single test
go test -bench=. -benchmem -run='^$' ./...  # Run benchmarks

Code Style

make fmt   # Format code
make vet   # Static analysis
make lint  # Full linter run

All CI checks must pass before a PR can be merged. Run make check locally before pushing to catch issues early.

Making Changes

Branching Strategy

Always branch off main and target main in your PR. Never push directly to main or any release/* branch:

git checkout main
git pull upstream main
git checkout -b your-feature-branch

Use descriptive branch names:

fix/telegram-timeout
feat/ollama-provider
docs/contributing-guide

Commit Guidelines

Write clear, concise commit messages in English
Use the imperative mood: “Add retry logic” not “Added retry logic”
Reference the related issue when relevant: Fix session leak (#123)
Keep commits focused - one logical change per commit
For minor cleanups or typo fixes, squash them into a single commit before opening a PR
Refer to Conventional Commits

Keeping Up to Date

Rebase your branch onto upstream main before opening a PR:

git fetch upstream
git rebase upstream/main

AI-Assisted Contributions

PicoClaw was built with substantial AI assistance, and we fully embrace AI-assisted development. However, contributors must understand their responsibilities when using AI tools.

Disclosure Is Required

Every PR must disclose AI involvement using the PR template’s 🤖 AI Code Generation section:

Level	Description
🤖 Fully AI-generated	AI wrote the code; contributor reviewed and validated it
🛠️ Mostly AI-generated	AI produced the draft; contributor made significant modifications
👨‍💻 Mostly Human-written	Contributor led; AI provided suggestions or none at all

Honest disclosure is expected. There is no stigma attached to any level — what matters is the quality of the contribution.

You Are Responsible for What You Submit

Using AI to generate code does not reduce your responsibility as the contributor. Before opening a PR with AI-generated code, you must:

Read and Understand

Read and understand every line of the generated code

Test Thoroughly

Test it in a real environment (see the Test Environment section of the PR template)

Security Review

Check for security issues — AI models can generate subtly insecure code (e.g., path traversal, injection, credential exposure)

Verify Correctness

Validate the behavior, not just the syntax. AI-generated logic can be plausible-sounding but wrong

PRs where it is clear the contributor has not read or tested the AI-generated code will be closed without review.

AI-Generated Code Quality Standards

AI-generated contributions are held to the same quality bar as human-written code:

Must pass all CI checks (make check)
Must be idiomatic Go and consistent with the existing codebase style
Must not introduce unnecessary abstractions, dead code, or over-engineering
Must include or update tests where appropriate

Security Review

AI-generated code requires extra security scrutiny. Pay special attention to:

File path handling and sandbox escapes
External input validation in channel handlers and tool implementations
Credential or secret handling
Command execution (exec.Command, shell invocations)

If you are unsure whether a piece of AI-generated code is safe, say so in the PR — reviewers will help.

Pull Request Process

Before Opening a PR

Run make check and ensure it passes locally
Fill in the PR template completely, including the AI disclosure section
Link any related issue(s) in the PR description
Keep the PR focused - avoid bundling unrelated changes together

PR Template Sections

The PR template asks for:

Description — What does this change do and why?
Type of Change — Bug fix, feature, docs, or refactor
AI Code Generation — Disclosure of AI involvement (required)
Related Issue — Link to the issue this addresses
Technical Context — Reference URLs and reasoning (skip for pure docs PRs)
Test Environment — Hardware, OS, model/provider, and channels used for testing
Evidence — Optional logs or screenshots demonstrating the change works
Checklist — Self-review confirmation

PR Size

Prefer small, reviewable PRs. A PR that changes 200 lines across 5 files is much easier to review than one that changes 2000 lines across 30 files.

If your feature is large, consider splitting it into a series of smaller, logically complete PRs.

Branch Strategy

Long-Lived Branches

main — the active development branch. All feature PRs target main. The branch is protected: direct pushes are not permitted, and at least one maintainer approval is required before merging.
release/x.y — stable release branches, cut from main when a version is ready to ship. These branches are more strictly protected than main.

Requirements to Merge into `main`

A PR can only be merged when all of the following are satisfied:

CI passes — All GitHub Actions workflows (lint, test, build) must be green
Reviewer approval — At least one maintainer has approved the PR
No unresolved review comments — All review threads must be resolved
PR template is complete — Including AI disclosure and test environment

Who Can Merge

Only maintainers can merge PRs. Contributors cannot merge their own PRs, even if they have write access.

Merge Strategy

We use squash merge for most PRs to keep the main history clean and readable. Each merged PR becomes a single commit referencing the PR number:

feat: Add Ollama provider support (#491)

If a PR consists of multiple independent, well-separated commits that tell a clear story, a regular merge may be used at the maintainer’s discretion.

Release Branches

When a version is ready, maintainers cut a release/x.y branch from main. After that point:

New features are not backported — The release branch receives no new functionality after it is cut
Security fixes and critical bug fixes are cherry-picked — If a fix in main qualifies (security vulnerability, data loss, crash), maintainers will cherry-pick the relevant commit(s) onto the affected release/x.y branch and issue a patch release

If you believe a fix in main should be backported to a release branch, note it in the PR description or open a separate issue. The decision rests with the maintainers.

Code Review

For Contributors

Respond to review comments within a reasonable time. If you need more time, say so
When you update a PR in response to feedback, briefly note what changed (e.g., “Updated to use sync.RWMutex as suggested”)
If you disagree with feedback, engage respectfully. Explain your reasoning; reviewers can be wrong too
Do not force-push after a review has started — it makes it harder for reviewers to see what changed. Use additional commits instead; the maintainer will squash on merge

For Reviewers

Review for:

Correctness — Does the code do what it claims? Are there edge cases?
Security — Especially for AI-generated code, tool implementations, and channel handlers
Architecture — Is the approach consistent with the existing design?
Simplicity — Is there a simpler solution? Does this add unnecessary complexity?
Tests — Are the changes covered by tests? Are existing tests still meaningful?

Be constructive and specific. “This could have a race condition if two goroutines call this concurrently — consider using a mutex here” is better than “this looks wrong”.

Reviewer List

Once your PR is submitted, you can reach out to the assigned reviewers:

Function	Reviewer
Provider	@yinwm
Channel	@yinwm/@alexhoshina
Agent	@lxowalle/@Zhaoyikaiii
Tools	@lxowalle
Skill
MCP
Optimization	@lxowalle
Security
AI CI	@imguoguo
UX
Document

Communication

GitHub Issues

Bug reports, feature requests, design discussions

GitHub Discussions

General questions, ideas, community conversation

Pull Request Comments

Code-specific feedback

Discord & WeChat

We will invite you when you have at least one merged PR

When in doubt, open an issue before writing code. It costs little and prevents wasted effort.

A Note on the Project’s AI-Driven Origin

PicoClaw’s architecture was substantially designed and implemented with AI assistance, guided by human oversight. If you find something that looks odd or over-engineered, it may be an artifact of that process — opening an issue to discuss it is always welcome. We believe AI-assisted development done responsibly produces great results. We also believe humans must remain accountable for what they ship. These two beliefs are not in conflict. Thank you for contributing!

Contributing

​Ways to Contribute

Bug Reports

Feature Requests

Code Contributions

Documentation

Testing

​Getting Started

​Fork and Clone

​Development Setup

​Prerequisites

​Build Commands

​Running Tests

​Code Style

​Making Changes

​Branching Strategy

​Commit Guidelines

​Keeping Up to Date

​AI-Assisted Contributions

​Disclosure Is Required

​You Are Responsible for What You Submit

​AI-Generated Code Quality Standards

​Security Review

​Pull Request Process

​Before Opening a PR

​PR Template Sections

​PR Size

​Branch Strategy

​Long-Lived Branches

​Requirements to Merge into main

​Who Can Merge

​Merge Strategy

​Release Branches

​Code Review

​For Contributors

​For Reviewers

​Reviewer List

​Communication

GitHub Issues

GitHub Discussions

Pull Request Comments

Discord & WeChat

​A Note on the Project’s AI-Driven Origin

Build docs developers (and LLMs) love

Ways to Contribute

Getting Started

Fork and Clone

Development Setup

Prerequisites

Build Commands

Running Tests

Code Style

Making Changes

Branching Strategy

Commit Guidelines

Keeping Up to Date

AI-Assisted Contributions

Disclosure Is Required

You Are Responsible for What You Submit

AI-Generated Code Quality Standards

Security Review

Pull Request Process

Before Opening a PR

PR Template Sections

PR Size

Branch Strategy

Long-Lived Branches

Requirements to Merge into `main`

Who Can Merge

Merge Strategy

Release Branches

Code Review

For Contributors

For Reviewers

Reviewer List

Communication

A Note on the Project’s AI-Driven Origin