Myc

myc

A local, fast task-and-memory layer for coding agents: a task queue, an oplog of facts and decisions, hybrid (lexical + vector) search over the project's memory, and a built-in code index — with no network calls of its own and no mandatory LLM key. The network is reached only when you ask: myc models fetch, myc code fetch, myc version --check (or MYC_UPDATE_CHECK=1, a background version check at most once a day from init and wire).

Agents forget. myc is the part that doesn't: decisions survive context compaction, work survives process death, and both survive being moved between machines through plain git.

Design docs live in docs/design/ (start with 00-brief.md); the measurements quoted below are reproducible from bench/ and scripts/.

Site: [https://aistastudio.github.io/myc/](https://aistastudio.github.io/myc/) — every capability with the release it arrived in and a command that shows it, the roadmap, and the measurements as charts, in English and Russian, with the command that reproduces each number printed next to it. It is the one source of numbers: bun run site/build.ts checks every figure on the site against the measurement artefacts in this repository, the figures in this README and in the Russian one against the site's site/measurements.json, and every myc command and flag on the site and in both READMEs against this build's --help; a mismatch fails the build.

Native binaries — and Bun as the fallback

The engine inside myc is still Bun (bun:sqlite, no native bindings on the Node side) — but since 0.6.0 you no longer install Bun to run it: npm install -g @aistastudio/myc brings a native binary for your platform (Windows x64, macOS arm64/x64, Linux x64/arm64), and the launcher needs only Node ≥ 18. On Windows the binary is experimental until confirmed on a live machine; WSL stays the fully supported path there.

What Bun is still for. The package also carries the whole myc as one JS bundle: wherever the platform binary did not install, the launcher falls back to running the bundle under Bun. The protection that matters travels with both paths: the native binary is built with autoload disabled (--no-compile-autoload-dotenv/--no-compile-autoload-bunfig), and the bundle gets --no-env-file/--config in argv — myc never loads the launching project's .env or bunfig.toml (in the cherry incident myc run forwarded 20 EXPO_PUBLIC_* from a worktree's .env into tests).

SQLite ≥ 3.50.4. The floor has two reasons. Below 3.44.0, FTS5 cannot be written from triggers under trusted_schema = OFF, so every write fails. And on 3.43.2 and 3.46.0, parallel myc processes were measured running one background job two or three times, with a failing job reporting "database disk image is malformed"; the cause is not known, so myc refuses every library below what a supported setup gives it. Nothing supported loses anything: on Linux, Bun links its own SQLite (3.50.4 in Bun 1.3.0, the minimum in engines.bun; 3.53.0 in Bun 1.3.14), and on macOS, where Bun would use the system SQLite — 3.43.2 on macOS 14 — the package ships its own: vendor/sqlite/libmyc-sqlite3.dylib, SQLite 3.53.4 built from the official amalgamation for arm64 and x86_64 (scripts/build-sqlite.ts), chosen before anything else except an explicit MYC_SQLITE=/path/to/libsqlite3.dylib. If the SQLite in use is still below 3.50.4 — a broken install, an unsupported Bun, or MYC_SQLITE pointing at an old library — every command, myc init included, refuses with precond.sqlite_unsupported and says what to do, instead of creating a workspace it cannot write to. From 3.50.4 up to 3.51.2 myc works but warns (WARN degraded.sqlite_old): that band is not proven safe for the queue, and on Linux the cure is bun upgrade. myc doctor names the SQLite in use and where it came from.

Install Bun: https://bun.sh

Install

Installation is one command:

bun install -g @aistastudio/myc   # 5.11 MB compressed, 15.83 MB unpacked, 16 files; no models pulled

myc --version # myc 0.6.7 (schema 1)

Windows. npm install -g @aistastudio/myc installs the native x64 binary (the launcher needs Node ≥ 18) — experimental until confirmed on a live machine. WSL stays the fully supported path: inside WSL everything works as on Linux.

