Repository navigation
docs: new-user onboarding path, Node 20 floor, neutral examples - #135
Conversation
Fixes the nine items from @Hermes's new-user review of main f68dec4: - README opens with a Quick Start (key, room, install, the config fields, rooms watch, first message), then Install; the v0.10.x release notes move below the setup path. - npm install -g is marked stale (npm has 0.2.0); git clone is the manual path. Nothing is published. - Node floor unified at 20: engines >=20 (was >=18), README matches the installer. The test suite needs 20.11+ (mock.timers option object) and Node 18 is end-of-life. - Key acquisition: README and installer point at the signed-in groupmind.one/agents flow and the self-register docs; README links docs/AGENT-ONBOARDING.md and docs/phone-first-setup.md. - Neutral examples (my-room, @myagent, YOUR_AGENT_KEY) in README, example configs, CLI help, UIK docs and the flow example; the License section links this repo, not team-relay. Runtime fallbacks in room-poll-check.py are unchanged and documented as the maintainers' own. - One key placeholder; real format stated (antfarm_ + 64 hex, older xfb_). The enrichment curl uses X-API-Key, as the intent API expects. - "142 tests" dropped; Tests section says npm test runs the suite. - install.sh header now names both listeners the starter config writes (127.0.0.1:8787 webhook, 0.0.0.0:8788 confirmations). - Three dead in-page anchors fixed (#quick-start, #gemini--antigravity, #whats-new-in-v070). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c39a134f8c
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| 3. **Install** (macOS/Linux, Node.js 20+, npm, git, tmux): `curl -fsSL https://raw.githubusercontent.com/ThinkOffApp/ide-agent-kit/main/scripts/install.sh | bash` | ||
| 4. **Fill the two fields the installer names** in `~/ide-agent-kit/ide-agent-kit.json`: `poller.api_key` (your key) and `mcp.confirmations.room` (`my-room`). Re-run the installer: the daemon starts and approval cards can reach your phone. | ||
| 5. **Let your agent hear the room:** also set `poller.rooms` (`["my-room"]`) and `poller.handle` (`@myagent`), then run `node bin/cli.mjs rooms watch` from `~/ide-agent-kit`. | ||
| 6. **See it work:** open a Claude Code session (the installer wired its hooks), then post `@myagent hello` in the room at [groupmind.one](https://groupmind.one) or in CodeWatch. The message reaches the session and your agent answers in the room. |
There was a problem hiding this comment.
On a clean install, the message can reach Claude through the installed hooks, but the agent cannot send the promised room reply: scripts/claudecode-stop-resume.sh directs it to mcp__ide-agent-kit__room_post, while scripts/install.sh never registers bin/iak-mcp.mjs with Claude Code and the rooms CLI only implements check and watch. Add MCP registration to the installer/Quick Start (or another configured posting path) before using this as the final verification step.
Useful? React with 👍 / 👎.
| git clone https://github.com/ThinkOffApp/ide-agent-kit.git ~/ide-agent-kit | ||
| ``` | ||
| ```bash | ||
| cd ~/ide-agent-kit && npm install |
There was a problem hiding this comment.
When a user chooses this new manual path, npm install only installs dependencies and does not put this package's own ide-agent-kit binary on PATH. Consequently later instructions such as ide-agent-kit init --ide claude-code fail with command-not-found for precisely these users; include an npm link/equivalent step or consistently tell manual users to invoke node bin/cli.mjs.
Useful? React with 👍 / 👎.
Fixes the nine items in @Hermes's new-user review of
mainat f68dec4. I checked each item against the code before changing anything. Where hermes's claim turned out only partly right, that is noted under the item.The nine items
npm install -g ide-agent-kit, but npm has an old versionnpm view ide-agent-kit versionsreturns["0.2.0"], whilepackage.jsonis 0.10.1. The primary install is now the installer. The manual path isgit clone+npm install, which is whatinstall.shitself does. The npm line is marked stale until a current version is published. Nothing was published and nobody logged in to npm.>=18, installerNODE_MIN_MAJOR=20AbortSignal.timeoutneeds 17.3 andutil.parseArgsneeds 18.3. The test suite does not:packages/user-intent-kit/test/state-publisher.test.jscallst.mock.timers.enable({ apis: [...] }), and the option-object form was added in Node v21.2.0/v20.11.0 (nodejs.org/api/test.html history table). Node 18 reached end-of-life on 2025-04-30 and Node 20 on 2026-04-30 (nodejs/Releaseschedule.json). The floor is now 20: engines>=20, and the README matches the installer. The README recommends 22+, which is the installer's default. Negative control: a stubnodethat printsv18.19.1makes the installer dry-run planbrew install node.#quick-start, but no such section existsrooms watch, first message. It is honest that hearing the room needspoller.rooms+poller.handle+rooms watchas well as the two daemon fields, because the daemon alone only handles approval cards. I verified on a fresh install thatrooms watchand the daemon both refuse, with clear errors, until those fields are set.groupmind.one/agents"+ Add agent" flow and the no-sign-inPOST /api/v1/agents/registerflow, and linksdocs/AGENT-ONBOARDING.md#1-mint-the-agents-own-identity.docs/phone-first-setup.mdis linked from the Quick Start. The installer's "EDIT THIS FILE" message now says you must be signed in at groupmind.one/agents, or points to the self-register section ofdocs/AGENT-ONBOARDING.md.AGENT-ONBOARDING.mdtold readers to copyconfig/dogfood.json, which is not in a clone; it now points toconfig/grok.example.jsonor the installer's config.my-room/@myagent/@mycodex/your-username/your_user_id: README examples,config/codex.desktop.example.json,config/grok.example.json,config/models.example.json, the CLI help examples inbin/cli.mjs,docs/AGENT-ONBOARDING.md, the UIK READMEs and examples, andexamples/flow-pr-opened.md. That last file also used ateam-relayCLI that does not exist; it now useside-agent-kit. The License section now links this repo instead ofThinkOffApp/team-relay@be641cf. Not changed: the env fallbacks inscripts/room-poll-check.py(rooms,@claudemm,petrus) andtools/*_autopost.sh. Existing deployments may rely on them, and I could not check the Mac mini from here. The README tables now label them as the maintainers' own fallbacks and say to always set them. The config-drivenrooms watchhas no such fallbacks. Also left alone as historical or internal: CHANGELOG,docs/task-lifecycle.md,docs/auto-wake.md(which describes the realclaudemb-*scripts),CHAT_RULES.md,skills/*, and the dated verification record under "Verify Enrichment".xfb_xxxvsgroupmind_xxx)antfarm_followed by 64 hex characters. Sources: groupmind.one/skill.md shows the register response"api_key": "antfarm_xxx...", and a live key was checked by regex only, never printed. There is now one placeholder,YOUR_AGENT_KEY, in the README,docs/, example configs and UIK docs. The real format is stated in the Quick Start and in AGENT-ONBOARDING (older keys startxfb_). Also fixed: the "Verify Enrichment" curl sentAuthorization: Bearer, but the intent API expectsX-API-Key(CHANGELOG 0.9.0).npm testruns the IAK and embedded UIK suites and needs Node 20.11+. Current total: see Tests below.install.shheader claims 8788 / 0.0.0.0, but the config writes 127.0.0.1:8787listenon 127.0.0.1:8787 (webhook server, local) andmcp.confirmationson 0.0.0.0:8788 (LAN, for CodeWatch). The old comment named only the second one. It now names both.Checks
#anchorfrom the markdown (skipping code fences) and checks each target file exists and each anchor matches a heading under GitHub's slug rules. A negative control plants two broken links in a test file, and both are caught. Result: README,docs/AGENT-ONBOARDING.md,docs/phone-first-setup.mdandexamples/flow-pr-opened.mdhave 49 links checked, 0 broken. Onmainthe README had 3 broken anchors:#quick-start,#gemini--antigravityand#whats-new-in-v070. Second instrument: I rendered the README through GitHub's/markdownAPI and slugged the rendered headings. Result: 34 in-page hrefs, 0 unresolved. The first rendered<h2>is Quick Start.bash -n scripts/install.shpasses.IAK_DRY_RUN=1underHOME=$(mktemp -d)exits 0 and leaves the fake HOME empty. I also ran it fully under a fake HOME, with a unique tmux session name and the install dir inside the fake HOME. It reached "Installed.", wrote the starter config, created the hooks, and printed the new key pointer androoms watchlines. The daemon exited as expected because the config was empty.node scripts/check-stageable-secrets.mjs: PASS.Tests
npm teston this branch (MacBook, macOS), run after the final commit:node): 814 tests, 814 pass, 0 fail, 0 cancelled, 0 skipped/opt/homebrew/opt/node@22): 814 tests, 814 pass, 0 failorigin/mainf68dec4 on Node 26: 814 / 814 passThe 5 model-tidy failures expected on macOS did not reproduce on this machine: 0 failures on both runs. Hermes's "655" was an earlier count.
node --testreports 650 top-level entries and 814 tests in total.Left for petrus
scripts/room-poll-check.py/tools/*_autopost.shand make those vars required (item 5). That is a behaviour change for any deployment relying on them.🤖 Generated with Claude Code