@aistastudio/myc 0.3.2 → 0.3.4

package/README.md

@@ -31,7 +31,7 @@ Installation is one command:
 
 ```bash
 bun install -g @aistastudio/myc   # 3.20 MB, 10 files, no models pulled at install
-myc --version                     # myc 0.3.2 (schema 1)
+myc --version                     # myc 0.3.4 (schema 1)
 ```
 
 The embedding model is **not** downloaded during install. Semantic search is
@@ -56,6 +56,7 @@ writing a config that silently won't start.
 ```bash
 ./dist/myc init                     # .myc/ + SQLite + migrations in this repo
 ./dist/myc wire                     # hooks for Claude Code / Codex / opencode / Kimi
+./dist/myc wire --scope user        # the same for agents in git worktrees (Claude Code's user layer)
 ./dist/myc ready                    # what can be picked up right now
 ./dist/myc remember "why X, not Y"  # record a fact or decision
 ./dist/myc recall "how retrieval works"
@@ -65,6 +66,82 @@ writing a config that silently won't start.
 
 Full command list: `./dist/myc --help`.
 
+**Agents in git worktrees.** `myc wire` writes into the project:
+`.claude/settings.json`, `.mcp.json`. An agent that orca starts in a git
+worktree of a nested repository (`~/orca/workspaces/<repo>/<branch>`) lives in
+the team's tree, where those files are not, even though `myc` itself finds the
+main copy's workspace from there. `myc wire --scope user` puts the same into
+Claude Code's user layer, which every session reads:
+`~/.claude/helpers/myc-hooks.mjs`, SessionStart/PreCompact/PostToolUse hooks and
+`Bash(myc <command>:*)` rules in `~/.claude/settings.json` (merged node by node;
+the hooks of orca, herdr and other tools stay byte for byte), the skill in
+`~/.claude/skills/myc`, and the MCP server through `claude mcp add --scope user`.
+Before anything else the helper checks, without starting myc, whether there is
+a workspace here (a git worktree is resolved through its main copy), and stays
+silent when there is none or the project wires myc itself: in a project without
+myc the hook costs one node start, and prime never arrives twice. Outside a
+workspace the MCP server offers zero tools and no instructions. The user's
+`statusLine` is never touched (it belongs to orca), and `--hook-mode replace`
+is refused here. The journal is `~/.myc/wire-user.json`; `myc unwire --scope
+user` restores the settings node by node and removes the MCP server.
+
+## Heavy commands take turns
+
+Several agents on one machine — in one tree or in neighbouring projects — each
+run the heavy things: the full test suite, builds, benchmarks. Run at once, they
+get in each other's way: full runs take twice as long, and latency budgets fail
+because of the neighbour, not the code. `myc run` puts such a command into one
+queue shared by every repository of the machine user (`~/.myc/queue.db`), waits
+for a free slot (first come, first served) and then runs it with the terminal
+and the exit code left alone:
+
+```bash
+myc run -- bun test              # waits its turn (--max-wait 5m by default), then runs
+myc run --max-wait 15m -- make   # a longer wait for a longer tool timeout
+myc queue                        # who is running, who is waiting, for how long
+```
+
+```
+$ myc queue
+heavy · slots 1 · 1 running · 1 waiting · ~/.myc/queue.db
+  running #1      4s  bun test  ~/src/api  session 6468c59d · orca term_efe4850f · pid 44815 · command pid 44827
+  waiting #2      3s  bun run build  ~/src/web  session 6468c59d · orca term_efe4850f · pid 44850 (#1 in line)
+```
+
+A waiting command says on stderr whom it waits for; past `--max-wait` it gives
+up with exit code 9 and names what is ahead:
+
+```
+myc run: waiting for a 'heavy' slot (1/1 busy, 1 waiting ahead), waited 0.0s of max 3s — held by 'bun test' in ~/src/api, session 6468c59d, orca term_efe4850f, pid 44815, running 13s
+```
+
+A holder that dies — even by `SIGKILL` — frees its slot; a `myc run` nested
+inside another one runs at once, in its parent's slot. One slot per lane by
+default, `MYC_HEAVY_SLOTS=2` for two.
+
+**Agents don't have to remember it.** `myc wire --queue-hook` installs a Claude
+Code `PreToolUse` hook that rewrites a heavy Bash command into
+`myc run -- <the same command>` before it runs. Heavy means a full test run or a
+build: `bun test` with no paths, `bun run build` / `typecheck`, `npm` / `pnpm` /
+`yarn` `test` and `build`, `cargo test` / `build`, `go test ./...`, `pytest`
+with no paths, `make`. A targeted `bun test path/file.test.ts`, a command already
+under `myc run`, a background one and a nested one pass untouched.
+`MYC_QUEUE_HEAVY` replaces the list (`+…` adds to it, `off` turns the hook off).
+It is opt-in: `wire` without the flag writes no such hook, and `unwire` removes
+it. It is cheap, because it runs on every Bash call: a command that is not heavy
+is let through by the host's own shell without starting bun or node — 3.4 ms at
+the median and 4.3 ms at p99 in the run of 2026-09-11, against 30 ms for the
+prime hook (`bun test packages/cli/src/hooks/queue-hook.multiprocess.test.ts`).
+
+**`myc run` is not a way around permissions.** It runs whatever it is given, so
+a queued command goes through without a question only when your own rules would
+let the original command through — `Bash(bun test:*)` keeps `bun test` silent
+under the queue as well. Otherwise Claude Code asks, and the question shows the
+whole command; a deny or ask rule on the original command still holds. The same
+goes for a `myc run -- <cmd>` an agent types itself. For the same reason `wire`
+no longer writes the broad `Bash(myc:*)`: it allows myc's subcommands one by
+one, and `run`, `statusline --then`, `wire` and `unwire` ask.
+
 ## What makes it different
 
 **Speed is a constraint, not an optimisation.** Every hot path has a budget
@@ -193,8 +270,12 @@ in git.** There is no server, no ACL and no team mode. Those are designed
 (`docs/design/03…`, `04…`, `05…`) and tracked, not implemented.
 
 Code intelligence is built in, and it is the same engine the alternatives use:
-tree-sitter, with grammars fetched on demand rather than shipped (all 36 weigh
-49 MB against a 12 MB package). `myc code index` builds it — on this repository,
+tree-sitter, with grammars fetched on demand rather than shipped. Symbols,
+callers and code search work for TypeScript, TSX, JavaScript (js, jsx, mjs,
+cjs) and Python — the languages myc has definition rules for. The grammar
+package holds 36; a language is added as a pair, a rule and a catalog entry,
+so a grammar that would yield no symbols is never offered. Every other file
+still gets `code grep`, anchors and staleness. `myc code index` builds it — on this repository,
 826 files and 3 949 symbols in 904 ms — and four commands read it:
 
 ```