The embedding model is not downloaded during install. Semantic search is opt-in and explicit: myc models fetch (129 MB, ~7 s). Until then search is lexical and says so on every answer (WARN degraded.embeddings). The grammars for the code index are fetched the same way, once: myc code fetch.

To run the newest code instead of the published release, build from source:

git clone https://github.com/aistastudio/myc && cd myc

bun install bun run build # produces a single binary: dist/myc ./dist/myc --version

Put the binary somewhere myc wire can find it — MYC_BIN, node_modules/.bin, ~/.myc/bin/myc, or PATH. If it can't, wire says so out loud instead of writing a config that silently won't start.

Quick start

Two commands set a project up; the rest is the loop an agent lives in. (From a source build, ./dist/myc instead of myc.)

myc init                     # .myc/ + SQLite + migrations in this repo

myc wire # hooks + MCP for Claude Code, Codex, opencode, Kimi, mcode and mimo myc ready --claim # take the next task myc show # all that is known about it myc close myc remember "why X, not Y" # record a fact or decision myc recall "how retrieval works" myc prime # session context packet (agents call it) myc code fetch # grammars for this repo's languages, once myc code index # symbols, callers, code search myc doctor # schema, counters, hooks — says "don't know" where it doesn't

Full command list: myc --help; details of each: myc --help.

Wiring agents

myc wire writes only its own files in full and merges JSON configs node by node with a .myc.bak alongside; CLAUDE.md is never touched. Running it twice changes nothing. Everything past the plain wire is opt-in:

myc wire --dry-run              # show every change, write nothing

myc wire --agents claude,codex # only some of the agents myc wire --status-line # + myc's status line under Claude Code's prompt myc wire --queue-hook # + heavy commands take turns (below) myc wire --agents-md # + the myc block in AGENTS.md myc wire --scope user # the same for agents in git worktrees (Claude Code's user layer) myc wire --scope user --agents claude,opencode # + opencode's global config myc unwire # remove what wire put in

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/ / ) 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 :*) 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. --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.

opencode in such a worktree is in the same position, and --agents opencode (or claude,opencode; without --agents the user layer is Claude Code's only) wires its global config, $XDG_CONFIG_HOME/opencode or ~/.config/opencode: the myc server goes into mcp of the opencode.json[c] opencode itself treats as its own, as one node — the file is JSONC, and other entries, comments and trailing commas stay byte for byte — and plugin/myc.ts goes next to it. opencode starts that server in the directory it was opened in, so myc mcp finds the workspace from a worktree by itself. The plugin makes the same two checks as the helper, once per project and without starting myc: no workspace here, or the project wires opencode itself (opencode.json with mcp.myc, or .opencode/plugin/myc.ts — opencode loads the plugins of both layers, and a project's mcp.myc overrides this one) — then it registers no hooks at all. myc unwire --scope user takes out exactly that node and the plugin.

With --status-line the user layer also gets myc's status line, myc statusline --scope user: in a myc workspace — a git worktree of one included — it is the full line, outside one it prints nothing of its own. The line that was there (orca's, which prints nothing and posts the input to orca) is kept in the journal, not in our command, and gets the same stdin on every redraw, never waited on: orca takes a line whose command mentions its agent-hooks/claude-statusline.sh for its own and removes it when it uninstalls (a foreign line it leaves alone), so ours never carries the word claude-statusline. A project with its own myc line keeps it, and that line hands the input to the same recorded line. If another tool replaces the user line after wire, myc doctor --hooks says so; myc wire --scope user --status-line puts ours back and makes the new line the previous one, and myc unwire --scope user puts the previous line back byte for byte. myc doctor --hooks checks the whole user layer against the journal: myc's hook entries and rules still in ~/.claude/settings.json, the helpers exactly what this build writes (a stale one is named with the build that wrote it), the status line, the MCP server — and, when opencode is wired, its plugin and mcp.myc.

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:

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. myc does not load the proje