merakcode 0.1.2 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +110 -74
- package/THIRD_PARTY_NOTICES.md +5 -4
- package/package.json +7 -7
package/README.md
CHANGED
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
<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>
|
|
11
11
|
<a href="https://github.com/TongTong313/merakcode/releases"><img src="https://img.shields.io/github/v/release/TongTong313/merakcode?include_prereleases" alt="Release" /></a>
|
|
12
12
|
<a href="https://www.npmjs.com/package/merakcode"><img src="https://img.shields.io/npm/v/merakcode" alt="npm" /></a>
|
|
13
|
-
<a href="
|
|
13
|
+
<a href="#develop-from-source"><img src="https://img.shields.io/badge/dev%20node-%3E%3D26.12-339933?logo=nodedotjs&logoColor=white" alt="Node.js (development)" /></a>
|
|
14
14
|
<a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-7.0-3178C6?logo=typescript&logoColor=white" alt="TypeScript" /></a>
|
|
15
15
|
</p>
|
|
16
16
|
|
|
@@ -27,7 +27,7 @@ We open-sourced this project to make up for a regret we have carried, and in the
|
|
|
27
27
|
- **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.
|
|
28
28
|
- **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.
|
|
29
29
|
- **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.
|
|
30
|
-
- **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.
|
|
30
|
+
- **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 (on Windows, set it up once in Settings first; collaboration members' commands do not run in it; for what it does and does not guarantee, see [Permissions and the sandbox](#permissions-and-the-sandbox)). 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.
|
|
31
31
|
- **Extensible**: MCP, skills, plugins, custom agents and slash commands.
|
|
32
32
|
- **Beyond coding**: AI coding is one of the hardest kinds of task there is, so using MerakCode for other things works just fine.
|
|
33
33
|
- **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.
|
|
@@ -55,7 +55,7 @@ Unsigned macOS builds, and Linux installs from a `.deb`, cannot update themselve
|
|
|
55
55
|
|
|
56
56
|
### Command line
|
|
57
57
|
|
|
58
|
-
The command-line version has no UI. It is for one-off tasks in a terminal, scripts, and editors (through ACP). It shares its config and keys with the desktop app.
|
|
58
|
+
The command-line version has no UI. It is for one-off tasks in a terminal, scripts, and editors (through ACP). It shares its config and keys with the desktop app. It runs on Linux (x64 and arm64, with glibc; musl systems such as Alpine are not supported yet), macOS (Apple silicon and Intel) and Windows (x64 and arm64).
|
|
59
59
|
|
|
60
60
|
macOS / Linux:
|
|
61
61
|
|
|
@@ -75,9 +75,13 @@ Or with npm (the package brings its own runtime; any Node.js 18 or newer can ins
|
|
|
75
75
|
npm install -g merakcode
|
|
76
76
|
```
|
|
77
77
|
|
|
78
|
-
The command is `merak`. Upgrade later with `merak upgrade` (or `merak update`).
|
|
78
|
+
The command is `merak`. Upgrade later with `merak upgrade` (or `merak update`; `merak upgrade <version>` installs a given version).
|
|
79
79
|
|
|
80
|
-
|
|
80
|
+
- The install script puts the program in `~/.merakcode/versions/<version>/`. On macOS / Linux the command goes in `~/.local/bin/merak` (the script tells you if that is not on your PATH); on Windows it goes in `~\.merakcode\bin`, which is added to your user PATH.
|
|
81
|
+
- For a mirror, the install script and `merak upgrade` read `MERAKCODE_DOWNLOAD_BASE` (where to download from), and upgrades of an npm install read `MERAKCODE_NPM_REGISTRY`. `MERAKCODE_VERSION`, `MERAKCODE_INSTALL_DIR` and `MERAKCODE_BIN_DIR` pick the version and where it goes.
|
|
82
|
+
- If Linux says the bundled Node does not start, libatomic is usually missing: install `libatomic1` on Debian / Ubuntu, or `libatomic` on Fedora / RHEL.
|
|
83
|
+
|
|
84
|
+
To check a command-line archive yourself (`merakcode-<version>-<platform>.tar.gz` or `.zip`; the install scripts already check it for you), put the release's `SHA256SUMS` in the same folder as the archive and run (`SHA256SUMS` lists only the command-line archives, not the desktop installers):
|
|
81
85
|
|
|
82
86
|
```sh
|
|
83
87
|
sha256sum -c SHA256SUMS --ignore-missing # Linux
|
|
@@ -96,16 +100,20 @@ The `shasum` that ships with macOS has no `--ignore-missing`, so the commands ab
|
|
|
96
100
|
|
|
97
101
|
On Windows, if you set up the sandbox, first click "Reset" under Settings → Permissions & security in the desktop app (or run `merak sandbox reset`). It removes the sandbox account and firewall rule and takes back the folder permissions it was given.
|
|
98
102
|
|
|
99
|
-
- Desktop app: uninstall it from the
|
|
100
|
-
- Installed with the script: on macOS / Linux delete `~/.local/bin/merak`; on Windows remove `~\.merakcode\bin` from your user PATH.
|
|
103
|
+
- Desktop app: on Windows, uninstall it under Settings → Apps; on macOS, drag MerakCode from Applications to the Trash; on Linux, delete the AppImage, or run `sudo apt remove merakcode-desktop` for the `.deb`.
|
|
104
|
+
- Installed with the script: the program is in `~/.merakcode/versions/` (it goes with the folder below); on macOS / Linux also delete `~/.local/bin/merak`; on Windows remove `~\.merakcode\bin` from your user PATH.
|
|
101
105
|
- Installed with npm: `npm uninstall -g merakcode`.
|
|
102
|
-
- Config, sessions, logs and
|
|
106
|
+
- Config, API keys (kept in plain text in `~/.merakcode/data/auth.json`), sessions, logs, caches and a script-installed program all live in one folder, `~/.merakcode` (on Windows `~` is `C:\Users\<you>`; the `MERAKCODE_HOME` environment variable moves it). Delete it if you no longer need it.
|
|
103
107
|
|
|
104
108
|
## Quick start
|
|
105
109
|
|
|
106
110
|
Open the desktop app and click "Open folder" to pick your project.
|
|
107
111
|
|
|
108
|
-
The first time, connect a model provider: on the onboarding screen, pick a provider and enter its API key (change it later under Settings → Models & providers). The built-in catalog is OpenAI, Anthropic, Google, Alibaba
|
|
112
|
+
The first time, connect a model provider: on the onboarding screen, pick a provider and enter its API key (change it later under Settings → Models & providers). The built-in catalog is OpenAI, Anthropic, Google, Alibaba (China), Zhipu AI, DeepSeek, Moonshot AI (China) and OpenRouter; Alibaba, Zhipu and Moonshot use their mainland China endpoints. Keys in environment variables (such as `OPENAI_API_KEY`) are not picked up on their own.
|
|
113
|
+
|
|
114
|
+
For any other service (a local Ollama or LM Studio, a company gateway, or an API relay), click "Add custom provider" under Settings → Models & providers and choose "Compatible API" or "Relay"; on the command line, `merak provider relay` adds a relay. A local model needs no key, but enter one anyway (such as `none`): a provider without a key is not listed.
|
|
115
|
+
|
|
116
|
+
Once connected, the model menu turns on only a few current models for each built-in provider (none for OpenRouter), and every model of a custom provider. For other models, click "Add model" at the bottom of the model menu and turn them on under that provider's "Configure" in Settings.
|
|
109
117
|
|
|
110
118
|
Then just say what you want:
|
|
111
119
|
|
|
@@ -119,7 +127,7 @@ Handy actions (`⌘` on macOS, `Ctrl` on Windows and Linux):
|
|
|
119
127
|
| --------------------- | ----------------------------------------------------------------------------- |
|
|
120
128
|
| `⌘/Ctrl+K` | Command palette: search conversation titles, conversation content or commands |
|
|
121
129
|
| `⌘/Ctrl+N` | New conversation |
|
|
122
|
-
| `⌘/Ctrl+G` | New collaboration group
|
|
130
|
+
| `⌘/Ctrl+G` | New team (a collaboration group) |
|
|
123
131
|
| `⌘/Ctrl+,` | Open settings |
|
|
124
132
|
| `⌘/Ctrl+J` | Open or close the terminal |
|
|
125
133
|
| `⌘/Ctrl+B` | Show or hide the side panel |
|
|
@@ -136,22 +144,30 @@ cd your-project
|
|
|
136
144
|
merak run "Explain how src/index.ts starts up"
|
|
137
145
|
```
|
|
138
146
|
|
|
139
|
-
| Command
|
|
140
|
-
|
|
|
141
|
-
| `merak run "<task>"`
|
|
142
|
-
| `merak
|
|
143
|
-
| `merak
|
|
144
|
-
| `merak
|
|
145
|
-
| `merak
|
|
146
|
-
| `merak
|
|
147
|
-
| `merak
|
|
148
|
-
| `merak
|
|
149
|
-
| `merak
|
|
150
|
-
| `merak
|
|
151
|
-
| `merak
|
|
147
|
+
| Command | What it does |
|
|
148
|
+
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
149
|
+
| `merak run "<task>"` | Run one task and print the result. `-c` continues the last session, `-m` picks the model, `-f` attaches files, `--format json` prints the raw events; the task can also come from a pipe |
|
|
150
|
+
| `merak run --auto "<task>"` | Run it in auto mode; see below |
|
|
151
|
+
| `merak provider login` | Connect a model provider; `list` shows the connected ones, `logout` removes one, `relay` adds a relay |
|
|
152
|
+
| `merak serve --port 4096` | Start only the engine, for the SDK or other programs |
|
|
153
|
+
| `merak upgrade` (or `update`) | Upgrade. `--check` only looks for a new version, `--yes` skips the question |
|
|
154
|
+
| `merak models` | List the models you can use; `--refresh` fetches the model lists again |
|
|
155
|
+
| `merak mcp list` | Show MCP server status |
|
|
156
|
+
| `merak skill`, `merak plugin` | Manage skills and plugins |
|
|
157
|
+
| `merak session`, `merak export`, `merak import` | Manage, export and import sessions |
|
|
158
|
+
| `merak stats` | Token usage and cost |
|
|
159
|
+
| `merak sandbox status` | Is the sandbox on? `setup` sets it up (Windows only), `reset` undoes it |
|
|
160
|
+
| `merak doctor` | Check the install, config, models and sandbox, and say what is wrong |
|
|
161
|
+
| `merak logs` | Where the logs are and recent runs; `--tail` follows the newest log |
|
|
162
|
+
| `merak bug-report` | Zip the checks, config and logs for an issue; keys and conversations are left out |
|
|
163
|
+
| `merak acp` | Run as an [ACP](https://agentclientprotocol.com) agent for editors such as Zed |
|
|
152
164
|
|
|
153
165
|
Add `--help` to any command for the full details.
|
|
154
166
|
|
|
167
|
+
`merak run` has no one to approve anything: an action that would ask (in ask mode, `npm install` or `npm test`, say) is refused, and the agent is told why. To let such actions through, add `--auto`, or write allow rules in the project config (see [Configuration](#configuration)). Writes outside the workspace, risky commands, secret reads, hosts off the allowlist and leaving the sandbox are refused even with `--auto`, and so are commands that may change things before the Windows sandbox is set up.
|
|
168
|
+
|
|
169
|
+
`merak serve` listens only on `127.0.0.1` by default, but has no password, so any program on this computer can call it. When other programs connect, set the environment variable `MERAKCODE_SERVER_PASSWORD` (HTTP Basic auth; the user name is `merakcode` by default). See [SECURITY.md](SECURITY.md#the-engines-api).
|
|
170
|
+
|
|
155
171
|
### In your editor (ACP)
|
|
156
172
|
|
|
157
173
|
Editors that speak [ACP](https://agentclientprotocol.com) can use MerakCode as their agent. For Zed, add this to `~/.config/zed/settings.json`:
|
|
@@ -168,28 +184,28 @@ Editors that speak [ACP](https://agentclientprotocol.com) can use MerakCode as t
|
|
|
168
184
|
|
|
169
185
|
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:
|
|
170
186
|
|
|
171
|
-
- **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.
|
|
172
|
-
- **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.
|
|
173
|
-
- **Commands.** Commands
|
|
174
|
-
- **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.
|
|
175
|
-
- **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
|
|
187
|
+
- **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. MerakCode's own config files (`merakcode.json` and `merakcode.jsonc` anywhere, including the global config) are the exception: they hold the permission rules, so even auto mode asks first, and you can allow only once or for the session. Read-only mode never edits, and an allow rule in the config cannot override that.
|
|
188
|
+
- **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, and so does `~/.merakcode/data/auth.json`, where MerakCode keeps your provider keys. A command argument naming one of these files asks too (`cat .env`, `cat ~/.ssh/id_rsa`), but paths read inside a script or built from variables are not seen. The OS sandbox blocks only the key folders in your home directory; it does not block `.env`, `~/.npmrc`, `~/.git-credentials` or `auth.json`.
|
|
189
|
+
- **Commands.** Commands whose name is on a fixed read-only list (`ls`, `git status`, `git diff`, `rg` and so on) run in every mode; with an option that writes files or runs another program (`sort -o`, `rg --pre`, `git diff --output=`) they count as file-changing commands, and so does anything not on the list. 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`, and piping a `curl` or `wget` download straight into a shell (`curl … | sh`). `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. All of this is read from the command text: wrappers such as `env`, `sudo`, `nice`, `timeout` and `xargs` are judged by the command they run, commands inside `sh -c "…"` and `eval` are looked at too, and forms such as `git -C dir push` are recognised; but commands in a script file or built from variables are not seen. So these rules are not a security boundary; the OS sandbox below is what limits the damage.
|
|
190
|
+
- **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. Local addresses (`localhost`, `127.0.0.1` and so on) do not ask, so commands can reach databases, dev servers and other services on this computer (except the engine's own port; see [SECURITY.md](SECURITY.md) for details).
|
|
191
|
+
- **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 asks in ask and auto mode and is refused in read-only mode. 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 your config (global or project) override the defaults above. Read-only mode still cannot edit files or run anything except read-only commands.
|
|
176
192
|
- **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.
|
|
177
193
|
|
|
178
|
-
| Mode | Good for | What happens
|
|
179
|
-
| ------------- | ------------------------------------- |
|
|
180
|
-
| Read-only | Designs and plans | No edits, only read-only
|
|
181
|
-
| 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
|
|
182
|
-
| 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
|
|
194
|
+
| Mode | Good for | What happens |
|
|
195
|
+
| ------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
196
|
+
| Read-only | Designs and plans | No edits, only commands on the read-only list. Still asks before a non-secret read outside the workspace, a secret, or a host off the allowlist |
|
|
197
|
+
| 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 |
|
|
198
|
+
| 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 changes to MerakCode's config files, writes outside, risky commands, secret reads, hosts off the allowlist, or leaving the sandbox |
|
|
183
199
|
|
|
184
|
-
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.
|
|
200
|
+
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. Subagents, workflows, sandbox permissions and changes to MerakCode's config files offer no "always allow".
|
|
185
201
|
|
|
186
|
-
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
|
|
202
|
+
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`, `.git/config` or MerakCode's config files in the workspace (blocked outright where the OS allows it, otherwise rolled back when the command ends and reported to the model); 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:
|
|
187
203
|
|
|
188
|
-
| System | Built on
|
|
189
|
-
| ------- |
|
|
190
|
-
| Windows | A separate low-rights account, NTFS permissions, the firewall
|
|
191
|
-
| Linux | Landlock (kernel 5.13 or newer)
|
|
192
|
-
| macOS | The built-in Seatbelt (sandbox-exec)
|
|
204
|
+
| System | Built on | What you need to do |
|
|
205
|
+
| ------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
206
|
+
| Windows | A separate low-rights account, NTFS permissions, the firewall | Click "Set up" under Settings → Permissions & security in the desktop app (or run `merak sandbox setup` once) and approve one administrator prompt |
|
|
207
|
+
| Linux | Landlock (kernel 5.13 or newer with Landlock enabled; needs glibc) | Nothing. Network rules need kernel 6.7 or newer |
|
|
208
|
+
| macOS | The built-in Seatbelt (sandbox-exec) | Nothing |
|
|
193
209
|
|
|
194
210
|
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).
|
|
195
211
|
|
|
@@ -197,7 +213,8 @@ While the sandbox is not ready (for example before setup on Windows), commands t
|
|
|
197
213
|
|
|
198
214
|
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.
|
|
199
215
|
|
|
200
|
-
- Create one from New
|
|
216
|
+
- Create one from New team in the sidebar, `⌘/Ctrl+G` or the command palette (with a project open). You can also copy the name and members of an existing group, with their roles and duties; members whose product is unavailable here are skipped, and Clear undoes the copy.
|
|
217
|
+
- A member can be MerakCode itself. The leader can hand out work to several members at once: members whose paths do not overlap work at the same time, while the same member or overlapping paths wait their turn.
|
|
201
218
|
- Mention a member with `@` in the input; rename it or change its role and duty in the member column.
|
|
202
219
|
- 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.
|
|
203
220
|
- 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.
|
|
@@ -220,12 +237,12 @@ Products can also be set in the config:
|
|
|
220
237
|
|
|
221
238
|
## Configuration
|
|
222
239
|
|
|
223
|
-
| Location
|
|
224
|
-
|
|
|
225
|
-
| `~/.merakcode/merakcode.
|
|
226
|
-
| `<project>/.merakcode/merakcode.json`
|
|
227
|
-
| `<project>/AGENTS.md`
|
|
228
|
-
| `<project>/.merakcode/agents/`, `skills/`, `commands/` | Custom agents, skills and
|
|
240
|
+
| Location | Purpose |
|
|
241
|
+
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
242
|
+
| `~/.merakcode/merakcode.jsonc` | Global config (model, language, permission rules...). `merakcode.json` works too, and `.jsonc` wins when both exist; the desktop app and the command line save settings here |
|
|
243
|
+
| `<project>/.merakcode/merakcode.json` | Project config, overrides the global one. `.jsonc` works too, and so does `merakcode.json(c)` in the project root; "always allow" is saved here |
|
|
244
|
+
| `<project>/AGENTS.md` | Notes about your project for MerakCode (`CLAUDE.md` works too; `AGENTS.md` wins in the same folder); `~/.merakcode/AGENTS.md` and `~/.claude/CLAUDE.md` apply to every project |
|
|
245
|
+
| `<project>/.merakcode/agents/`, `skills/`, `commands/`, `rules/` | Custom agents, skills, slash commands and rules (`*.mdc`). The first three also work under `~/.merakcode/` for every project. `.claude/skills`, `.agents/skills` and `.cursor/rules` are read too |
|
|
229
246
|
|
|
230
247
|
Config files can be plain JSON or JSONC with comments. Add `"$schema"` at the top and your editor will autocomplete and check it:
|
|
231
248
|
|
|
@@ -235,13 +252,20 @@ Config files can be plain JSON or JSONC with comments. Add `"$schema"` at the to
|
|
|
235
252
|
"model": "anthropic/claude-sonnet-4-5",
|
|
236
253
|
"locale": "en-US",
|
|
237
254
|
"permission": {
|
|
238
|
-
"bash": { "
|
|
255
|
+
"bash": { "npm test *": "allow" },
|
|
256
|
+
"bash_delete": { "rm -rf *": "deny" },
|
|
239
257
|
},
|
|
240
258
|
"sandbox": { "mode": "preferred" },
|
|
241
259
|
}
|
|
242
260
|
```
|
|
243
261
|
|
|
244
|
-
|
|
262
|
+
Command rules go under the key for their level: `bash_readonly` (read-only commands), `bash` (other commands), `bash_delete` (deletes), `bash_risky` (risky ones) and `bash_forbidden` (the refused ones). A rule only applies under its command's level: a rule for `rm` under `bash` does nothing. See the [schema](schema/config.json) for every key.
|
|
263
|
+
|
|
264
|
+
A config can read environment variables with `{env:NAME}`, such as `"apiKey": "{env:OPENAI_API_KEY}"`.
|
|
265
|
+
|
|
266
|
+
To change the language: the desktop app starts in your system language; change it under Settings → General → Language (saved in the global config, so the command line follows). The command line is in Chinese by default and reads only `"locale"` in the global config (`zh-CN` or `en-US`), or the environment variable `MERAKCODE_LOCALE=en-US`, which wins over the config.
|
|
267
|
+
|
|
268
|
+
The engine goes online to refresh model lists: shortly after it starts and every hour, it fetches each connected provider's list with your saved key, and reads openrouter.ai's public model catalog without a key. Set `MERAKCODE_DISABLE_CATALOG_FETCH=1` to turn this off; `merak models --refresh` refreshes by hand.
|
|
245
269
|
|
|
246
270
|
## SDK
|
|
247
271
|
|
|
@@ -266,35 +290,35 @@ See the [SDK guide](docs/sdk/README.en.md) for everything else.
|
|
|
266
290
|
|
|
267
291
|
## Develop from source
|
|
268
292
|
|
|
269
|
-
You need Node.js 26.12 or newer
|
|
293
|
+
You need Node.js 26.12 or newer (the `node` on your PATH too), pnpm 12, and [ripgrep](https://github.com/BurntSushi/ripgrep) (`rg`) on your PATH for the tests.
|
|
270
294
|
|
|
271
295
|
```sh
|
|
272
296
|
git clone https://github.com/TongTong313/merakcode.git
|
|
273
297
|
cd merakcode
|
|
274
298
|
pnpm install
|
|
275
|
-
pnpm hooks:install # check formatting before each commit
|
|
299
|
+
pnpm hooks:install # check formatting before each commit, and the title of each commit
|
|
276
300
|
```
|
|
277
301
|
|
|
278
302
|
### Run from source
|
|
279
303
|
|
|
280
|
-
| To
|
|
281
|
-
|
|
|
282
|
-
| Work on the desktop app
|
|
283
|
-
| Run a command-line command
|
|
284
|
-
| Start only the engine
|
|
285
|
-
| Debug the engine
|
|
286
|
-
| Print
|
|
304
|
+
| To | Run |
|
|
305
|
+
| ------------------------------ | -------------------------------------------------------------------------------- |
|
|
306
|
+
| Work on the desktop app | `pnpm --dir apps/desktop/main dev` |
|
|
307
|
+
| Run a command-line command | `pnpm dev run --dir "$PWD" "Explain this project"` |
|
|
308
|
+
| Start only the engine | `pnpm dev serve --port 4096` |
|
|
309
|
+
| Debug the engine | `node --inspect --import ./script/node/register.mjs apps/cli/src/index.ts serve` |
|
|
310
|
+
| Print the logs in the terminal | `pnpm dev serve --print-logs` (from source the log level is DEBUG already) |
|
|
287
311
|
|
|
288
312
|
**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.
|
|
289
313
|
|
|
290
|
-
`pnpm dev` runs the source directly; there is nothing to build first. Change the code and run it again.
|
|
314
|
+
`pnpm dev` runs the source directly; there is nothing to build first. Change the code and run it again. It runs inside `apps/cli`, so pass `--dir` to point at your project, or the command takes `apps/cli` as the project.
|
|
291
315
|
|
|
292
316
|
### Tests and checks
|
|
293
317
|
|
|
294
318
|
```sh
|
|
295
|
-
pnpm check
|
|
296
|
-
|
|
297
|
-
|
|
319
|
+
pnpm check # formatting, types, dependency boundaries, generated files... run before you commit
|
|
320
|
+
pnpm --dir packages/engine test # each package runs its own tests
|
|
321
|
+
pnpm --dir apps/cli test test/cli/doctor-command.test.ts # a single file
|
|
298
322
|
```
|
|
299
323
|
|
|
300
324
|
### Packaging
|
|
@@ -304,22 +328,33 @@ pnpm --dir apps/cli build --single # CLI release bundle for this machine, i
|
|
|
304
328
|
pnpm --dir apps/desktop/main package # desktop installer for this machine, in apps/desktop/main/release/
|
|
305
329
|
```
|
|
306
330
|
|
|
307
|
-
The CLI ends up at `apps/cli/dist/merakcode-<version>-<platform>/bin/merak` (`merak.cmd` on Windows). Packaging downloads Node and Electron; if that is slow, set `MERAKCODE_NODE_MIRROR` and `
|
|
331
|
+
The CLI ends up at `apps/cli/dist/merakcode-<version>-<platform>/bin/merak` (`merak.cmd` on Windows). Packaging downloads Node and Electron; if that is slow, set `MERAKCODE_NODE_MIRROR`, `ELECTRON_MIRROR` and `ELECTRON_BUILDER_BINARIES_MIRROR` to a closer mirror. Tests download ripgrep from GitHub when it is not installed; `MERAKCODE_RIPGREP_BASE_URL` picks another source.
|
|
308
332
|
|
|
309
333
|
### Generated files
|
|
310
334
|
|
|
311
|
-
| If you changed
|
|
312
|
-
|
|
|
313
|
-
| A server route
|
|
314
|
-
| A config option
|
|
315
|
-
| An error code
|
|
316
|
-
|
|
|
335
|
+
| If you changed | Run |
|
|
336
|
+
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
|
|
337
|
+
| A server route | `pnpm generate:sdk`, then `pnpm generate:sdk-reference`; `pnpm check:api --write` if the SDK API snapshot changed |
|
|
338
|
+
| A config option | `pnpm generate:schema` |
|
|
339
|
+
| An error code | `pnpm generate:errors` |
|
|
340
|
+
| `@merakcode/sdk/adapter` or a built-in adapter | `pnpm generate:adapter-library` |
|
|
341
|
+
| The SDK public API | `pnpm check:api --write` |
|
|
317
342
|
|
|
318
343
|
### Point the SDK at the engine source
|
|
319
344
|
|
|
345
|
+
Run `pnpm install` in the repo first, and run your program with Node.js 26.12 or newer. Pass the loader to `--import` as a `file://` URL; Windows accepts nothing else:
|
|
346
|
+
|
|
320
347
|
```ts
|
|
348
|
+
import { pathToFileURL } from "node:url"
|
|
349
|
+
|
|
350
|
+
const repo = "/path/to/merakcode"
|
|
321
351
|
const merak = await createMerakCode({
|
|
322
|
-
executablePath: [
|
|
352
|
+
executablePath: [
|
|
353
|
+
process.execPath,
|
|
354
|
+
"--import",
|
|
355
|
+
pathToFileURL(`${repo}/script/node/register.mjs`).href,
|
|
356
|
+
`${repo}/apps/cli/src/index.ts`,
|
|
357
|
+
],
|
|
323
358
|
})
|
|
324
359
|
```
|
|
325
360
|
|
|
@@ -329,14 +364,15 @@ const merak = await createMerakCode({
|
|
|
329
364
|
apps/cli the merak command; merak serve is the engine, and the desktop app ships the same one
|
|
330
365
|
apps/desktop/main desktop app main process (Electron)
|
|
331
366
|
apps/desktop/renderer desktop app UI (SolidJS)
|
|
332
|
-
packages/engine the engine: sessions, models, tools, permissions, HTTP server
|
|
333
|
-
|
|
367
|
+
packages/engine the engine: sessions, models, tools, permissions, HTTP and event stream server
|
|
368
|
+
src/agent agent loop, sessions, context, models, tools and permissions
|
|
369
|
+
src/infra sandbox, config IO, storage, processes and workspace mechanisms
|
|
370
|
+
src/app task, project and session composition, server and host
|
|
334
371
|
packages/sdk/js TypeScript SDK
|
|
335
372
|
packages/util, log shared helpers and logging
|
|
336
|
-
packages/client-core approval options for the desktop app
|
|
337
373
|
```
|
|
338
374
|
|
|
339
|
-
Neither the desktop app nor the command-line commands import engine code. They start a `merak serve` process through the SDK and talk to it over HTTP and an event stream. `pnpm check` enforces this. See [CONTRIBUTING.md](CONTRIBUTING.md) for the rest of the conventions.
|
|
375
|
+
Neither the desktop app nor the command-line commands (other than `serve`, `generate` and `debug`) import engine code. They start a `merak serve` process through the SDK and talk to it over HTTP and an event stream. `pnpm check` enforces this. See [CONTRIBUTING.md](CONTRIBUTING.md) for the rest of the conventions.
|
|
340
376
|
|
|
341
377
|
## When something goes wrong
|
|
342
378
|
|
package/THIRD_PARTY_NOTICES.md
CHANGED
|
@@ -3,13 +3,14 @@
|
|
|
3
3
|
MerakCode contains code taken from or based on the open-source projects below. Their licenses ask us to keep
|
|
4
4
|
their copyright notices, so they are reproduced here in full.
|
|
5
5
|
|
|
6
|
-
|
|
7
|
-
|
|
6
|
+
The command-line archives and platform packages, and the desktop installers, also contain `THIRD_PARTY_LICENSES.txt`,
|
|
7
|
+
which lists the npm packages bundled into them together with their license texts. The `merakcode` npm package and
|
|
8
|
+
`@merakcode/sdk` bundle no third-party code, so they carry this file only.
|
|
8
9
|
|
|
9
10
|
## opencode
|
|
10
11
|
|
|
11
12
|
- Project: https://github.com/anomalyco/opencode
|
|
12
|
-
- Used in: the engine (sessions, tools, providers, server)
|
|
13
|
+
- Used in: the engine (sessions, tools, providers, server, system prompts) and the SDK's plugin API
|
|
13
14
|
- License: MIT
|
|
14
15
|
|
|
15
16
|
```
|
|
@@ -39,7 +40,7 @@ SOFTWARE.
|
|
|
39
40
|
## pi-mono
|
|
40
41
|
|
|
41
42
|
- Project: https://github.com/badlogic/pi-mono
|
|
42
|
-
- Used in: the patterns that detect "context window exceeded" errors in `packages/engine/src/
|
|
43
|
+
- Used in: the patterns that detect "context window exceeded" errors in `packages/engine/src/agent/model/error.ts`
|
|
43
44
|
- License: MIT
|
|
44
45
|
|
|
45
46
|
```
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "merakcode",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0",
|
|
4
4
|
"description": "MerakCode command line: run tasks, start the engine, ACP for editors",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -19,11 +19,11 @@
|
|
|
19
19
|
"node": ">=18"
|
|
20
20
|
},
|
|
21
21
|
"optionalDependencies": {
|
|
22
|
-
"merakcode-darwin-arm64": "0.
|
|
23
|
-
"merakcode-darwin-x64": "0.
|
|
24
|
-
"merakcode-linux-arm64": "0.
|
|
25
|
-
"merakcode-linux-x64": "0.
|
|
26
|
-
"merakcode-windows-arm64": "0.
|
|
27
|
-
"merakcode-windows-x64": "0.
|
|
22
|
+
"merakcode-darwin-arm64": "0.3.0",
|
|
23
|
+
"merakcode-darwin-x64": "0.3.0",
|
|
24
|
+
"merakcode-linux-arm64": "0.3.0",
|
|
25
|
+
"merakcode-linux-x64": "0.3.0",
|
|
26
|
+
"merakcode-windows-arm64": "0.3.0",
|
|
27
|
+
"merakcode-windows-x64": "0.3.0"
|
|
28
28
|
}
|
|
29
29
|
}
|