@@ -205,6 +286,34 @@ myc code grep "<lit>"    exhaustive, every occurrence; --in <path> narrows it
 myc skeleton <file>      the file's API — 26× cheaper than reading it
 ```
 
+The file list is git's own (`git ls-files`, so `.gitignore` applies; a tree
+without git is walked, and the command says so). On top of any list,
+secret-named files are never indexed, whatever `.gitignore` says: `.env` and
+`.env.*` (templates like `.env.example` are indexed), `*.pem`, `*.key`,
+keystores, private SSH keys, `.npmrc`, `.netrc` and other credential files —
+`code index` counts them without naming them, and `code grep` refuses to read one.
+
+**Nested repositories and git worktrees.** A workspace can be an ecosystem: a
+root that is a git repository with independent repositories inside it (not
+submodules). It has one code index, built from the root — one row per file,
+paths like `messaging-server/server/src/x.ts`. From inside a nested
+repository every code command answers from that repository's part of the
+root index, with paths relative to the repository you are in; from the root
+the answers do not change. `myc code index` run inside a nested repository
+refreshes its part of the root index instead of building a second copy of the
+same files, and so does the background refresh. A git worktree — even one
+outside the workspace tree — is answered from the index of the main checkout:
+there is no index per branch. When the worktree is on another commit, or has
+uncommitted changes to tracked files, every answer carries
+`WARN code_index.worktree_divergent` naming both branches, because lines and
+spans may not match your files. `code grep` reads the worktree's files (the
+line numbers are yours, the owning symbols come from the index); `skeleton`
+shows the main copy's declarations when your copy differs from what the index
+saw, and says so. When nothing covers the repository, the hint is the command
+for the workspace root (`myc -C <root> code index`), not one that would build a
+duplicate. Anchors set from the root and from inside a repository are stored
+under different keys; `code symbol` reads both.
+
 Anchors tie knowledge to a span and follow the code as it moves; that half is
 language-agnostic and was verified on Python as well as TypeScript.