🛡️ NTS MCP FileSystem Server

Next Transactional Server for Model Context Protocol

English | Русский | Releases

---

NTS_MCP_FS is an enterprise-grade File System server implementation for the Model Context Protocol (MCP).

It transforms standard file operations into a Transactional OS for AI Agents. Unlike basic tools that allow "blind" overwrites, NTS enforces Optimistic Locking, provides a Persistent HUD, and enables Atomic Scripting via programmable batches.

🚀 Key Differentiators

Feature	Standard MCP Server	NTS_MCP_FS
Integrity	Blind Overwrites (Last Write Wins)	Line Access Tokens (LATs) - Optimistic Locking
Operations	One file at a time	Programmable Atomic Batches (Multi-file Scripting)
Context	Stateless (Agent forgets plan)	AI-HUD & Built-in TODOs (Persistent Context)
Safety	Basic Ctrl+Z (if any)	Deep Undo & Checkpoints (Tracks file moves)
Code Intelligence	None	LSP Navigation & Semantic Refactoring (12 languages)
Verification	Manual testing	Syntax Check (Tree-sitter), Compilation & Test validation
Persistence	Stateless (in-memory only)	H2 Database (Transaction journal survives restarts)
Agent Memory	None (context lost on compression)	nts_context (HUD notes + snapshot recovery)
Profiling	None	JFR Profiler + Memory Analyzer (CPU/contention/GC/IO profiling, heap snapshots, allocation analysis)
Performance	Blocking I/O	Java Virtual Threads & Memory-Mapped I/O

---

📦 Installation & Usage

Prerequisites: Java 25+

Why Java 25+? NTS uses jdk.jfr.consumer streaming API improvements (JDK 25), enhanced jcmd diagnostic commands, and ScopedValue for task-scoped context propagation. Virtual Threads (preview in 21, production in 25) are used throughout for non-blocking I/O. Docker is available for environments that can't upgrade.

1. Quick Start (Auto-Integration)

Build and run the integrator to automatically configure supported clients (Gemini CLI, OpenCode, Codex, Claude Code, Qwen CLI, Cursor, LM Studio, Antigravity, Copilot VS Code).

./gradlew shadowJar
java -jar app/build/libs/app-all.jar --integrate

2. Manual Configuration

Add to your mcp-config.json:

{
  "mcpServers": {
    "NTS-FileSystem-MCP": {
      "command": "java",
      "args": [
        "-jar",
        "/absolute/path/to/nts-mcp-fs/app/build/libs/app-all.jar"
      ]
    }
  }
}

3. Docker (No Java Required)

Docker eliminates the need to install Java 25+ locally. The server runs in a container with project directories mounted as volumes.

Important: Docker Mode and Roots

In Docker, you must explicitly mount directories and specify them via NTS_DOCKER_ROOTS. These roots override any roots sent by the MCP client, because the client sends host paths that don't exist inside the container.

Option A: Use pre-built image (recommended)

docker pull ghcr.io/nefrols/nts-mcp-fs:latest

Single project:

{
  "mcpServers": {
    "NTS-FileSystem-MCP": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/home/user/myproject:/mnt/project",
        "-e", "NTS_DOCKER_ROOTS=/mnt/project",
        "ghcr.io/nefrols/nts-mcp-fs:latest"
      ]
    }
  }
}

Multiple projects:

{
  "mcpServers": {
    "NTS-FileSystem-MCP": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/home/user/project1:/mnt/p1",
        "-v", "/home/user/project2:/mnt/p2",
        "-e", "NTS_DOCKER_ROOTS=/mnt/p1:/mnt/p2",
        "ghcr.io/nefrols/nts-mcp-fs:latest"
      ]
    }
  }
}

Option B: Build locally

docker build -t nts-mcp-fs .
docker run -i --rm \
  -v /path/to/project:/mnt/project \
  -e NTS_DOCKER_ROOTS=/mnt/project \
  nts-mcp-fs

Environment variables:

Variable	Description
NTS_DOCKER_ROOTS	Required. Colon-separated list of root paths inside the container. Must match your -v mount points. Overrides client roots.
JAVA_OPTS	JVM options (default: -XX:+UseZGC -Xmx512m)
MCP_DEBUG	Set to true for debug logging
MCP_LOG_FILE	Path to log file (for clients that merge stderr/stdout)

Available image tags:

Tag	Description
latest	Latest stable release
1.2.3	Specific version
1.2	Latest patch of minor version
edge	Latest development build (main branch)

