merakcode 0.1.0 → 0.1.1

package/LICENSE

@@ -19,9 +19,3 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
-
----
-
-Parts of this software are derived from other open-source projects, most notably
-opencode (https://github.com/anomalyco/opencode), Copyright (c) 2025 opencode, MIT License.
-See THIRD_PARTY_NOTICES.md for their copyright notices and licenses.

package/README.md

@@ -10,14 +10,15 @@
   <a href="https://github.com/TongTong313/merakcode/actions/workflows/ci.yml"><img src="https://github.com/TongTong313/merakcode/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
   <a href="https://github.com/TongTong313/merakcode/releases"><img src="https://img.shields.io/github/v/release/TongTong313/merakcode?include_prereleases" alt="Release" /></a>
   <a href="https://www.npmjs.com/package/merakcode"><img src="https://img.shields.io/npm/v/merakcode" alt="npm" /></a>
-  <a href="LICENSE"><img src="https://img.shields.io/github/license/TongTong313/merakcode" alt="License" /></a>
+  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D26.12-339933?logo=nodedotjs&logoColor=white" alt="Node.js" /></a>
+  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-7.0-3178C6?logo=typescript&logoColor=white" alt="TypeScript" /></a>
 </p>
 
 <p align="center"><a href="README.md">简体中文</a> · English</p>
 
 ---
 
-MerakCode is an open-source AI coding tool. Beyond strong coding skills, it can help with anything you need AI for. AI now writes far faster than people can read, so MerakCode puts a lot of care into how people and the agent work together: a better way to review what the agent produces and a smoother experience overall, so that its output is what you expect.
+MerakCode is an open-source AI coding tool. Beyond strong coding skills, it can help with anything you need AI for. Now that AI writes far faster than people can read, MerakCode puts a lot of care into how people and the agent work together. Collaboration groups let Claude Code, Codex, OpenCode and other products work together, and MerakCode keeps refining how you review what the agent produces, so that its output is what you expect. The aim is to be the best AI coding tool to use, not the most powerful one.
 
 We open-sourced this project to make up for a regret we have carried, and in the hope that the community can keep it going. The name comes from Merak, the star in the Big Dipper that, together with Dubhe, points to Polaris. We hope MerakCode does the same and points each of your ideas in the right direction.
 
@@ -26,7 +27,7 @@ We open-sourced this project to make up for a regret we have carried, and in the
 - **AI coding**: strong project-level coding across many languages, frameworks, paradigms and styles. Honestly, this part is no different from other AI coding products. You be the judge, and if you like it, a Star is the best way to support us.
 - **Collaboration across products**: MerakCode is designed around people and the agent working together. It has a review interface built specifically for checking what the agent produces (desktop app only) and a complete permission system for what the agent may do. It can also work alongside other AI coding products that ship a CLI, so the collaboration reaches across products.
 - **Model setup**: connect all kinds of model providers (only 8 for now, more to come) as well as local models. MerakCode can also use models through API relay services.
-- **Secure and reliable**: commands the agent runs go into our own OS sandbox. They cannot read your key folders, cannot write outside the workspace, and need your approval to reach unfamiliar websites. This is a small product built by a few people, with no server side (no time to build one...). We don't collect, and couldn't collect, any usage data, so there is nothing of yours to leak.
+- **Secure and reliable**: commands the agent runs go into our own OS sandbox. They cannot read key folders such as `~/.ssh` or `~/.aws`, can write only the workspace, temp folders and package manager caches, and need your approval for hosts that are not on the allowlist. This is a small product built by a few people, with no server side (no time to build one...). We don't collect, and couldn't collect, any usage data, so there is nothing of yours to leak.
 - **Extensible**: MCP, skills, plugins, custom agents and slash commands.
 - **Beyond coding**: AI coding is one of the hardest kinds of task there is, so using MerakCode for other things works just fine.
 - **Build your own**: MerakCode ships an agent SDK, and every MerakCode product is built on it. You can build your own AI coding tool on the same engine.
@@ -48,7 +49,9 @@ The desktop app ships with its own engine; you do not need the command-line vers
 The installers are not code-signed yet, so the system stops them the first time:
 
 - **Windows**: when you see "Windows protected your PC", click "More info", then "Run anyway".
-- **macOS**: if the app "cannot be opened", go to System Settings → Privacy & Security and click "Open Anyway" near the bottom. Unsigned macOS builds cannot update themselves; the app tells you when a new version is out and opens the download page.
+- **macOS**: if the app "cannot be opened", go to System Settings → Privacy & Security and click "Open Anyway" near the bottom.
+
+Unsigned macOS builds, and Linux installs from a `.deb`, cannot update themselves. When a new version is out, the app sends you to the download page.
 
 ### Command line
 
@@ -77,10 +80,13 @@ The command is `merak`. Upgrade later with `merak upgrade` (or `merak update`).
 To check a download yourself, put the release's `SHA256SUMS` in the same folder as the file and run:
 
 ```sh
-sha256sum -c SHA256SUMS --ignore-missing          # Linux
-shasum -a 256 -c SHA256SUMS --ignore-missing      # macOS
+sha256sum -c SHA256SUMS --ignore-missing                 # Linux
+grep 'darwin-arm64.tar.gz' SHA256SUMS | shasum -a 256 -c # macOS (Apple silicon)
+grep 'darwin-x64.tar.gz' SHA256SUMS | shasum -a 256 -c   # macOS (Intel)
 ```
 
+The `shasum` that ships with macOS has no `--ignore-missing`, so the commands above check only the line for the file you downloaded.
+
 ```powershell
 # Windows: the output must equal the value on this file's line in SHA256SUMS
 (Get-FileHash .\merakcode-<version>-windows-x64.zip).Hash.ToLower()
@@ -113,6 +119,7 @@ Handy actions (`⌘` on macOS, `Ctrl` on Windows and Linux):
 | --------------------- | ----------------------------------------------------------------------------- |
 | `⌘/Ctrl+K`            | Command palette: search conversation titles, conversation content or commands |
 | `⌘/Ctrl+N`            | New conversation                                                              |
+| `⌘/Ctrl+G`            | New collaboration group                                                       |
 | `⌘/Ctrl+,`            | Open settings                                                                 |
 | `⌘/Ctrl+J`            | Open or close the terminal                                                    |
 | `⌘/Ctrl+B`            | Show or hide the side panel                                                   |
@@ -159,17 +166,24 @@ Editors that speak [ACP](https://agentclientprotocol.com) can use MerakCode as t
 
 ## Permissions and the sandbox
 
-MerakCode edits files and runs commands on your computer, so every action goes through the permission mode first: do it, ask you, or refuse.
+MerakCode edits files and runs commands on your computer, so every action goes through the permission mode first: do it, ask you, or refuse. There is no category called an ordinary file. The rules are:
 
-| Mode          | Good for                              | What happens                                                                                                                                                    |
-| ------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Read-only     | Designs and plans                     | Only reads files and runs read-only commands (such as `git status` or `ls`). No edits, no other commands                                                        |
-| Ask (default) | Everyday work                         | Reads files and edits inside the workspace right away; asks before running commands, editing outside the workspace, reading sensitive files or going online     |
-| Auto          | Large projects, when you trust the AI | Does most things right away; still asks before risky commands (such as `git push` or `sudo`), edits outside the workspace, sensitive files and unknown websites |
+- **Edits inside the workspace.** If no directory or file name on the path relative to the workspace starts with `.`, ask mode and auto mode edit it immediately. If any segment starts with `.` (`.git`, `.github`, `.env`, `src/.hidden/a.ts`), ask mode asks first and auto mode edits it immediately. Read-only mode never edits, and an allow rule in the config cannot override that.
+- **Reads.** A file inside the workspace that is not a secret is read immediately in every mode. A non-secret file outside the workspace asks in read-only and ask mode, and is read immediately in auto mode. Secrets always ask. A secret is a file named `.env`, or `.env.*` other than `.env.example`, `.env.sample`, `.env.template` and `.env.dist`; `id_rsa`, `id_dsa`, `id_ecdsa` or `id_ed25519`, with an optional extra suffix; `credentials` or `credentials.json`; an extension of `.pem`, `.key`, `.p12`, `.pfx`, `.keystore` or `.jks`; or `.npmrc`, `.pypirc`, `.netrc`, `.git-credentials` or `.pgpass`. Files under `.ssh`, `.aws`, `.azure`, `.kube`, `.gnupg`, `.docker`, `.config/gcloud` or `.config/gh` in your home directory count too.
+- **Commands.** Commands that certainly do not change files (`ls`, `git status`, `git diff`, `rg`, and the rest of that fixed list) run in every mode. Anything that might change files counts as a file-changing command. File-changing commands, and `rm`, `rmdir`, `unlink`, `shred`, `git clean`, `git reset --hard` and `find -delete`, are refused in read-only mode, asked about in ask mode, and run immediately in auto mode. Risky commands are refused in read-only mode and asked about in ask and auto mode: `sudo`, `su`, `doas`, `pkexec`, `runas`, `dd` when it does not target a whole disk, `shutdown`, `reboot`, `chown`, and `git push`, `npm publish`, `npm unpublish`, `pnpm publish`, `yarn publish`, `bun publish`, `cargo publish`, `gem push`, `twine upload`, `docker push`, `gh release`, `gh pr`, `helm push`. `rm -rf /` (and the home directory), recursively chmodding those locations to `777`, `mkfs`, `dd` onto a whole disk, `format`, `diskpart` and a fork bomb are refused by default. In ask and auto mode they run only when the config explicitly allows them. In read-only mode an allow rule still does not.
+- **Websites.** The allowlist matches hostnames exactly; a subdomain does not count. These hosts are reached immediately: `registry.npmjs.org`, `registry.yarnpkg.com`, `registry.npmmirror.com`, `cdn.npmmirror.com`, `pypi.org`, `files.pythonhosted.org`, `pypi.tuna.tsinghua.edu.cn`, `crates.io`, `index.crates.io`, `static.crates.io`, `static.rust-lang.org`, `rsproxy.cn`, `proxy.golang.org`, `sum.golang.org`, `goproxy.cn`, `repo.maven.apache.org`, `repo1.maven.org`, `maven.aliyun.com`, `services.gradle.org`, `plugins.gradle.org`, `rubygems.org`, `github.com`, `codeload.github.com`, `objects.githubusercontent.com`, `raw.githubusercontent.com`, `gitlab.com`, `gitee.com`, `mirrors.aliyun.com`, `mirrors.tuna.tsinghua.edu.cn`. Every other host asks, in every mode.
+- **The rest.** Subagents, workflows, scheduled tasks, MCP and tools registered by plugins ask in read-only and ask mode, and run immediately in auto mode. Leaving the sandbox always asks. While the sandbox is not ready, a command that may change things asks even in auto mode. In ask and auto mode, allow and deny rules in the project config override the defaults above. Read-only mode still cannot edit files or run anything except read-only commands.
+- **Collaboration members.** The leader hands a task to a member without asking. When a member (Claude Code, Codex, OpenCode, or a product with a member adapter) wants to edit files, run commands, reach a website or read files, the rules above decide it; what needs asking shows in the approval bar and a member's question in the question box, both naming the member. Members' commands do not run in MerakCode's OS sandbox (Codex runs them in its own sandbox), and a custom product added as a one-shot command never asks: its own settings decide.
 
-Switch modes next to the input in the desktop app, or press `Shift+Tab`. When it asks, you can allow once, allow for this session, always allow (saved to the project config) or deny. By default, commands such as `rm -rf /` or formatting a disk never run, in any mode.
+| Mode          | Good for                              | What happens                                                                                                                                                                                                           |
+| ------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Read-only     | Designs and plans                     | No edits, only read-only commands. Still asks before a non-secret read outside the workspace, a secret, or a host off the allowlist                                                                                    |
+| Ask (default) | Everyday work                         | Edits a workspace file immediately when no path segment starts with `.`. Asks before edits to dot paths, file-changing commands and deletes, reads or edits outside the workspace, secrets, or hosts off the allowlist |
+| Auto          | Large projects, when you trust the AI | Edits inside the workspace (including dot paths), file-changing commands and deletes run immediately. Still asks before writes outside, risky commands, secret reads, hosts off the allowlist, or leaving the sandbox  |
 
-Commands the agent runs also go into an **OS sandbox**: they can only write the workspace, temp folders and package manager caches; they cannot read key folders such as `~/.ssh` or `~/.aws`; they cannot change `.git/hooks` or `.git/config`; and network traffic goes through a local proxy that asks you about sites it has not seen. The sandbox is our own code on top of what each OS provides:
+Switch modes next to the input in the desktop app, or press `Shift+Tab`. When it asks, you can allow once, allow for this session, always allow (saved to the project config) or deny.
+
+Commands the agent runs also go into an **OS sandbox**: they can only write the workspace, temp folders and package manager caches; they cannot read key folders such as `~/.ssh` or `~/.aws`; they cannot change `.git/hooks` or `.git/config`; and network traffic goes through a local proxy that asks you about hosts off the allowlist that you have not approved. The sandbox is our own code on top of what each OS provides:
 
 | System  | Built on                                                      | What you need to do                                                                                                                                |
 | ------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -179,6 +193,31 @@ Commands the agent runs also go into an **OS sandbox**: they can only write the
 
 While the sandbox is not ready (for example before setup on Windows), commands that may change things ask first, even in auto mode. For what the sandbox does and does not protect against, see [SECURITY.md](SECURITY.md).
 
+## Collaboration groups
+
+In a collaboration group MerakCode is the leader, and Claude Code, Codex, OpenCode and other AI coding tools can be members. Say what you want in the group; the leader splits it into tasks for the members, and each replies in the group when it is done.
+
+- Create one from New collaboration group in the sidebar, `⌘/Ctrl+G` or the command palette, or copy the members of an existing group.
+- Mention a member with `@` in the input; rename it or change its role and duty in the member column.
+- What members want to do, and what they ask, shows in the approval bar and the question box, decided by the permission mode you chose.
+- Under Settings › Collaboration, turn products on or off, see their versions and paths and who decides their permissions (MerakCode approves for a product with an adapter; a one-shot command decides itself), and add your own. A CLI older than recommended shows how to upgrade it (`claude update`, `codex update`, `opencode upgrade`) and still works. Recommended: Claude Code 2.1.283, Codex 0.164.0, OpenCode 1.19.4 or later.
+- For an AI coding tool without a built-in adapter, click "Have MerakCode write an adapter to connect your own AI coding tool" under Settings › Collaboration, or ask MerakCode in an ordinary conversation to write and register a member adapter with the adapter generator skill (`adapter-generator`). The skill works from the three built-in adapters: a tool that talks the way one of them does gets a copy of it, changed where it differs; any other gets an adapter written after them. You can also write one yourself with [the member adapter section of the SDK guide](docs/sdk/README.en.md#15-member-adapters-adapter).
+
+Products can also be set in the config:
+
+```jsonc
+{
+  "collaboration": {
+    "products": {
+      // A built-in product needs only the fields you change, such as where its command is or extra arguments
+      "codex": { "command": "/opt/codex/bin/codex", "args": ["-c", "model=\"o3\""] },
+      // Your own adapter
+      "mycli": { "title": "MyCLI", "adapter": "member", "command": "node", "args": ["/path/to/adapter.mjs"] },
+    },
+  },
+}
+```
+
 ## Configuration
 
 | Location                                               | Purpose                                                        |
@@ -202,7 +241,7 @@ Config files can be plain JSON or JSONC with comments. Add `"$schema"` at the to
 }
 ```
 
-To switch to English: in the desktop app, use Settings → General → Language; for the command line, set `"locale": "en-US"` in the config or the environment variable `MERAKCODE_LOCALE=en-US`.
+To change the language: in the desktop app, use Settings → General → Language. On the command line, set `"locale"` in the config (`zh-CN` or `en-US`) or the environment variable `MERAKCODE_LOCALE`.
 
 ## SDK
 
@@ -246,7 +285,7 @@ pnpm hooks:install          # check formatting before each commit
 | Debug the engine           | `node --inspect --import ./script/node/register.mjs apps/cli/src/index.ts serve` |
 | Print detailed logs        | `pnpm dev serve --print-logs --log-level DEBUG`                                  |
 
-**Note**: desktop development reloads the UI as you save and restarts the main process and the engine when their code changes, which makes debugging much easier.
+**Note**: desktop development reloads the UI as you save and restarts the app when main process code changes. Engine changes do not restart anything: use Help › Restart Local Service, and windows reconnect on their own.
 
 `pnpm dev` runs the source directly; there is nothing to build first. Change the code and run it again.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "merakcode",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "MerakCode command line: run tasks, start the engine, ACP for editors",
   "license": "MIT",
   "repository": {
@@ -19,11 +19,11 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "merakcode-darwin-arm64": "0.1.0",
-    "merakcode-darwin-x64": "0.1.0",
-    "merakcode-linux-arm64": "0.1.0",
-    "merakcode-linux-x64": "0.1.0",
-    "merakcode-windows-arm64": "0.1.0",
-    "merakcode-windows-x64": "0.1.0"
+    "merakcode-darwin-arm64": "0.1.1",
+    "merakcode-darwin-x64": "0.1.1",
+    "merakcode-linux-arm64": "0.1.1",
+    "merakcode-linux-x64": "0.1.1",
+    "merakcode-windows-arm64": "0.1.1",
+    "merakcode-windows-x64": "0.1.1"
   }
 }