|
| 1 | +# gruntcode — grunt-it soft-fork of opencode |
| 2 | + |
| 3 | +**gruntcode is a soft-fork of [anomalyco/opencode](https://github.com/anomalyco/opencode) maintained by [grunt-it](https://github.com/grunt-it).** It exists to layer hivemind-native autonomous-coordination behavior on top of opencode without waiting for upstream review cycles. |
| 4 | + |
| 5 | +## What's different from opencode |
| 6 | + |
| 7 | +The only changes from upstream are a small, deliberately-scoped patch series that makes opencode work better with [hivemind-mcp](https://github.com/grunt-it/hivemind-mcp) — grunt-it's shared coordination MCP for parallel agent sessions. |
| 8 | + |
| 9 | +Current patches (each tracked in [hivemind #222](https://github.com/grunt-it/hivemind-mcp)): |
| 10 | + |
| 11 | +1. **Auto-announce-at-session-start.** TUI sessions automatically register themselves on the hivemind peer registry. No `hivemind_announce` TAKEOFF call needed. |
| 12 | +2. **Attach subscribes to all session message updates.** When a wake fires via `/session/<id>/prompt_async`, the attach-client TUI renders the response. (Without this patch, externally-triggered messages land in the server's db but never reach the user's screen.) |
| 13 | +3. **`OPENCODE_SERVER_URL` propagation.** The attach binary reads and propagates this env var to all subprocesses (MCP children, etc.) so agents can find their serve daemon without a launch-script shim. |
| 14 | +4. **`--peer-id <id>` flag.** Lets launch scripts set the tab's hivemind peer-id at startup instead of via TAKEOFF gymnastics. Powers patch #1. |
| 15 | + |
| 16 | +Everything else is opencode upstream. We rebase against `anomalyco/opencode:dev` weekly. |
| 17 | + |
| 18 | +## Why a fork, not upstreaming? |
| 19 | + |
| 20 | +We upstream each patch as a PR in parallel. The fork exists because: |
| 21 | + |
| 22 | +- We need these patches *now* for the grunt-it autonomous-coordinator vision (the hivemind UI + multi-tab coordinator workflows depend on them) |
| 23 | +- Upstream's contribution guidelines reasonably require design review for "core" changes; we don't want to wait |
| 24 | +- Branding helps signal that hivemind <-> coding-agent integration is a grunt-it product, not just a config layer on top of someone else's tool |
| 25 | + |
| 26 | +If upstream accepts a patch, we drop it on next rebase. The fork shrinks over time. |
| 27 | + |
| 28 | +## Stability and support |
| 29 | + |
| 30 | +**gruntcode tracks opencode upstream.** If you don't need hivemind integration, install [opencode](https://opencode.ai) directly — it's the same binary minus our four patches. |
| 31 | + |
| 32 | +We do NOT promise: |
| 33 | +- API stability beyond what opencode itself promises |
| 34 | +- Independent feature work on top of opencode's TUI / agents / providers |
| 35 | +- Backports of opencode bugfixes (you get them on next rebase, typically within a week) |
| 36 | + |
| 37 | +We DO promise: |
| 38 | +- The four hivemind-integration patches stay working as long as the hivemind-mcp tools they target stay working |
| 39 | +- Weekly rebase on upstream `dev` |
| 40 | +- Tagged releases as `vX.Y.Z-grunt.N` where `X.Y.Z` is the upstream version we rebased on |
| 41 | + |
| 42 | +## Installation |
| 43 | + |
| 44 | +```sh |
| 45 | +brew install grunt-it/tap/gruntcode |
| 46 | +``` |
| 47 | + |
| 48 | +Or build from source: |
| 49 | + |
| 50 | +```sh |
| 51 | +git clone https://github.com/grunt-it/gruntcode.git |
| 52 | +cd gruntcode |
| 53 | +bun install |
| 54 | +bun run --cwd packages/opencode src/index.ts --help |
| 55 | +``` |
| 56 | + |
| 57 | +## Contributing |
| 58 | + |
| 59 | +For patches that should land in **opencode upstream**: open the PR there directly. We'll see it and drop our equivalent on next rebase. |
| 60 | + |
| 61 | +For patches that are **gruntcode-specific** (i.e. hivemind-integration only, not general opencode improvements): open a PR against `grunt-it/gruntcode:dev`. We keep our patch series tiny — please discuss in [hivemind #222](https://github.com/grunt-it/hivemind-mcp) before opening a large change. |
| 62 | + |
| 63 | +For everything else: use upstream opencode. |
| 64 | + |
| 65 | +## Rebase workflow (maintainer notes) |
| 66 | + |
| 67 | +Each grunt-it patch lives as a single commit on top of upstream `dev`. The history looks like: |
| 68 | + |
| 69 | +``` |
| 70 | +upstream/dev |
| 71 | +├── upstream commits (we rebase on these) |
| 72 | +└── grunt-it patches (cherry-picked on top, one commit each) |
| 73 | + ├── chore(grunt): branding (README, GRUNTCODE.md, etc.) |
| 74 | + ├── feat(grunt): --peer-id flag (#222 patch 4) |
| 75 | + ├── feat(grunt): OPENCODE_SERVER_URL propagation (#222 patch 3) |
| 76 | + ├── feat(grunt): attach subscribes to all session updates (#222 patch 2) |
| 77 | + └── feat(grunt): auto-announce-at-session-start (#222 patch 1) |
| 78 | +``` |
| 79 | + |
| 80 | +Weekly rebase: |
| 81 | + |
| 82 | +```sh |
| 83 | +git fetch upstream |
| 84 | +git rebase upstream/dev |
| 85 | +# resolve conflicts patch-by-patch |
| 86 | +git push --force-with-lease origin dev |
| 87 | +``` |
| 88 | + |
| 89 | +If a grunt-it patch lands upstream, drop it from the rebase chain (it's now part of the upstream commit set). |
| 90 | + |
| 91 | +If a grunt-it patch conflicts non-trivially: file as a hivemind sub-ticket of #222, decide whether to update the patch or drop it. |
| 92 | + |
| 93 | +## License |
| 94 | + |
| 95 | +Same as upstream: [MIT](./LICENSE). |
0 commit comments