---

🎯 The Philosophy: Disciplined AI Through Intentional Friction

"The goal is not to make the agent's job easier — it's to make the agent's work reliable."

Most MCP servers optimize for convenience: fewer calls, shorter responses, maximum automation. NTS takes the opposite approach. It introduces intentional friction that forces AI agents to work with surgical precision.

The Problem: Catastrophic Drift in Long Sessions

When an AI agent works on a complex task (1-2M+ tokens), context summarization inevitably loses details. The agent "forgets" what it read 50 messages ago. Then:

1. 🔴 Agent edits line 347 based on stale memory
2. 🔴 Edit breaks something — agent panics
3. 🔴 Agent enters an uncontrolled fix-loop
4. 🔴 Hours of work destroyed in seconds

This isn't a bug — it's an emergent property of how LLMs handle long contexts. NTS is designed to prevent this failure mode.

The Solution: Forced Concentration via LAT

Line Access Tokens (LATs) are not just a security feature — they're a cognitive constraint.

┌─────────────────────────────────────────────────────────────────┐
│  Without LAT:                                                   │
│  "I'll just read the whole file... it's only 400 lines"        │
│   → Context bloated with "just in case" data                    │
│   → Summarization drops critical details                        │
│   → Agent edits wrong line from fuzzy memory                    │
│   → Catastrophic error                                          │
├─────────────────────────────────────────────────────────────────┤
│  With LAT:                                                      │
│  "I need to edit line 47. Let me read lines 40-55."            │
│   → Agent explicitly decides what it needs                      │
│   → Token proves agent saw current state                        │
│   → Context stays clean and precise                             │
│   → Edits are surgical and verified                             │
└─────────────────────────────────────────────────────────────────┘

The agent cannot read an entire file in one lazy command. It must specify ranges. This forces the agent to think before acting — exactly the discipline that prevents drift.

Why Verbose Responses Matter

Every nts_edit_file response includes a full unified diff. This isn't optional verbosity — it's mandatory validation.

--- User.java (original)
+++ User.java (modified)
@@ -15,7 +15,7 @@
     }
 
