⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣀⣀⣀⣀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣤⣾⣿⣿⣿⣿⣿⣿⣷⣦⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⢀⣾⣿⣿⡿⠋⣉⣉⠙⢿⣿⣿⣿⡄⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⣼⣿⣿⡏⢠⣾⣿⣿⣿⡄⢹⣿⣿⣿⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⣿⣿⣿⣧⠈⢿⣿⣿⣿⠃⣸⣿⣿⣿⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠸⣿⣿⣿⣆⠀⠉⠉⠀⢠⣿⣿⣿⡏⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠙⣿⣿⣿⣆⠀⠀⢠⣿⣿⣿⠏⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⢸⣶⣤⣀⠘⣿⣿⣿⠆⢠⣿⣿⣿⠃⢀⣤⣶⣿⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⢸⣿⣿⣿⣿⣿⣿⠏⢠⣿⣿⣿⠃⣰⣿⣿⣿⣿⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⢸⣿⣿⣿⣿⣿⠏⢠⣿⣿⡿⠃⣰⣿⣿⣿⣿⣿⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⢸⣿⣿⣿⣿⡏⢠⣿⣿⡿⠁⣼⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⢸⣿⣿⣿⡟⢠⣿⣿⡟⢀⣼⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⢸⣿⠿⠋⢀⣿⣿⠟⠀⠾⠿⣿⣿⡌⠙⠻⢿⣿⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣾⣿⣿⣶⣶⣶⣶⣿⣿⣿⣄⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠚⠛⠛⠛⠛⠛⠛⠛⠛⠛⠛⠛⠂⠀⠀⠀⠀⠀⠀⠀⠀

Monkdev

A coding methodology for LLM agents. Measure. Prove. Cut.

Monkdev is a toolkit plus a persona. The toolkit (an MCP server) gives your agent token-aware codebase ingestion, cross-language symbol search, dependency mapping, and stealth web browsing. The persona (CLAUDE.md) constrains behavior: simple over clever, root-cause fixes over band-aids, no performative code, no wasted tokens. The monk serves the architecture, not the ego.

Installation

curl -fsSL https://raw.githubusercontent.com/oeo/monkdev/master/scripts/install.sh | bash

One line installs or upgrades everything: clones to ~/.monkdev (override with MONK_DIR), runs bun install, registers the MCP server, and merges the monk directives into your global agent prompt between markers — never touching your own content outside them. Auto-detects Claude Code and OpenCode; for OpenCode it writes to ~/.config/opencode/AGENTS.md and prints the MCP config snippet. Re-run the same line to upgrade. Requires Bun and git.

The script edits your global agent prompt. Skim scripts/install.sh before piping it to bash.

A full install is two parts: the MCP server (tools) and the monk directives (behavior).

1. Get the code

• Fresh: git clone https://github.com/oeo/monkdev.git && cd monkdev
• Upgrade: git pull in the existing checkout.
• bun install (Bun required — https://bun.sh).

2. Register the MCP server — entrypoint src/mcp.ts, run with bun and an absolute path.

• Claude Code: claude mcp add monk -s user -- bun "$(pwd)/src/mcp.ts"
• OpenCode — add to ~/.config/opencode/opencode.json under mcp:

  "monk": { "type": "local", "command": ["bun", "<abs>/src/mcp.ts"], "enabled": true }
  

• Claude Desktop — add to claude_desktop_config.json under mcpServers:

  "monk": { "command": "bun", "args": ["<abs>/src/mcp.ts"] }
  

3. Install the monk directives — the directives are this repo's CLAUDE.md; they belong in your global prompt so the discipline applies everywhere:

• Claude Code: ~/.claude/CLAUDE.md
• OpenCode: ~/.config/opencode/AGENTS.md

Wrap them in markers so upgrades replace cleanly:

<!-- BEGIN MONK DIRECTIVES -->
...contents of CLAUDE.md...
<!-- END MONK DIRECTIVES -->

4. Configure & verify

• Optional: brave-search needs BRAVE_API_KEY in .env (copy .env.example); every other tool works without a key.
• fetch-url / screenshot-url require Google Chrome or Chromium installed (auto-detected via common paths; set MONK_CHROME to the binary path to override). No bundled browser download needed.
• Restart the agent session, then verify the monk_tree tool responds.

The Arsenal

Usage

The tools are self-documenting from the CLI:

./bin/monk list             # list all tools
./bin/monk describe <tool>  # show a tool's args
./bin/monk tree             # map the architecture

Directives

Directives are the monk's verbs — natural-language keywords the operator types to drive the workflow. The agent recognizes each and runs the matching ritual with the toolkit. Use them to scaffold your own sessions. All commands use the # pound-prefix (holy commands); legacy keyword forms below are fallback aliases. Holy commands compose with | for pseudo-unix pipes.

The full ritual semantics (meditation depths, the Measure–Prove–Cut protocol, commit formats) live in CLAUDE.md under Explicit Command Directives — the agent reads them from your global prompt after install.

Ignore Rules

tree and context walk recursively, reading .gitignore at every directory level (rules inherit downward and resolve relative to their own directory).

A built-in blacklist (MONK_BLACKLIST in src/lib/walk.ts) hard-omits what is never source: package stores (node_modules, site-packages, Pods, …), build output (dist, target, zig-out, …), tool caches (.pytest_cache, .gradle, .terraform, …), lockfiles, and derived artifacts (*.min.js, sourcemaps, *.tsbuildinfo). Any directory holding a pyvenv.cfg is skipped as a virtualenv regardless of its name. Files over 500KB are skipped and surfaced as a warning; byte-identical duplicate files keep only their best-ranked copy's score, and context packs the body once, stubbing the copies with duplicateOf.

A .monkignore file (same syntax, also recursive) marks paths the monk should not ingest during general meditation. Such paths are dropped from context but still listed by tree with a (monk-omit) tag. This keeps broad meditation focused while letting the monk target a fogged folder explicitly (e.g. monk context vendor).

Extending

Tools are built using citty. To add a new tool:

1. Create the command in src/tools/.
2. Export it in src/tools/index.ts.
3. Write an integration test in tests/ (enforced by conventions.test.ts).