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/ — 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.

Requires Bun — this is not fine print

The runtime is bound to bun:sqlite (no native bindings on the Node side). It will not start on plain Node.js or Deno. Bun ≥ 1.3.0 is required and pinned in package.json → engines.bun.

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.06 MB compressed, 15.63 MB unpacked, 16 files; no models pulled
myc --version                     # myc 0.3.14 (schema 1)

It runs on macOS and Linux. On Windows, use WSL and install Bun and myc inside it: the myc launcher does not start in cmd or PowerShell, and an npm install on Windows says so.

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 and Kimi
myc ready --claim            # take the next task
myc show <id>                # all that is known about it
myc close <id>
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 <command> --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/<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. --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