-    public String getName() {
+    public String getFullName() {
         return name;
     }

The agent sees the result immediately, in the same response. No separate "verify" step needed. No chance to "forget" to check. The diff is the proof.

Real-World Impact

Scenario	Standard Tools	NTS
2-hour refactoring session	40% chance of catastrophic error	Near-zero (checkpoint + undo)
Multi-file rename	Silent corruption possible	Atomic batch or full rollback
External file change mid-work	Agent overwrites user's edits	Token expires, agent warned
Agent "panics" after error	Uncontrolled fix spiral	Undo → stable state → retry

The Counterintuitive Truth

Spending 10% more tokens on discipline saves 100% of wasted work.

A 2-hour agent session costs ~$5-15 in API calls. A catastrophic error that destroys that work costs the same amount again to redo — plus human time to diagnose what went wrong.

NTS trades micro-efficiency for macro-reliability. The agent works slightly harder per-operation, but the entire session succeeds instead of collapsing at hour 1:45.

🧠 Advanced Features Deep Dive

1. 📟 Agent HUD (Heads-Up Display)

The server injects a status header into every tool response. The Agent never loses context.

[HUD tid:a1b2] Plan: Refactor Auth [✓2 ○1] → #3: Update Login | Task: 5 edits | Unlocked: 3 files
[MEMORY: Auth tokens must use RS256 | DB migration pending review]

• Task Context: Reminds the agent of the active Task ID.
• Progress Tracking: Shows current TODO status (Done/Pending) and the next active task.
• Safety Stats: Shows how many files are currently unlocked for editing.
• Agent Memory: Shows [MEMORY: ...] lines from nts_context HUD notes — critical reminders survive context compression.

2. 📜 Programmable Atomic Batches (Scripting)

The nts_batch_tools is not just a list of commands; it's a scripting engine for the file system.

• Atomic Transactions: 10 operations in one request. If the 10th fails, the previous 9 are rolled back instantly. The project is never left in a broken state.
• Variable Interpolation: Pass data between steps. Create a file in Step 1, then reference its path in Step 2 using {{step1.path}}.
• Virtual Addressing: Use variables like $LAST or $PREV_END+1 to insert code relative to previous edits without calculating line numbers.
• Virtual FS Context: When you edit a file in Step 1 and run nts_code_refactor in Step 2, the refactoring sees the modified content from Step 1, not the disk version. Enables complex chains like "edit class → rename symbol across project".

Example Script: "Create a service, rename it, and add a method"

"actions": [
  { "id": "cre", "tool": "nts_file_manage", "params": { "action": "create", "path": "Temp.java", "content": "class Svc {}" } },
  { "tool": "nts_file_manage", "params": { "action": "rename", "path": "{{cre.path}}", "newName": "UserService.java" } },
  { "tool": "nts_edit_file", "params": { "path": "{{cre.path}}", "startLine": "$LAST", "operation": "insert_after", "content": "void login() {}", "accessToken": "{{cre.token}}" } }
]

Note: {{cre.path}} automatically resolves to UserService.java after the rename step!

3. 🔒 Enterprise Security & Sandboxing

• Optimistic Locking (LATs): Agents must read a file to get a token (LAT:...) before editing. If the file changes externally, the token expires and the external change is automatically recorded in file history. No more race conditions.
• Smart Token Invalidation: Tokens track Range CRC instead of file CRC. Edits outside your token's range don't invalidate it — only changes to the specific lines you're working on trigger re-read. This dramatically reduces unnecessary token refreshes in large files.
• Path Aliasing: Tokens remain valid after move/rename operations. The system tracks file identity through path aliases with transitive resolution — even chains like A → B → C preserve token validity.
• Strict Sandboxing: All paths are normalized and pinned to the project root. Impossible to escape via ../../.
• Infrastructure Protection: Automatically blocks modification of .git, .env, and build configs unless explicitly allowed.
• OOM Protection: Prevents reading massive files (>10MB) that would crash the context window.
• Structured Error Codes: All errors include machine-readable codes (FILE_NOT_FOUND, TOKEN_EXPIRED, etc.) with human-readable solutions. No more cryptic exceptions — every error tells you exactly what went wrong and how to fix it.

4. ⏪ State Management: Checkpoints & Deep Undo

• Task Journal (H2 Database): Logs every logical step (not just file IO). Persisted in embedded H2 database — survives server restarts.
• In-Memory Snapshots: Undo engine uses in-memory byte[] snapshots instead of file-based backups for faster recovery.
• Checkpoints: Agent can run nts_task checkpoint('pre-refactor') and safely rollback if the approach fails.
• Deep Undo: The system tracks File Lineage. If you move FileA -> FileB and then hit Undo, NTS knows to restore content to FileA.
• Git Integration: Can create Git stashes as emergency fallbacks (git_checkpoint).

5. 👁️ External Change Tracking

The server automatically detects when files are modified outside of MCP (by user, linter, IDE, or other tools).

• CRC-based Detection: Each file read creates a snapshot. On next access, if the CRC differs, the change is detected.
• File History: External changes are recorded in file history and can be reviewed via nts_task journal.
• Smart Prompts: When an external change is detected, the agent receives a TIP recommending to review changes before proceeding, as they may be intentional user edits.
• Undo Support: If needed, external changes can be undone through the standard undo mechanism.

6. 💡 Smart Contextual TIPs

Every tool response includes intelligent contextual hints that guide the agent through optimal workflows.

• Workflow Guidance: After each operation, TIPs suggest the logical next step (e.g., "Token ready for editing → nts_edit_file(...)").
• Performance Hints: Large range reads trigger suggestions to use symbol-based navigation or grep for precision.
• Error Prevention: Pattern analysis detects regex-like queries used without isRegex=true and warns proactively.
• Token Management: When line counts change after edit, TIPs remind to use the NEW token for subsequent operations.
• Refactoring Awareness: Signature changes trigger suggestions to check call sites via nts_code_navigate(action='references').
• Import Updates: After move/rename of Java/Kotlin files, TIPs suggest searching for import statements that need updating.

Example TIPs in action:

[WORKFLOW: Token ready for editing -> nts_edit_file(path, startLine, content, accessToken)]
[TIP: Large range read (150 lines). Consider using 'symbol' parameter for precise symbol boundaries.]
[TIP: Pattern contains regex-like characters (.*). If you intended regex search, add isRegex=true parameter.]
[TIP: Line count changed (+5). Use NEW TOKEN above for subsequent edits to this file.]

7. ✅ Built-in TODO System

A specialized tool (nts_todo) allows the agent to maintain a Markdown-based plan.

• The active plan state is fed into the HUD.
• Keeps the agent focused on one task at a time.
• Auto-updates status (todo, done, failed) in the file system.

8. 🧭 LSP Navigation (Tree-sitter)

The nts_code_navigate tool provides IDE-like code intelligence powered by Tree-sitter.

• Go to Definition: Jump to where a symbol is defined.
• Find References: Locate all usages across the project.
• Hover: Get type, signature, and documentation for any symbol.
• List Symbols: File outline with all definitions.
• 12 Languages: Java, Kotlin, JS/TS/TSX, Python, Go, Rust, C/C++, C#, PHP, HTML.
• Extended Java Support: Enum constants as CONSTANT symbols, class-vs-constructor auto-resolution, kind filter and brief mode for compact output on large files.
• Structured Resolution Contract: Semantic actions now return resolutionStatus, resolutionKind, usedFallback, safeForAutonomousEdit, candidateCount, target, and candidates.
• Strict Mode: strict=true rejects fallback and ambiguous cursor resolution instead of silently guessing a target.
• Ambiguity Signaling: Overload or nearby-cursor ambiguity is returned explicitly so an agent can stop before making an unsafe edit.

9. 🔄 Semantic Refactoring (10 Operations)

The nts_code_refactor tool performs intelligent code transformations.

• Rename: Byte-span rewrite (UTF-8 safe) with overload-aware SymbolHandle matching. Updates ALL references across the entire project.
• Change Signature: AST-rewrite of declarations and call sites. Action-based parameters (add, remove, rename, retype, reorder) with automatic overload disambiguation.
• Extract Method: Pull code into a new method with safety validation (escaping variable detection) and smart return type inference.
• Extract Variable: Span-precise extraction with occurrence normalization, balanced-expression validation, and replaceAll support.
• Inline: AST-aware call-site rewriting with argument substitution, precedence-safe parenthesization, and multi-occurrence support.
• Move: Relocate classes/methods with static method reference updates, import rewiring, and instance-method safety guards.
• Wrap: Wrap code in try-catch, if-block, or loop with escaping-variable scope check.
• Delete: Statement-level rewriting (findStatementSegment) instead of whole-line deletion. Overload-safe via signature/position.
• Generate: Create getters, setters, constructors, builders, toString, equals/hashCode with final-field safety and duplicate detection.
• Batch: Combine multiple refactoring operations atomically with parameter normalization and inheritance.
• Preview Mode: Review diff before applying (preview: true).
• Parallel Reference Search: Both nts_code_navigate and nts_code_refactor use parallel file scanning with pre-filtering, searching up to 15 levels deep for maximum coverage.
• Batch Integration: Successful apply responses return an affectedFiles array with tokens for each modified file — enables chaining like refactor → edit in nts_batch_tools.
• Structured Validation: Semantic previews/applies expose machine-readable validation metadata and affectedFileCount.
• Rollback on Invalid Output: All mutating operations validate changed files through SyntaxChecker after apply and rollback atomically on syntax breakage.
• Risk Metadata: Every response includes confidence (exact/mixed), riskLevel (low/medium), rewriteStrategy (semantic_span/hybrid_span/line_fallback), and detailed validation object.
• Hybrid Transparency: Hybrid rename previews expose hybridMode, semanticMatchCount, textOnlyMatchCount, and provenance so text-only matches are never hidden.

{
  "action": "rename",
  "path": "src/User.java",
  "symbol": "getName",
  "newName": "getFullName",
  "preview": true
}

Preview response exposes structured validation and file counts:

{
  "status": "preview",
  "affectedFileCount": 2,
  "hybridMode": false,
  "semanticMatchCount": 2,
  "validation": {
    "targetCountExpected": 2,
    "targetCountMatched": 2,
    "declarationCountUpdated": 1,
    "callSiteCountUpdated": 1,
    "astParseAfterEdit": true
  }
}

Apply response includes batch-ready tokens:

{
  "status": "success",
  "affectedFileCount": 1,
  "affectedFiles": [
    { "path": "src/User.java", "accessToken": "LAT:...", "crc32c": "A1B2C3D4", "lineCount": 50 }
  ],
  "token": "LAT:..."
}

10. 🧠 Agent Context Memory (nts_context)

The nts_context tool gives the agent a structured, task-scoped memory — a native alternative to manually editing a MEMORY.MD file.

• HUD Notes (kind='hud_note'): Critical reminders that appear in every tool response via the HUD line. Survive context compression and prompt summarization.
• Context Notes (kind='note'): Broader findings, root causes, user constraints — stored for recovery but not shown on every response.
• Importance Levels: critical > high > normal — controls display priority and sorting.
• Snapshot Recovery: action='snapshot' returns a complete task picture: TODO progress, recently modified files, last 5 journal operations, active HUD notes, all context notes, and a suggested next action. Designed for re-orientation after context compression.
• CRUD API: add, read, update, delete, list — full lifecycle management.
• Contextual Prompts: Other tools (nts_edit_file, nts_todo, nts_verify) gently nudge the agent to save durable findings via TIP hints.

Agent discovers root cause → saves as hud_note
  → Every subsequent tool response shows: [MEMORY: Auth tokens must use RS256]
  → Context compressed after 500 messages
  → Agent calls snapshot → full picture restored in one call

11. ☕ Java Development Suite

NTS provides extended Java support beyond the general 12-language tree-sitter capabilities. While AST navigation, refactoring, and syntax checking work across all supported languages, the Java ecosystem gets dedicated high-level tools designed for maximum agent productivity with minimum cognitive load.

Design philosophy: Every Java tool operates at the highest abstraction level. The agent doesn't manage JFR sessions, parse histograms, or construct Gradle commands from scratch — it states intent ("profile this", "build the project", "show me the heap") and receives actionable results. This reduces cognitive load, saves tokens, and lets the agent focus on the problem, not the tooling.

AST Intelligence (Extended for Java)

The tree-sitter-based nts_code_navigate and nts_code_refactor support 12 languages, but Java gets enhanced capabilities:

• Enum constant extraction — enum values appear as CONSTANT symbols in navigation
• Constructor-aware rename — class rename automatically renames all constructors (Java requires constructor name = class name)
• Import-aware move — moving classes triggers import update suggestions via Smart TIPs
• Overload disambiguation — method signature matching uses structured AST parameters, not string heuristics
• Symbol filtering — symbols(kind='method', brief=true) gives compact output for large classes (saves tokens on 2000+ line files)

Gradle Build Integration (nts_gradle_task)

High-level build automation — the agent says "build" or "test" without thinking about wrapper scripts or platform specifics.

• Smart backend switching: Uses gradlew if present, falls back to system gradle, or auto-generates wrapper
• Project initialization: task='init', initType='java-application' creates a complete project scaffold
• Parsed output: Compilation errors come back with file:line references. Test results include pass/fail/skip counts
• Async support: Long builds return a processId — the agent can continue other work and poll via nts_process

JFR Profiler (nts_java_profiler)

One call profiling — attach to any JVM, record, parse, and get an executive summary in a single tool call.

discover → profile(focus='cpu', 30s) → analyze(focus='contention') → compare(before, after)

• 6 focus areas: cpu, cpu-time (JDK 25+), memory, contention, gc, io, or all
• Re-analyze without re-recording: Same recording, different focus — saves time and tokens
• Delta comparison: Before/after analysis with normalized per-second rates
• Enhanced contention: JavaMonitorEnter, Object.wait(), ThreadPark — with call sites and blocked thread ranking
• Smart hints: NIO servers with empty IO data get an NIO-specific suggestion. ZGC with minimal pauses gets a pauseless collector note

Memory Analyzer (nts_java_memory)

Answers "what's on the heap?" and "what's being allocated?" — separate from the profiler because these are fundamentally different questions.

snapshot(baseline) → exercise code → snapshot(after) → compare → find leak candidates

• Instant histograms: jcmd GC.class_histogram — results in milliseconds, no recording needed
• Leak detection workflow: Two snapshots → compare → classes with biggest growth = leak candidates
• Allocation pressure: JFR-based allocation recording shows top types by allocation rate with call sites
• Auto-verdict: Snapshot compare includes automated "leak signal" / "no leak signal" conclusion

Why Java Gets Special Treatment

Aspect	General (12 languages)	Java (extended)
Navigation	symbols, hover, definition, references	+ enum constants, constructor-aware rename, overload disambiguation
Build	—	Gradle integration with init, build, test, async
Profiling	—	JFR profiler with 6 focus areas, re-analyze, compare
Memory	—	Heap snapshots, leak detection, allocation analysis
Verification	Tree-sitter syntax check	+ Gradle compilation + test execution

---

🛠️ The Toolchain: A Discipline System, Not Just Utilities

Each tool in NTS is designed as part of an interconnected discipline system. They don't just perform operations — they enforce a workflow that keeps the agent focused, verified, and recoverable.

┌─────────────────────────────────────────────────────────────────────────────┐
│                        THE NTS DISCIPLINE LOOP                              │
│                                                                             │
│   ┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐          │
│   │  INIT    │────▶│  READ    │────▶│  EDIT    │────▶│  VERIFY  │          │
│   │  Task    │     │ + Token  │     │ + Token  │     │(Diff/AST)│          │
│   └──────────┘     └──────────┘     └──────────┘     └────┬─────┘          │
│        │                                                   │                │
│        │              ┌──────────┐                         │                │
│        └─────────────▶│  UNDO    │◀────────────────────────┘                │
│         (if panic)    │ Recovery │    (if wrong)                            │
│                       └──────────┘                                          │
└─────────────────────────────────────────────────────────────────────────────┘

---

🔐 nts_init — The Accountability Boundary

Why it exists: Creates an isolated task with its own undo history, checkpoints, and token registry.

Discipline role: Everything the agent does is tracked. There's no "anonymous" editing. If something breaks, the task journal knows exactly what happened and when.

Task Reactivation: If the server restarts or connection drops, the task can be reactivated:

{ "taskId": "your-previous-uuid" }

This restores the task directory with todos and file history. In-memory state (tokens, undo stack) starts fresh, but disk-persisted data (H2 journal) is preserved.

Connection: All other tools require taskId. This isn't bureaucracy — it's traceability.

Sub-Tasks (parallel agents):

When multiple agents work on the same codebase simultaneously (e.g., one refactors backend, another updates frontend), sub-tasks provide isolated undo/redo stacks while sharing the same project roots.

                    ┌─────────────┐
                    │  nts_init() │  ← Parent agent
                    │  taskId: A  │
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              ▼                         ▼
    ┌─────────────────┐     ┌─────────────────┐
    │ nts_init(        │     │ nts_init(        │
    │  parentTaskId=A) │     │  parentTaskId=A) │
    │ taskId: A:sub-x  │     │ taskId: A:sub-y  │
    │ [own undo stack] │     │ [own undo stack] │
    └────────┬────────┘     └────────┬────────┘
             │                       │
             ▼                       ▼
    ┌─────────────────┐     ┌─────────────────┐
    │ merge → parent  │     │ rollback (fail)  │
    │ (one undo entry)│     │ (all reverted)   │
    └─────────────────┘     └─────────────────┘

Lifecycle:

// 1. Sub-agent creates isolated sub-task
{"parentTaskId": "A"}
→ {"taskId": "A:sub-x1b2c3d4", "isSubTask": true}

// 2. Sub-agent works using sub-taskId in all calls
{"taskId": "A:sub-x1b2c3d4", "path": "Backend.java", ...}

// 3a. On SUCCESS — merge into parent (one grouped undo entry)
{"action": "merge", "childTaskId": "A:sub-x1b2c3d4", "taskId": "A"}

// 3b. On FAILURE — rollback all sub-task edits
{"action": "rollback", "childTaskId": "A:sub-x1b2c3d4", "taskId": "A"}

Key rules:

• Sub-tasks inherit workingDirectory and project roots from parent
• Sub-tasks have their own undo/redo stack, file tokens, TODO plans
• After merge, parent can undo ALL sub-agent edits with one nts_task(action='undo')
• Different files only: sub-tasks are designed for agents editing non-overlapping files. CRC tokens will block the second writer if two sub-tasks try to edit the same file region
• Don't use sub-tasks for simple sequential workflows — they add overhead

---

📖 nts_file_read — The Attention Gate

Why it exists: Reads file content and issues a Line Access Token (LAT).

Discipline role: The agent must explicitly decide which lines it needs. No "just read everything" shortcut.

❌ read({ path: "file.java" })                    // NOT ALLOWED
✅ read({ path: "file.java", startLine: 10, endLine: 30 })  // Forced precision

Connection: The token returned here is required for nts_edit_file. Read → Token → Edit. No shortcuts.

Smart TIPs: Responses include workflow hints (e.g., "Token ready for editing") and suggest symbol-based reading for large ranges.

Bulk Read: Read multiple related files in a single request:

{
  "bulk": [
    { "path": "UserService.java", "symbol": "createUser" },
    { "path": "UserRepository.java", "symbol": "save" },
    { "path": "User.java", "startLine": 1, "endLine": 30 }
  ]
}

Each file is separated in output with its own TOKEN. Errors in one file don't affect others.

---

✏️ nts_edit_file — The Verified Mutation

Why it exists: Applies line-based edits with mandatory token validation.

Discipline role:

1. Token required — proves agent read the current state
2. Diff in response — agent immediately sees what changed
3. CRC check — if file changed externally, edit fails safely
4. Smart TIPs — contextual hints for common issues:
   • Multi-line content replacing single line without endLine → suggests insert_after or range
   • Line count changed → reminds to use NEW token for subsequent edits
   • Signature change detected → suggests checking call sites with nts_code_navigate
   • Significant changes → reminds to run tests

Connection: Consumes token from nts_file_read, produces new token for subsequent edits. Chain of custody is unbroken.

---

📁 nts_file_manage — Structure with Memory

Why it exists: Create, delete, move, rename files and directories.

Discipline role:

• create returns a token — new files are immediately editable
• rename/move transfers tokens via path aliasing — tokens remain valid even after the file is moved (transitive chains like A → B → C work)
• delete invalidates tokens — no editing ghosts

Connection: Works with nts_batch_tools for atomic multi-file restructuring. Path aliases persist across the task.

---

🔍 nts_file_search — Discovery with Intent

Why it exists: Find files (glob), search content (grep), view structure.

Discipline role: grep returns tokens for matched ranges. The agent can search and immediately edit without a separate read step.

grep("TODO") → finds line 47 → returns TOKEN for lines 45-50
           → agent can edit lines 45-50 directly

Smart TIPs: After grep, workflow hints remind that tokens are ready for direct editing. If pattern looks like regex but isRegex=false, suggests enabling it.

Connection: Bridges discovery and action. Reduces round-trips while maintaining token discipline.

---

⏪ nts_task — The Panic Button

Why it exists: Undo, redo, checkpoints, rollback, and task journal.

Discipline role: When the agent makes a mistake, it has structured recovery instead of uncontrolled fix-spiraling.

checkpoint("before-risky-refactor")
  → try dangerous changes
  → if wrong: rollback("before-risky-refactor")
  → project restored in one command

Connection: This is the safety net that makes aggressive refactoring possible. Agents can be bold because recovery is guaranteed.

---

🔗 nts_batch_tools — Atomic Scripting

Why it exists: Execute multiple tools as a single atomic transaction.

Discipline role: Complex operations either fully succeed or fully rollback. No half-broken states.

{
  "actions": [
    { "id": "svc", "tool": "nts_file_manage", "params": { "action": "create", "path": "Service.java" }},
    { "tool": "nts_edit_file", "params": { "path": "{{svc.path}}", "accessToken": "{{svc.token}}", ... }}
  ]
}
// If edit fails → create is rolled back → project untouched

Connection: Uses {{step.token}} interpolation. Tokens flow between steps automatically. This is the culmination of the discipline system.

---

🔄 nts_project_replace — Controlled Mass Mutation

Why it exists: Global search and replace across the entire project.

Discipline role:

• dryRun: true shows all changes before applying
• Atomic: all files changed or none
• Creates automatic checkpoint before execution

Connection: High-risk operation with maximum safeguards.

---

🧭 nts_code_navigate — Semantic Understanding

Why it exists: Go to definition, find references, hover info, symbol listing.

Discipline role: Agent can understand code structure before editing. Reduces guesswork, increases precision.

Structured response contract:

• resolutionStatus: exact, ambiguous, fallback, or not_found
• resolutionKind: how the semantic target was resolved
• usedFallback: whether resolver had to weaken precision
• safeForAutonomousEdit: whether the result is safe to feed into autonomous edits
• candidateCount: number of semantic candidates considered
• target: the selected SymbolHandle when one exact target exists
• candidates: candidate summary when the target is ambiguous

Extended Java Support: Enum constants as CONSTANT symbols, class-vs-constructor auto-resolution, kind filter and brief mode for compact output on large files.

Connection: Returns tokens for found locations. Navigate → understand → edit with confidence.

---

🔧 nts_code_refactor — Intelligent Transformation

Why it exists: Rename symbols, change signatures, generate code, extract methods — with automatic reference updates.

Discipline role:

• preview: true shows all affected files before applying
• Semantic rename updates ALL references, not just text matches
• Atomic: entire refactoring succeeds or fails together
• Returns tokens for all modified files — enables refactor → edit chains in batches
• Semantic refactors expose machine-readable validation and affectedFileCount
• Standard semantic rename no longer mixes in text-search fallback unless hybridMode=true
• Hybrid rename explicitly reports semanticMatchCount, textOnlyMatchCount, and provenance
• Apply path validates syntax and rolls back on invalid output instead of returning false success

Connection: Uses tree-sitter for precision. Integrates with nts_batch_tools via {{step.affectedFiles[0].accessToken}} interpolation. Safer than manual multi-file editing.

---

📋 nts_todo — The Focus Anchor

Why it exists: Maintains a Markdown-based task list integrated with the HUD.

Discipline role: Keeps the agent focused on one task at a time. The HUD constantly reminds what's next.

[HUD] Plan: Auth Refactor [✓2 ○3] → #3: Update Login Controller

Connection: Prevents scope creep. Agent always knows the current objective even after context summarization.

---

🔀 nts_git — Version Control Integration

Why it exists: Git status, diff, add, commit — without leaving NTS.

Discipline role:

• git_checkpoint creates stash as emergency backup
• commit_task auto-generates commit message from TODO progress
• Safe operations only (no push/force)

Connection: Integrates with task journal. Commits can reference completed tasks.

---

📊 nts_compare_files — Visual Verification

Why it exists: Shows unified diff between any two files.

Discipline role: Agent can verify changes by comparing before/after states explicitly.

Connection: Useful for reviewing results of batch operations or refactoring.

---

⚙️ nts_gradle_task — Build Feedback Loop

Why it exists: Run Gradle tasks (build, test, check) with parsed output.

Discipline role: Agent gets immediate feedback on whether changes broke the build. Errors are parsed and actionable.

Connection: Closes the loop: Edit → Build → Fix → Repeat.

---

✅ nts_verify — Multi-Level Validation

Why it exists: Verify code correctness at three levels: syntax, compilation, and tests.

Discipline role:

• syntax — Fast tree-sitter AST check (no build needed). Catches errors instantly after edits.
• compile — Runs gradlew build -x test for compilation verification.
• test — Runs gradlew test for full test validation.

Connection: Bridges editing and building. Agent verifies syntax without a full build cycle, escalating to compilation/tests only when needed.

---

🔍 nts_context — Unified Task Context

Why it exists: Provides a single place for HUD reminders and full task-context recovery after compression.

Discipline role:

• add/update/read/delete/list manage task-scoped context entries
• kind='hud_note' creates always-visible HUD reminders
• kind='note' stores broader findings and recovery notes
• snapshot returns the current task picture when the agent needs to re-orient
• The tool behaves like a structured internal MEMORY.MD, but with explicit actions instead of manual file editing

When the agent loses context due to prompt summarization, snapshot returns:

• Current task ID and stats
• TODO progress (if active)
• Recently modified files
• Recent journal entries (last 5 operations)
• Active HUD notes
• All stored context notes
• Suggested next action

Connection: Combines always-on reminders and recovery context into one native tool. The agent can ask "what must I remember?" and "where am I?" from the same surface, while prompt hints gently push it to preserve only durable, high-value context.

---

🖥️ nts_process — Background Process Management

Why it exists: Monitor and control long-running background processes (Gradle builds, Git operations).

Discipline role: Agent can retrieve logs or kill async processes without blocking the main workflow.

Connection: Works with nts_gradle_task and nts_git for async operations.

---

☕ Java Development Suite (nts_gradle_task + nts_java_profiler + nts_java_memory)

Why it exists: Java gets dedicated high-level tools that operate at the intent level — "build", "profile CPU for 30s", "show me the heap" — with all complexity handled internally.

Discipline role: The agent never manages JFR sessions, parses raw histograms, or constructs Gradle command lines. Each tool returns actionable, agent-friendly output. Re-analyze without re-recording saves tokens. Snapshot compare auto-generates leak verdicts. Build errors come back with file:line references.

Connection: Integrates with nts_context for persisting findings, nts_verify for build feedback, and nts_process for async builds.

---

The System as a Whole

These tools aren't independent utilities. They form a closed discipline loop:

1. Task establishes accountability
2. Read forces attention and issues tokens
3. Edit requires tokens and shows results
4. Verify validates changes (syntax → compile → test)
5. Task provides recovery when needed
6. Batch enables complex operations atomically
7. HUD + TODO maintains focus across long sessions
8. Context preserves durable reminders and recovers the task picture after compression
9. Java Suite provides build, profiling, and memory analysis for the full Java development lifecycle

Every tool reinforces the others. There's no escape hatch to "just edit blindly." The discipline is architectural.

---

See also: Русская версия | Releases | License