Troubleshooting

When something breaks, start here. If your issue isn't covered, open a GitHub issue with mewrite doctor output.

Install

mewrite: command not found after install

Restart your shell, or:

source ~/.zshrc      # zsh
source ~/.bashrc     # bash

If still missing, the installer printed the install path — add it to your PATH.

Operation not permitted writing to ~/.mewrite

Filesystem is read-only or owned by another user. Run:

ls -la ~/.mewrite
chown -R "$USER" ~/.mewrite

Apple silicon: bad CPU type in executable

You downloaded an x86_64 binary on an ARM Mac. Re-install via npm — the package is platform-agnostic:

npm install -g @zhachory1/mewrite-code

Auth

OAuth opens browser but never completes

1. Check that the loopback port (random in 1024-65535) isn't firewalled.
2. If loopback auth still fails, use API-key auth for that provider.
3. Disable VPN that intercepts loopback.

401 Unauthorized on a stored token

Token expired and refresh failed. Re-login:

mewrite
/logout <provider>
/login <provider>

Linux libsecret not found

Install:

# Debian / Ubuntu
sudo apt install libsecret-1-0 libsecret-tools

# Arch
sudo pacman -S libsecret

If your distro lacks libsecret, prefer API-key auth via environment variables.

Sessions

Me Write Code hangs on launch

Stuck on context load. Kill and:

mewrite -r --no-context     # browse without loading any session

Then identify and remove the bad session under ~/.mewrite/agent/sessions/.

/tree shows no branches

Branching is per-session. The first session in a cwd has no branches by definition. Run a few turns then /fork to test.

Compaction destroyed important context

Use the shadow-git checkpoint: /checkpoint list, then /rollback <N>. Compaction itself runs a PreCompact hook — instrument it to write important context to disk first.

Tools

Bash tool times out

Default tool timeout is 60s. Override per call:

> use Bash with --timeout 600 to run the long-running migration

Or globally in ~/.mewrite/agent/settings.json:

{
    "tools": { "bash": { "timeoutMs": 600000 } }
}

Edit keeps applying to the wrong location

The model's view of the file is stale. After a hook writes to the file, ask Me Write Code to re-read:

> re-read src/foo.ts and apply the change

Caveman Mode is summarizing too aggressively

Lower compression intensity:

/cave lite                    # default is "full" (in TUI)
/cave off                     # turn off entirely

Permissions

Every action prompts even though I clicked "Allow always"

The allow-key is more specific than the new action. E.g. Read packages/foo/** won't match Read packages/bar/baz.ts. Add a broader allow-key with mewrite permissions add "Read **".

Sandbox blocks something I need

mewrite debug sandbox shows the active policy. Me Write Code executes all tool requests directly - there is no sandbox flag or permission prompts. The OS enforces filesystem permissions. To constrain a session, use --tools to limit available tools (e.g. --tools read,grep,find,ls for read-only).

For permanent allowlist, add to permissions.json:

{
    "permissions": {
        "alwaysAllow": ["Bash:docker run *"]
    }
}

MCP

mewrite mcp doctor shows server unreachable

mewrite mcp logs <server>     # tails stderr of stdio server

Common causes: command not on PATH, env var missing, server's auth flow incomplete.

MCP tools don't show up in the model's context

By default Me Write Code defers MCP schemas — only names are listed until the model calls ToolSearch. This reduces context bloat by ~85%.

Hooks

Hook never fires

Check the matcher:

/hooks test PreToolUse --tool Edit --path src/foo.ts

Reports whether each hook would fire for that input. Common mistake: paths glob doesn't include the actual file path.

Hook output isn't reaching the model

Only stdout is fed back to the model as a system reminder. Stderr is logged but ignored. Check that your hook prints to stdout, not stderr.

Memory (cavemem)

/memory search returns nothing

cavemem isn't running. Check:

cavemem --version
mewrite mcp doctor   # should show cavemem reachable

If missing: npm install -g cavemem, then register it with mewrite mcp add cavemem --command cavemem --arg mcp.

Memory injection too noisy

Lower the cap in settings.json:

{
    "memory": { "maxInjectTokens": 1000 }
}

Or disable for the session: /memory off.

Performance

TUI feels laggy

Me Write Code automatically detects and uses synchronized output (DEC mode 2026) on supported terminals. If you see rendering issues, ensure your terminal supports ANSI escape sequences and check mewrite doctor output for terminal detection status.

Long sessions get slow

Run /compact to manually compact. Or enable auto-compact at a lower threshold:

{
    "session": { "autoCompactAtTokens": 80000 }
}

Reporting issues

mewrite doctor > /tmp/mewrite-doctor.txt
mewrite version > /tmp/mewrite-version.txt

Attach both to a GitHub issue. Include the prompt that triggered the bug if reproducible.