Feature: File writing and code execution for Grok Swarm plugin

[KHAEntertainment]

Problem

Grok Swarm currently operates as a powerful consultant — it reads your entire codebase (up to 1.5M tokens), coordinates 4 agents to analyze it, and returns detailed results. However, it cannot write files or execute code directly.

Why This Matters

With a ~2M token context window, Grok can generate responses up to ~350K tokens. If that entire response floods back through the orchestrator's context window:

1. Wasted tokens — Valuable context space consumed by Grok's output
2. Slower responses — Orchestrator processes larger context
3. Inefficient workflow — User must manually copy-paste suggested code

Current Flow

Files (1.5M) → Grok → Full response (376K) → Orchestrator (flooded!)

Desired Flow

Files (1.5M) → Grok → Writes files + brief summary → Orchestrator (clean)

Proposed Solution

Implement a capability system where:

1. Core defines contract — FileSystemOperation or CodeExecution capabilities
2. Grok plugin implements contract — Can write files directly and execute code
3. Other tools could use same contract — Different implementations (local, cloud, etc.)
4. Orchestrator gets summary only — Clean context, efficient token usage

This aligns with OpenClaw's Capability Cookbook:

"Capability = shared core contract"
"Plugin = ownership boundary"

Use Cases

• Automated refactoring — Grok writes refactored files directly
• File manipulation — Create, move, delete files based on analysis
• Code execution — Run tests, linting, or builds after generation
• Batch operations — Process multiple files without orchestrator involvement

Examples

Security Audit with Auto-Write

/grok-swarm:analyze --write-fixes audit-report.json
# Grok writes files AND provides brief summary
# Orchestrator gets: "Found 3 issues, wrote fixes to audit-report/"

Refactor with Direct Write

/grok-swarm:refactor --output-dir src/refactored/ --apply
# Grok writes refactored code directly to files
# Orchestrator gets: "Refactored 5 files, see src/refactored/"

Code Generation + Execution

/grok-swarm:code --execute --run-tests
# Grok generates code, writes files, runs tests
# Orchestrator gets: "Generated feature, 3/5 tests passing"

Alternatives Considered

Approach	Pros	Cons
Consultant model (current)	Simple, works now	Token waste, manual copy-paste
File writing only	Better token usage	Still manual execution
Full capability system	Extensible, clean, future-proof	More complex, requires core changes

Recommendation

1. Short-term — Add file writing capability to Grok plugin (--write-fixes audit-report.json / --output-dir src/refactored/)
2. Medium-term — Propose FileSystemOperation contract to OpenClaw core
3. Long-term — Enable full CodeExecution contract for test execution, builds, etc.

Resources

• OpenClaw Capability Cookbook
• Plugin Architecture
• Current implementation: https://github.com/KHAEntertainment/grok-multiagent-plugin/tree/claude-plugin

[traycerai]

Plan

Observations

The plugin is a two-layer stack: src/plugin/index.ts (OpenClaw tool registration) spawns src/bridge/grok_bridge.py (Python/OpenAI SDK call). The bridge already has an --output flag that writes raw Grok output to a file, but the plugin layer (index.ts) never passes it through, and there is no summary-vs-full-response split. The orchestrator currently receives the entire Grok response as stdout.

Approach

Add write_files and output_dir parameters to the tool schema and wire them through the full stack: plugin → Node wrapper → Python bridge. The bridge will parse Grok's response for fenced code blocks, write each one to the target directory, and return only a compact summary to stdout. This keeps the orchestrator's context clean without requiring any OpenClaw core changes.

---

Implementation

1. Extend the Python bridge (src/bridge/grok_bridge.py)

Add --write-files and --output-dir CLI arguments in main():

• --write-files — boolean flag; when set, parse Grok's response and write extracted code blocks to disk
• --output-dir <path> — directory to write files into (defaults to ./grok-output/ if not specified)

Add a parse_and_write_files(response_text, output_dir) function that:

1. Scans the response for fenced code blocks annotated with a filename (e.g., ```ts:src/foo.ts or a // FILE: path comment convention)
2. Creates the output directory (and any subdirectories) if it does not exist
3. Writes each extracted block to its resolved path under output_dir
4. Returns a list of (relative_path, byte_count) tuples for the summary

Modify main() — after call_grok() returns:

• If --write-files is set, call parse_and_write_files() and print a compact summary to stdout instead of the full response:

  Wrote N files to <output_dir>/
    src/foo.ts (1,234 bytes)
    src/bar.ts (567 bytes)
  

• If --write-files is not set, preserve existing behaviour (print full response or write to --output).

Fenced block detection pattern — support at minimum:

• ```lang:path/to/file (GitHub-style with colon separator)
• A // FILE: path/to/file comment on the line immediately before a fenced block

---

2. Extend the Node wrapper (src/bridge/index.js)

Add two new CLI flags in parseArgs():

• --write-files — boolean flag (no value)
• --output-dir <path> — string

Forward them to Python in run() when building pyArgs:

if (opts.writeFiles) pyArgs.push('--write-files');
if (opts.outputDir)  pyArgs.push('--output-dir', opts.outputDir);

Update --help text to document the two new flags.

---

3. Extend the plugin schema and executor (src/plugin/index.ts)

Add two optional fields to GrokSwarmSchema:

• write_files: Type.Optional(Type.Boolean({ description: "Write generated files directly to disk; orchestrator receives a brief summary only" }))
• output_dir: Type.Optional(Type.String({ description: "Directory to write files into (default: ./grok-output/)" }))

Forward them in the args array inside execute():

if (params.write_files) args.push('--write-files');
if (params.output_dir)  args.push('--output-dir', params.output_dir);

Update the tool description to mention the new capability so the orchestrator agent knows when to use it.

---

4. Expose config knob in openclaw.plugin.json

Add an optional defaultOutputDir property to configSchema.properties so operators can set a project-level default output directory without passing it per-call.

In index.ts, resolve the output dir with precedence: params.output_dir → api.config?.defaultOutputDir → "./grok-output".

---

Data Flow After This Change

sequenceDiagram
    participant Orch as Orchestrator Agent
    participant Plugin as index.ts (Plugin)
    participant Node as index.js (Node wrapper)
    participant Py as grok_bridge.py
    participant Grok as Grok 4.20 API
    participant FS as File System

    Orch->>Plugin: grok_swarm({ prompt, mode, files, write_files:true, output_dir })
    Plugin->>Node: spawn(--write-files --output-dir ...)
    Node->>Py: spawn(--write-files --output-dir ...)
    Py->>Grok: chat.completions.create(...)
    Grok-->>Py: Full response (~350K tokens)
    Py->>FS: Write N files to output_dir/
    Py-->>Node: "Wrote 5 files to src/refactored/" (summary only)
    Node-->>Plugin: stdout = compact summary
    Plugin-->>Orch: { result: "Wrote 5 files to src/refactored/\n  src/foo.ts (1,234 bytes)..." }

Loading

---

Parameter Reference (after change)

Parameter	Layer	Type	Description
write_files	Plugin + Node + Python	bool	Parse response and write files; return summary
output_dir	Plugin + Node + Python	string	Target directory for written files
--write-files	Node + Python CLI	flag	Same as above
--output-dir	Node + Python CLI	string	Same as above
defaultOutputDir	openclaw.plugin.json	string	Operator-level default output dir

---

Files to Modify

File	Change
file:src/bridge/grok_bridge.py	Add --write-files, --output-dir args; add parse_and_write_files(); branch output logic in main()
file:src/bridge/index.js	Add --write-files, --output-dir to parseArgs(); forward to Python in run()
file:src/plugin/index.ts	Add write_files, output_dir to GrokSwarmSchema; forward in execute(); update description
file:src/plugin/openclaw.plugin.json	Add defaultOutputDir to configSchema
file:README.md	Document new parameters and usage examples

Import In IDE

🤖 Prompt for AI Agents

## Observations

The plugin is a two-layer stack: `src/plugin/index.ts` (OpenClaw tool registration) spawns `src/bridge/grok_bridge.py` (Python/OpenAI SDK call). The bridge already has an `--output` flag that writes raw Grok output to a file, but the plugin layer (`index.ts`) never passes it through, and there is no summary-vs-full-response split. The orchestrator currently receives the entire Grok response as `stdout`.

## Approach

Add `write_files` and `output_dir` parameters to the tool schema and wire them through the full stack: plugin → Node wrapper → Python bridge. The bridge will parse Grok's response for fenced code blocks, write each one to the target directory, and return only a compact summary to stdout. This keeps the orchestrator's context clean without requiring any OpenClaw core changes.

---

## Implementation

### 1. Extend the Python bridge (`src/bridge/grok_bridge.py`)

**Add `--write-files` and `--output-dir` CLI arguments** in `main()`:
- `--write-files` — boolean flag; when set, parse Grok's response and write extracted code blocks to disk
- `--output-dir <path>` — directory to write files into (defaults to `./grok-output/` if not specified)

**Add a `parse_and_write_files(response_text, output_dir)` function** that:
1. Scans the response for fenced code blocks annotated with a filename (e.g., ` ```ts:src/foo.ts ` or a `// FILE: path` comment convention)
2. Creates the output directory (and any subdirectories) if it does not exist
3. Writes each extracted block to its resolved path under `output_dir`
4. Returns a list of `(relative_path, byte_count)` tuples for the summary

**Modify `main()`** — after `call_grok()` returns:
- If `--write-files` is set, call `parse_and_write_files()` and print a compact summary to stdout instead of the full response:
  ```
  Wrote N files to <output_dir>/
    src/foo.ts (1,234 bytes)
    src/bar.ts (567 bytes)
  ```
- If `--write-files` is not set, preserve existing behaviour (print full response or write to `--output`).

> **Fenced block detection pattern** — support at minimum:
> - ` ```lang:path/to/file ` (GitHub-style with colon separator)
> - A `// FILE: path/to/file` comment on the line immediately before a fenced block

---

### 2. Extend the Node wrapper (`src/bridge/index.js`)

**Add two new CLI flags** in `parseArgs()`:
- `--write-files` — boolean flag (no value)
- `--output-dir <path>` — string

**Forward them to Python** in `run()` when building `pyArgs`:
```
if (opts.writeFiles) pyArgs.push('--write-files');
if (opts.outputDir)  pyArgs.push('--output-dir', opts.outputDir);
```

**Update `--help` text** to document the two new flags.

---

### 3. Extend the plugin schema and executor (`src/plugin/index.ts`)

**Add two optional fields to `GrokSwarmSchema`**:
- `write_files: Type.Optional(Type.Boolean({ description: "Write generated files directly to disk; orchestrator receives a brief summary only" }))`
- `output_dir: Type.Optional(Type.String({ description: "Directory to write files into (default: ./grok-output/)" }))`

**Forward them in the `args` array** inside `execute()`:
```
if (params.write_files) args.push('--write-files');
if (params.output_dir)  args.push('--output-dir', params.output_dir);
```

**Update the tool `description`** to mention the new capability so the orchestrator agent knows when to use it.

---

### 4. Expose config knob in `openclaw.plugin.json`

Add an optional `defaultOutputDir` property to `configSchema.properties` so operators can set a project-level default output directory without passing it per-call.

In `index.ts`, resolve the output dir with precedence: `params.output_dir` → `api.config?.defaultOutputDir` → `"./grok-output"`.

---

## Data Flow After This Change

```mermaid
sequenceDiagram
    participant Orch as Orchestrator Agent
    participant Plugin as index.ts (Plugin)
    participant Node as index.js (Node wrapper)
    participant Py as grok_bridge.py
    participant Grok as Grok 4.20 API
    participant FS as File System

    Orch->>Plugin: grok_swarm({ prompt, mode, files, write_files:true, output_dir })
    Plugin->>Node: spawn(--write-files --output-dir ...)
    Node->>Py: spawn(--write-files --output-dir ...)
    Py->>Grok: chat.completions.create(...)
    Grok-->>Py: Full response (~350K tokens)
    Py->>FS: Write N files to output_dir/
    Py-->>Node: "Wrote 5 files to src/refactored/" (summary only)
    Node-->>Plugin: stdout = compact summary
    Plugin-->>Orch: { result: "Wrote 5 files to src/refactored/\n  src/foo.ts (1,234 bytes)..." }
```

---

## Parameter Reference (after change)

| Parameter | Layer | Type | Description |
|---|---|---|---|
| `write_files` | Plugin + Node + Python | `bool` | Parse response and write files; return summary |
| `output_dir` | Plugin + Node + Python | `string` | Target directory for written files |
| `--write-files` | Node + Python CLI | flag | Same as above |
| `--output-dir` | Node + Python CLI | `string` | Same as above |
| `defaultOutputDir` | `openclaw.plugin.json` | `string` | Operator-level default output dir |

---

## Files to Modify

| File | Change |
|---|---|
| `file:src/bridge/grok_bridge.py` | Add `--write-files`, `--output-dir` args; add `parse_and_write_files()`; branch output logic in `main()` |
| `file:src/bridge/index.js` | Add `--write-files`, `--output-dir` to `parseArgs()`; forward to Python in `run()` |
| `file:src/plugin/index.ts` | Add `write_files`, `output_dir` to `GrokSwarmSchema`; forward in `execute()`; update description |
| `file:src/plugin/openclaw.plugin.json` | Add `defaultOutputDir` to `configSchema` |
| `file:README.md` | Document new parameters and usage examples |

---

Execution Information

Branch: master
Commit: 58f4951

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[KHAEntertainment]

Implemented in PR #5 - file writing capability added across plugin, Node wrapper, and Python bridge layers. Orchestrator now receives compact summary instead of full response.