Skip to content

Self-improving AI Employees for everyone

docs: update CLAUDE.md and deep_agent.md for filesystem nodes and create_agent

trohitg186d5a2faca4
diff --git a/CLAUDE.md b/CLAUDE.md
index ccbd958c..363171b3 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1213,6 +1213,21 @@ Residential proxy provider management with geo-targeting, session control, and a
- **javascriptExecutor**: **Dual-purpose node** - Execute JavaScript code via persistent Node.js server with syntax-highlighted editor and console output. Works as workflow node OR AI Agent tool (`javascript_code`).
- **typescriptExecutor**: **Dual-purpose node** - Execute TypeScript code via persistent Node.js server with type safety, syntax-highlighted editor and console output. Works as workflow node OR AI Agent tool (`typescript_code`).
+### Filesystem & Shell Nodes (4 nodes)
+Dual-purpose tool nodes delegating to `deepagents.backends.LocalShellBackend`. Workspace path configured via `DEEP_AGENT_WORKSPACE` env var (default: `./workspace`). Uses `virtual_mode=True` to confine paths.
+
+- **fileRead**: **Dual-purpose node** - Read file contents with line numbers and pagination. Works as workflow node OR AI Agent tool (`file_read`). Parameters: file_path, offset, limit.
+- **fileModify**: **Dual-purpose node** - Write new files or edit existing files with string replacement. Works as workflow node OR AI Agent tool (`file_modify`). Operations: write (create/overwrite), edit (find and replace with old_string/new_string/replace_all).
+- **shell**: **Dual-purpose node** - Execute shell commands with timeout. Works as workflow node OR AI Agent tool (`shell_execute`). Returns stdout, exit_code, truncated flag.
+- **fsSearch**: **Dual-purpose node** - Search the filesystem with three modes. Works as workflow node OR AI Agent tool (`fs_search`). Modes: ls (list directory), glob (pattern match), grep (search file contents).
+
+**Key Files:**
+| File | Description |
+|------|-------------|
+| `client/src/nodeDefinitions/filesystemNodes.ts` | 4 dual-purpose node definitions |
+| `server/services/handlers/filesystem.py` | Handlers delegating to `deepagents.backends.LocalShellBackend` |
+| `server/skills/coding_agent/` | Skills: file-read-skill, file-modify-skill, shell-skill, fs-search-skill |
+
### Utility Nodes (6 nodes)
- **httpRequest**: Make HTTP requests to external APIs (GET, POST, PUT, DELETE, PATCH) with configurable headers, body, timeout, and optional proxy support (`useProxy: true` routes through configured residential proxy)
- **webhookTrigger**: Event-driven trigger that waits for incoming HTTP requests at `/webhook/{path}` with method filtering and authentication options
diff --git a/docs-internal/deep_agent.md b/docs-internal/deep_agent.md
index 4bc8ca5b..78702735 100644
--- a/docs-internal/deep_agent.md
+++ b/docs-internal/deep_agent.md
@@ -23,22 +23,20 @@ Specialized agent node powered by [LangChain DeepAgents](https://github.com/lang
## Overview
-Deep Agent combines MachinaOs's existing agent infrastructure (skill injection, tool building, model resolution, memory) with the LangChain `deepagents` package, which provides a pre-configured middleware stack inspired by Claude Code.
+Deep Agent uses `langchain.agents.create_agent()` (the lower-level function from the `deepagents` package) to create a LangGraph agent that uses **only MachinaOs connected tool nodes** -- no built-in middleware tools. This ensures all tool executions show glow effects on the canvas.
-**What deepagents adds over standard LangGraph agents:**
-- Built-in filesystem tools (read, write, edit, ls, glob, grep, execute)
-- Todo-based planning via `write_todos` tool
-- Sub-agent delegation via `task` tool
-- Auto-summarization when conversations grow long
-- Prompt caching middleware (Anthropic models)
+**How it differs from chatAgent:**
+- Uses `langchain.agents.create_agent()` instead of `build_agent_graph()` for graph creation
+- Supports `PatchToolCallsMiddleware` for tool call formatting
+- 4 dedicated filesystem/shell tool nodes (fileRead, fileModify, shell, fsSearch) delegate to `deepagents.backends.LocalShellBackend`
**What MachinaOs provides:**
- Provider/model selection from `llm_defaults.json` (9 providers)
-- Executable tool node connections (calculator, search, WhatsApp, Android, etc.)
+- Executable tool node connections with glow effects (fileRead, fileModify, shell, fsSearch, calculator, search, WhatsApp, Android, etc.)
- Skill injection from Master Skill / SKILL.md files
- Memory via Simple Memory node (markdown + vector store)
- Teammate delegation via `input-teammates` handle
-- Real-time status broadcasting via WebSocket (including tool node glow effects)
+- Real-time status broadcasting via WebSocket
---
@@ -73,21 +71,22 @@ DeepAgentService.execute() server/services/agents/service.py
- ToolAdapter.build_tools() [agents/adapters.py] -> executable tools
- SubAgentAdapter.convert() [agents/adapters.py] -> deepagents SubAgent dicts
- _parse_memory_markdown() [ai.py] -> memory load
- - create_deep_agent() + ainvoke() [deepagents] -> graph execution
+ - langchain.agents.create_agent() [langchain] -> graph creation
+ - agent.ainvoke() -> graph execution
- ResponseExtractor.extract() [agents/adapters.py] -> response + thinking
- _append_to_memory_markdown() [ai.py] -> memory save
|
v
-deepagents.create_deep_agent() deepagents package
+langchain.agents.create_agent() langchain package (lower-level)
model = pre-built BaseChatModel (API key baked in)
- tools = executable MachinaOs tools + deepagents built-in tools
+ tools = ONLY MachinaOs connected tools (with glow effects via ToolAdapter)
system_prompt = system_message (includes skills + long-term memory context)
+ middleware = [PatchToolCallsMiddleware()] only (no built-in filesystem/todo)
|
v
agent.ainvoke(messages) LangGraph CompiledStateGraph
messages = history from SimpleMemory + current prompt
- Middleware stack: TodoList -> Filesystem -> SubAgent
- -> Summarization -> ToolCallPatching -> PromptCaching
+ No built-in middleware tools -- uses only connected MachinaOs tool nodes
|
v
ResponseExtractor.extract() -> save memory -> return result
@@ -127,7 +126,7 @@ agent = create_deep_agent(
Returns a **`CompiledStateGraph`** -- a compiled LangGraph graph compatible with streaming, Studio, checkpointers, and all LangGraph features.
-**Default model:** `claude-sonnet-4-6` (via `ChatAnthropic`). MachinaOs passes a pre-built `BaseChatModel` instance instead to avoid credential resolution issues.
+**Default model:** `claude-sonnet-4-6` (via `ChatAnthropic`). MachinaOs uses the lower-level `langchain.agents.create_agent()` instead, passing a pre-built `BaseChatModel` instance and no default middleware -- only connected MachinaOs tool nodes are used.
### Built-in Tools
@@ -326,7 +325,7 @@ Matches `execute_chat_agent` format for frontend compatibility:
| File | Description |
|------|-------------|
| `server/services/agents/__init__.py` | Public API: exports `DeepAgentService` |
-| `server/services/agents/service.py` | Orchestration: calls adapters, shared helpers, `create_deep_agent()` |
+| `server/services/agents/service.py` | Orchestration: calls adapters, shared helpers, `langchain.agents.create_agent()` |
| `server/services/agents/adapters.py` | `ToolAdapter`, `SubAgentAdapter`, `ResponseExtractor` |
| `server/services/agents/constants.py` | `PROVIDER_PREFIX`, `DEFAULT_MAX_TURNS` |
@@ -378,14 +377,14 @@ These work as standalone workflow nodes AND as AI agent tools when connected to
|--------|-----------|------------|-------------------|-----------|
| **Handler** | `handle_chat_agent` | `handle_deep_agent` | `handle_claude_code_agent` | `handle_rlm_agent` |
| **Service** | `AIService.execute_chat_agent()` | `DeepAgentService.execute()` | `ClaudeCodeService.execute()` | `RLMService.execute()` |
-| **Graph creation** | `build_agent_graph()` | `create_deep_agent()` | Claude Code CLI | RLM REPL loop |
-| **Built-in tools** | None | 9 (filesystem, todos, task) | 6 (Read, Edit, Bash, etc.) | 3 (llm_query, rlm_query, FINAL) |
-| **Connected tools** | Yes | Yes (executable) | No | Yes (bridged) |
+| **Graph creation** | `build_agent_graph()` | `langchain.agents.create_agent()` | Claude Code CLI | RLM REPL loop |
+| **Built-in tools** | None | None (uses only connected nodes) | 6 (Read, Edit, Bash, etc.) | 3 (llm_query, rlm_query, FINAL) |
+| **Connected tools** | Yes | Yes (executable, with glow) | No | Yes (bridged) |
| **Skills** | Yes | Yes | Yes (prompt only) | Yes |
| **Memory** | Yes (markdown + vector) | Yes (markdown + vector) | No | Yes (context only) |
| **Teammates** | Team leads only | Yes | No | No |
| **Providers** | All 9 | All 9 | Anthropic only | All 9 |
-| **Middleware** | None | 8-layer stack | None | None |
-| **Auto-summarization** | No | Yes | No | No |
-| **Planning** | No | Yes (`write_todos`) | No | No |
+| **Middleware** | None | PatchToolCallsMiddleware only | None | None |
+| **Auto-summarization** | No | No | No | No |
+| **Planning** | No | No | No | No |
| **Tool glow effects** | Yes | Yes | No | No |