|
| 1 | +# Contributing to LocalPibox |
| 2 | + |
| 3 | +LocalPibox is a personal, local-first AI devstack on |
| 4 | +[Pi.dev](https://pi.dev). The stack is designed to be **forked and |
| 5 | +personalized** — you are welcome to contribute directly, fork it for your own |
| 6 | +stack, or share what works on your hardware. |
| 7 | + |
| 8 | +There are **three ways to get involved**: |
| 9 | + |
| 10 | +--- |
| 11 | + |
| 12 | +## 1. Contribute directly |
| 13 | + |
| 14 | +Improve patches, add features, or fix bugs in any of the repos. Each repository |
| 15 | +has its own scope: |
| 16 | + |
| 17 | +| Repo | What to work on | |
| 18 | +|---|---| |
| 19 | +| [devstack](https://github.com/localpibox/devstack) | Container image (`Dockerfile`), `lpb` launcher (`scripts/`), entrypoints (`support/`), CI | |
| 20 | +| [config](https://github.com/localpibox/config) | Pi settings, MCP servers, custom skills, subagents presets | |
| 21 | +| [pi](https://github.com/localpibox/pi) | Qwen `reasoning_effort` + context-overflow patches (fork) | |
| 22 | +| [lemonade-pi-plugin](https://github.com/localpibox/lemonade-pi-plugin) | Qwen thinking + vision support (fork) | |
| 23 | +| [pi-subagents](https://github.com/localpibox/pi-subagents) | Centralized subagent model registry (fork) | |
| 24 | +| [lpb-memory](https://github.com/localpibox/lpb-memory) | Persistent memory / session search extension | |
| 25 | +| [localpibox](https://github.com/localpibox/localpibox) | Project overview & stack reference | |
| 26 | +| [localpibox.github.io](https://github.com/localpibox/localpibox.github.io) | GitHub Pages project site | |
| 27 | + |
| 28 | +### Process |
| 29 | + |
| 30 | +1. Fork the repo and create a feature branch off its stable branch |
| 31 | + (`main` for own repos, `lpb` for forks). |
| 32 | +2. Make focused changes. **Prefer minimal, targeted patches** over broad |
| 33 | + rewrites. |
| 34 | +3. For forks, keep work as a **single squashed commit** on `lpb` so the delta |
| 35 | + vs upstream stays one clean patch. |
| 36 | +4. Open a PR. Describe what changed, why, and how you tested it. |
| 37 | + |
| 38 | +### Policy notes |
| 39 | + |
| 40 | +- **Never hardcode model names in agent defaults** — use `model: parent` so |
| 41 | + agents inherit the session model. See the config repo's `agents/` templates. |
| 42 | +- **Anthropic models are not used** in this stack; Qwen (via Lemonade) is the |
| 43 | + default. |
| 44 | +- Forks carry candidate **upstream contributions**: ship a patch upstream when |
| 45 | + it's generally useful and not too opinionated for this stack. |
| 46 | + |
| 47 | +## 2. Fork for your stack |
| 48 | + |
| 49 | +1. Fork the repos you care about. |
| 50 | +2. Clone devstack and edit `lpb.stack.env` to point at your forks (see |
| 51 | + [Forking & Repointing](https://github.com/localpibox/devstack#forking--repointing)). |
| 52 | +3. Build & push your image, then run `lpb`. |
| 53 | + |
| 54 | +You own your variant — change anything: image names, container name, branch |
| 55 | +refs, config preset. |
| 56 | + |
| 57 | +## 3. Feed back experiences |
| 58 | + |
| 59 | +Share what works reliably on **your hardware with your models**. Configuration |
| 60 | +like context-window ratios, thinking levels, and model detection depends |
| 61 | +heavily on the actual host (CPU/APU, RAM, model size). Your findings help |
| 62 | +everyone converge on robust local setups. |
| 63 | + |
| 64 | +Open an issue or PR with: |
| 65 | +- Your hardware (e.g. "Ryzen AI Max+ 395, 128 GB"). |
| 66 | +- The model + provider + Pi version. |
| 67 | +- What worked, what overflowed, and any tuning you discovered. |
| 68 | + |
| 69 | +--- |
| 70 | + |
| 71 | +## Reporting issues |
| 72 | + |
| 73 | +Open an issue in the relevant repo (usually `devstack`). Include: |
| 74 | + |
| 75 | +- What you were doing. |
| 76 | +- Exact command(s) and output. |
| 77 | +- Host OS, container engine (podman/docker), and stack version (from |
| 78 | + `VERSION` / `lpb.conf.env`). |
| 79 | + |
| 80 | +## Code of conduct |
| 81 | + |
| 82 | +Keep it friendly and constructive — this is a personal stack shared in public. |
| 83 | +Respect other people's hardware, models, and workflows. |
0 commit comments