# Octofs 0.16: Claude Code और Codex के लिए state-of-the-art filesystem

> चार हफ़्तों तक हमने octofs को Claude Code और Codex के नीचे इकलौते filesystem और shell के रूप में चलाया, और जो कुछ भी रास्ते में आया उसे ठीक किया। आठ releases बाद वही tasks लगभग उतने ही tokens में 2–2.5 गुना तेज़ पूरे होते हैं। 0.15 और 0.16 के release notes, साथ में built-in tools की जगह इसे लगाकर ख़ुद आज़माने के लिए exact config। ओपन सोर्स, Apache-2.0।

# Octofs 0.16: Claude Code और Codex के लिए state-of-the-art filesystem

400 लाइनों की file पढ़ने में microseconds लगते हैं। उसे दोबारा पढ़ने का फ़ैसला करने में मॉडल का एक turn लगता है, और मॉडल का एक turn seconds लेता है। एजेंट की speed की पूरी कहानी इसी असमानता में है: disk कभी bottleneck नहीं होती। Bottleneck यह है कि action लेने से पहले मॉडल को कितनी बार रुकना, देखना और दोबारा पूछना पड़ता है।

पिछले चार हफ़्तों से हमने [octofs](https://github.com/Muvon/octofs) को Claude Code और Codex के नीचे इकलौते filesystem और shell के रूप में चलाया। हमने built-in file और shell tools बंद कर दिए और जो कुछ भी रास्ते में आया उसे ठीक किया। आठ releases बाद, 0.15.0 से 0.16.0 तक, हमने यह मापा: **वही tasks लगभग उतने ही tokens में 2–2.5 गुना तेज़ पूरे होते हैं।** वही मॉडल, लगभग उतने ही tokens, कम समय।

Clients के साथ आने वाले tools से तेज़, और tokens का कोई अतिरिक्त ख़र्च नहीं। किसी filesystem को state of the art कहने के लिए हमने यही पैमाना रखा था, और 0.16 उस पर खरा उतरता है। यह पोस्ट उन आठ releases के release notes हैं, साथ में ख़ुद आज़माने के लिए exact config।

---

## समय कहाँ जाता है

Octofs मॉडल को तेज़ सोचने पर मजबूर नहीं करता। वह उन turns को हटा देता है जिनमें मॉडल सिर्फ़ वही दोबारा पक्का कर रहा था जो उसे पहले से पता था। इनमें से हर बात उस tool contract में है जो मॉडल देखता है:

- **Edits वही लौटाते हैं जो बदला, fresh ids के साथ।** Octofs जो भी लाइन दिखाता है उसकी एक id होती है: उसका line number और उसके content का एक छोटा hash, `N:hh|content` के रूप में। `batch_edit` और `text_editor` जवाब में एक diff देते हैं जिसकी लाइनों पर नई ids होती हैं, इसलिए अगला edit बीच में दोबारा पढ़े बिना सीधे उन्हें target करता है। 0.15.0 ने अंत में एक `shift:` लाइन जोड़ी जो बताती है कि हर edit के नीचे के line numbers कितने खिसके, ताकि किसी पुराने read से मॉडल के पास बची ids भी काम की रहें।
- **दोबारा पढ़ने पर सिर्फ़ फ़र्क़ लौटता है।** 0.15.0 से, ऐसी पूरी file देखने पर जिसे सेशन पहले देख चुका है, सिर्फ़ बदले हुए hunks लौटते हैं, या एक लाइन का "unchanged" marker। Octofs के अपने edits उस cache को current रखते हैं, इसलिए अपने ही edit को दोबारा जाँचने की क़ीमत एक लाइन है।
- **ग़लत target जवाब साथ लेकर fail होता है।** पुरानी पड़ चुकी line id सिर्फ़ fail नहीं होती। Error में current content और यह जानकारी होती है कि target कहाँ खिसका, इसलिए retry बिना एक और read के हो जाता है। यह [0.9.0](/blog/octofs-0-9-0-content-verified-line-ids) से ऐसा ही है।
- **लंबी commands turn को रोककर नहीं रखतीं।** दस सेकंड पर भी चल रही command एक background job बन जाती है। यह वही process है, न मारी गई न restart हुई, और मॉडल को उसका turn वापस मिल जाता है। यह [0.13 और 0.14](/blog/octofs-0-14-waiting-is-not-a-tool-call) में आया।
- **एक response, कई calls।** Server instructions मॉडल को साफ़ बताती हैं कि हर response एक round trip का ख़र्च है, इसलिए उसे हर independent call एक साथ माँगनी चाहिए। 0.16.0 ने यह wording और धारदार की।

हमने 2–2.5x को mechanism के हिसाब से नहीं बाँटा है, इसलिए इस सूची को design की तरह पढ़ें, इस हिसाब की तरह नहीं कि किसने कितना योगदान दिया। इनमें से कोई भी idea इस release में नया नहीं है। असली clients के नीचे चार हफ़्तों ने वह polish जोड़ा जो मॉडल को fast path पर टिकाए रखता है, बजाय उसे वहाँ से फिसलने देने के।

---

## 0.15 और 0.16 में क्या बदला

### Claude Code को tools फिर से दिखते हैं

अगर आपने हाल के Claude Code में octofs आज़माया और कुछ नहीं मिला, तो यही fix जानने लायक है। 2026-07-28 का MCP revision list और read results में cache hints (`ttlMs` और `cacheScope`) को अनिवार्य बनाता है। उस revision के लिए Claude Code का strict client इनके बिना आए results को reject कर देता था, इसलिए वह **octofs का एक भी tool load नहीं करता था**। 0.16.0 ये hints तब emit करता है जब client 2026-07-28 revision पर बात करता है, और पुराने connections को जस का तस छोड़ देता है।

### Background jobs जिन्हें आप `view` से पढ़ सकते हैं

Background job एक link के रूप में उपलब्ध होता है, `octofs://jobs/<id>`। मॉडल उस link पर सबसे पहले `view` की ओर हाथ बढ़ाते हैं, और Claude Code अपना generic resource reader tool search के पीछे रखता है, जिसमें एक अतिरिक्त round trip लगता है। इसलिए job link पर `view` job का status और output tail लौटाता है। **0.16.0 से यह job के exit होने का इंतज़ार करने के बजाय तुरंत लौटता है।** इस cycle का यही एक breaking change है, और इसकी वजह: मॉडल build को बीच में ही check कर सकता है और काम जारी रख सकता है।

Claude Code मॉडल को standard `resources/updated` notification भी नहीं दिखाता, इसलिए job का exit सेशन को नहीं जगाता। मॉडल result तब उठाता है जब उसे ज़रूरत होती है, link को view करके — इसीलिए वह read कभी block नहीं होना चाहिए।

0.16.0 में एक और guard: जब changes को stash करने वाली command (`git stash`) background में जाती है, तो response मॉडल को चेताता है कि command exit होने तक working tree में वे changes नहीं हैं, ताकि वह इस बीच files edit न करे या task को done न कह दे।

### Edits जो files को बिल्कुल वैसा ही छोड़ते हैं जैसी वे थीं

- **Line endings बची रहती हैं।** CRLF files replacements और insertions के बाद भी CRLF रहती हैं (0.15.5)।
- **आख़िरी blank lines बची रहती हैं**, और empty insert का मतलब अब कुछ नहीं के बजाय एक blank line है (0.16.0)।
- **Ambiguous operations reject होते हैं, उनका अंदाज़ा नहीं लगाया जाता।** ऐसी range के अंदर insert, जिसे वही batch replace या delete करता है, अब एक explanation के साथ fail होता है (0.15.0, 0.15.2)।
- **लंबे diffs पढ़ने लायक रहते हैं।** Edit result में लंबे exact replacement या लंबे added block का बीच का हिस्सा एक id range में collapse हो जाता है (0.16.0)।

### ऐसा shell जो मॉडल को dedicated tools पर रखता है

Octofs उन shell commands को reject करता है जो किसी dedicated tool का काम दोहराती हैं, जैसे `cat`, `grep` या `ls`, क्योंकि dedicated tools line ids लौटाते हैं और raw shell output नहीं। इस cycle ने उस gate को सटीक बनाया:

- **Blocked reads पकड़े जाते हैं, चाहे वे command की शुरुआत कहीं भी करें**: अकेले, `&&` या `;` के साथ chain में, `$(…)` के अंदर, या pipeline की शुरुआत में (0.16.0)। `cargo test 2>&1 | tail -20` जैसा बाद का pipe stage allowed रहता है।
- **Read-only `sed` और `awk` allowed हैं** (0.15.6)। stdout पर text stream करना ऐसा काम नहीं है जिसे कोई dedicated tool cover करता हो। In-place `sed -i` अब भी reject होता है, edit tools की ओर इशारे के साथ।
- **Redirects parse होते हैं** (0.16.0)। Octofs project में `echo`, `printf` या `cat` से file content लिखने को reject करता है, क्योंकि quoting content को ख़राब कर देती है। किसी program का output redirect करना, जैसे `cargo test > out.log`, allowed है।
- **हर rejection blocked program का नाम बताता है** और कहता है कि कुछ भी नहीं चला, इसलिए मॉडल compound command को पूरा retry करने के बजाय उसे तोड़ देता है (0.15.6)।

### Remote hosts और protocol

- `ssh://host` और `ssh://host/~/dir` login user के home के हिसाब से resolve होते हैं, जैसे `ssh host` करता है (0.15.0)।
- Remote trees पर content search ठीक की गई, और bare remote listing default रूप से सिर्फ़ एक level गहरी जाती है, क्योंकि हर subdirectory एक SFTP round trip का ख़र्च है (0.15.1)। SFTP layer `russh-sftp` 3.0 पर चली गई (0.16.0)।
- Published tool schemas में अब `$schema`, integer `format` tags और `default: null` जैसा generator noise नहीं रहता (0.16.0)। Tool definitions हर request के साथ भेजी जाती हैं, इसलिए उनमें सिर्फ़ वही होना चाहिए जिस पर मॉडल action लेता है।

---

## इसे swap करें: Claude Code

**1. Octofs install करें** (Homebrew, Cargo या npm):

```bash
brew install muvon/tap/octofs
# or: cargo install octofs
# or: npm install -g @muvon/octofs
```

**2. इसे हर project के लिए register करें:**

```bash
claude mcp add --scope user octofs -- octofs mcp
```

Claude Code server को उसी directory में शुरू करता है जहाँ से आपने `claude` launch किया था, और वही directory octofs का project root बन जाती है।

**3. Built-in editors बंद करें** `~/.claude/settings.json` में:

```json
{
	"permissions": {
		"allow": ["mcp__octofs"],
		"deny": ["Edit", "Write", "NotebookEdit"]
	}
}
```

हमारे numbers के पीछे यही setup है। `deny` में सिर्फ़ tool का नाम लिखने से वह tool मॉडल के context से पूरी तरह हट जाता है, और `mcp__octofs` हर octofs tool को बिना prompt के allow करता है। `Bash` और `Read` बने रहते हैं: हमारे runs में मॉडल ने अपने reads, edits और commands वैसे भी octofs से भेजे, और `Read` ही वह तरीका है जिससे Claude Code images और PDFs देखता है। `Bash` को भी deny करना उल्टा पड़ता है, क्योंकि इससे Claude Code के standalone `Glob` और `Grep` tools मॉडल के toolset में वापस आ जाते हैं।

## इसे swap करें: Codex

**1. Octofs जोड़ें और built-in shell बंद करें** `~/.codex/config.toml` में:

```toml
[features]
shell_tool = false
unified_exec = false

[mcp_servers.octofs]
command = "octofs"
args = ["mcp"]
default_tools_approval_mode = "approve"
```

Block को जैसा है वैसा paste करें, और साथ में `codex mcp add octofs` न चलाएँ: वह वही `[mcp_servers.octofs]` table लिखता है, और दो बार define की गई table के साथ Codex start होने से मना कर देता है। `shell_tool` और `unified_exec` Codex के दो command runners हैं। दोनों बंद हों तो हर command octofs के `shell` से गुज़रती है, background promotion समेत, और `default_tools_approval_mode` octofs tools को बिना approval prompt के चलने देता है।

**2. Edits को octofs की ओर मोड़ें।** Codex में उसके built-in `apply_patch` editor को बंद करने का कोई switch नहीं है ([openai/codex#8161](https://github.com/openai/codex/issues/8161) "not planned" कहकर बंद कर दिया गया), इसलिए मॉडल को `AGENTS.md` में बताएँ:

```markdown
## Tools

- Use octofs for all file and shell work: `view` to read, list and search; `batch_edit` or `text_editor` to edit; `shell` for builds, tests and git. Never use apply_patch.
- Put every call that doesn't depend on another call's result in one response.
- A command still running after ~10s becomes a background job. Don't wait for it: take the next step, and `view` its `octofs://jobs/<id>` link when you need the result.
```

यही block `CLAUDE.md` में भी काम करता है, हालाँकि हमारे runs में Claude Code ने इसके बिना भी octofs ही चुना।

---

## आज़माकर देखें

हमारे number को जाँचने का सबसे तेज़ तरीका है कोई ऐसा काम दोबारा करना जो आप पहले कर चुके हैं। कोई हाल का task चुनें, जैसे bug fix या ऐसा refactor जो कुछ files को छूता हो। उसे एक बार built-in tools के साथ और एक बार octofs के साथ चलाएँ, वही मॉडल और वही prompt, और wall-clock time और tokens की तुलना करें। उम्मीद रखें कि tokens लगभग उतने ही आएँगे। फ़र्क़ समय में दिखता है।

पहले से octofs इस्तेमाल कर रहे हैं? `brew upgrade muvon/tap/octofs`, `cargo install octofs` या `npm install -g @muvon/octofs` से upgrade करें, या [releases page](https://github.com/Muvon/octofs/releases) से Linux, macOS या Windows (x86_64 और ARM64) के लिए pre-built binary लें। एक behavioral note है: background-job link पर `view` अब job के exit होने तक block नहीं करता। अगर आपकी बनाई कोई चीज़ इस पर निर्भर थी, तो job ख़त्म होने के बाद link को दोबारा पढ़ें।

---

Octofs ओपन सोर्स है (Apache 2.0), [github.com/Muvon/octofs](https://github.com/Muvon/octofs) पर। [Octofs का परिचय](/blog/introducing-octofs) में बताया गया था कि हमने अपना filesystem server क्यों बनाया, [0.9.0](/blog/octofs-0-9-0-content-verified-line-ids) में कि line number पर भरोसा क्यों नहीं किया जा सकता, और [0.14](/blog/octofs-0-14-waiting-is-not-a-tool-call) में कि blocked tool call पर भी क्यों नहीं। यह पोस्ट इन तीनों का नतीजा है: जो एजेंट पहले से पता बातों को दोबारा जाँचना बंद कर देता है, वह वही काम दो से ढाई गुना तेज़ पूरा करता है।