Skip to content
This repository was archived by the owner on Aug 17, 2026. It is now read-only.

Commit 4153dfe

Browse files
authored
chore(grunt): add GRUNTCODE.md — fork identity + rebase workflow (#1)
This is the first commit on top of upstream/dev establishing grunt-it/gruntcode as a soft-fork of anomalyco/opencode. GRUNTCODE.md documents: - What's different from opencode (the 4-patch series tracked in hivemind anomalyco#222) - Why we forked (need patches now, brand identity, parallel upstreaming) - Stability promise (track upstream weekly, no independent feature work) - Install path (homebrew tap, source build) - Maintainer rebase workflow The existing README.md is UNTOUCHED — it stays upstream-aligned so rebases don't pointlessly conflict. GRUNTCODE.md is the grunt-it-specific layer. Refs hivemind anomalyco#222.
1 parent 922903e commit 4153dfe

1 file changed

Lines changed: 95 additions & 0 deletions

File tree

‎GRUNTCODE.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
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

Comments
 (0)