From bd6f5aac36ab1893c8d1896ce1d0c3f3d1b6a285 Mon Sep 17 00:00:00 2001 From: Michael Assaf Date: Wed, 17 Jun 2026 07:32:14 -0400 Subject: [PATCH] docs(readme): document oxcode_watch and the single-writer watcher Replace the stale "read-only tools" framing in the MCP section: tell the agent to call oxcode_watch once (it builds the index and keeps it current as files change; a file lock elects one writer per repo while other instances serve reads), add oxcode_watch to the auto-allow list, and add it to the oxcode-cli tool description in the architecture section. --- README.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index d5e4603..cefe645 100644 --- a/README.md +++ b/README.md @@ -59,9 +59,15 @@ Add the server to your agent. For Claude Code (`~/.claude.json`): } ``` -Optionally auto-allow the read-only tools in `~/.claude/settings.json`: -`mcp__oxcode__oxcode_explore`, `_search`, `_callers`, `_callees`, `_symbol`, -`_files`, `_status`. +Once wired, have the agent call `oxcode_watch` once: it builds the index and +keeps it current as files change. Across multiple agents on one repo a file lock +elects a single writer (the one watcher/re-indexer) while the rest serve reads, so +you can run as many as you like. Then ask questions with `oxcode_explore`. + +Optionally auto-allow the tools in `~/.claude/settings.json` (the query tools are +read-only; `oxcode_watch` only builds/maintains the local index): +`mcp__oxcode__oxcode_watch`, `_explore`, `_search`, `_callers`, `_callees`, +`_symbol`, `_files`, `_status`. #### Claude Code plugin (one-command install) @@ -254,9 +260,12 @@ The workspace uses a hybrid Rust architecture: - `oxcode-core`: indexing, extraction, reference resolution, OxGraph storage, navigation, formatting, and the public `ProjectIndex` facade - `oxcode-cli`: the `oxcode` binary — the CLI commands plus the `oxcode mcp` - subcommand, an MCP server (stdio) exposing oxcode's read-only queries to coding + subcommand, an MCP server (stdio) exposing the read-only queries to coding agents (the one-call `oxcode_explore` tool plus `oxcode_search`, - `oxcode_callers`/`oxcode_callees`, `oxcode_symbol`, `oxcode_files`, `oxcode_status`) + `oxcode_callers`/`oxcode_callees`, `oxcode_symbol`, `oxcode_files`, + `oxcode_status`) and `oxcode_watch`, which builds and keeps the index current as + files change — a cross-process file lock elects one writer per repo while other + instances serve reads `oxcode-core` is split into focused internal modules: `scan`, `extract` (with per-language extractors and shared CST/cargo helpers), `resolve`,