plugin-coding-tools

Imported from gabrielmoreira/agent-skills-mirror (mirrors/repos/elizaOS@eliza/plugins/plugin-coding-tools/AGENTS.md). Install upstream with npx skills add gabrielmoreira/agent-skills-mirror --skill plugin-coding-tools. Copyright stays with the author.

@elizaos/plugin-coding-tools

Native coding tools (READ, WRITE, EDIT, FILE, SHELL, WORKTREE) for Eliza agents running in code/terminal/automation contexts.

Purpose / role

Adds filesystem operations, shell command execution, and git worktree management to an Eliza agent. The plugin is opt-in: it auto-enables when config.features.codingTools (or legacy config.features["coding-agent"]) is truthy and the runtime environment supports a terminal (disabled on ELIZA_BUILD_VARIANT=store and on iOS; Android only when ELIZA_RUNTIME_MODE=local-yolo). All actions are gated to contexts: ["code", "terminal", "automation"]. FILE and WORKTREE require roleGate: minRole=ADMIN; SHELL requires roleGate: minRole=OWNER.

Plugin surface

Actions

• FILE — umbrella for read/write/edit/grep/glob/ls. Dispatches to per-operation handlers. Relative file_path values for read/write/edit and relative path values for grep/glob/ls resolve against the conversation's SessionCwdService cwd before sandbox validation. Supports target=device for read/write/ls through a device_filesystem bridge service (mobile). Similes: FILE_OPERATION, FILE_IO.
• READ / WRITE / EDIT — strict, operation-specific schemas for direct coding loops. They delegate to the same FILE handlers and preserve its sandbox, stale-file, secret, and size checks.
• SHELL — action=run executes a command via /bin/bash -c and returns the complete accepted redacted stdout/stderr to the planner; output above the explicit 1,000,000-character capture ceiling is rejected with no partial result. read_output_artifact remains available for scoped artifacts retained by earlier runtimes. action=start_background starts a per-conversation background process and returns a stable handle; poll_background reads incremental stdout/stderr by absolute stream offsets and reports truncatedBefore; write_background writes stdin; kill_background terminates the process group with SIGTERM then SIGKILL escalation; list_background lists sessions; action=view_history/clear_history read or clear per-conversation command history (backed by the in-plugin ShellService (serviceType = "shell")). Per-call timeout (ms) is clamped to [100, 600000], default CODING_TOOLS_SHELL_TIMEOUT_MS (120000). Similes: BASH, EXEC, RUN_COMMAND.
• WORKTREE — umbrella for enter/exit git worktrees. On enter, registers new root in SandboxService and pushes to SessionCwdService stack. On exit, pops. Similes: GIT_WORKTREE.

Providers

• SHELL_HISTORY (src/shell/providers/shellHistoryProvider.ts, position 99) — injects complete conversation-scoped command history (redacted stdout/stderr/exit code), cwd, allowed directory, and file operations into context; fires only in terminal/code contexts.
• AVAILABLE_CODING_TOOLS — injects the available focused and umbrella tool names (READ, WRITE, EDIT, FILE, SHELL, WORKTREE) into agent state at position -10. Stable/agent-scoped cache.

Services

Other exports

• coding-agent-context (Zod schemas) — FileOperationSchema, CommandResultSchema, CapturedErrorSchema, etc. Used to validate structured outputs from coding loops.

Layout

plugins/plugin-coding-tools/
  src/
    index.ts                      Plugin entry — exports codingToolsPlugin, all services, types
    types.ts                      Service-type constants, ToolFailure/ToolResult types, CODING_TOOLS_CONTEXTS
    actions/
      file.ts                     FILE umbrella action — routes to per-op handlers
      direct-file-actions.ts      strict READ / WRITE / EDIT action wrappers
      bash.ts                     SHELL action implementation
      worktree.ts                 WORKTREE umbrella action
      read.ts / write.ts / edit.ts  FILE sub-handlers for read/write/edit
      grep.ts / glob.ts / ls.ts   FILE sub-handlers for grep/glob/ls
      enter-worktree.ts / exit-worktree.ts  WORKTREE sub-handlers
      index.ts                    Re-exports all action handlers
    providers/
      available-tools.ts          AVAILABLE_CODING_TOOLS provider
    services/
      sandbox-service.ts          Path policy (blocklist + allow-roots)
      file-state-service.ts       Per-conversation file mtime tracking
      session-cwd-service.ts      Per-conversation working directory + worktree stack
      background-shell-service.ts Per-conversation background shell sessions
      ripgrep-service.ts          @vscode/ripgrep wrapper
      coding-agent-context.ts     Zod schemas for coding-agent context types
      index.ts                    Re-exports all services
    lib/
      format.ts                   Param readers (readStringParam, readNumberParam), successActionResult, failureToActionResult
      path-utils.ts               Path predicates plus FILE input resolution against the session cwd
      run-shell.ts                runShell helper (child_process wrapper with timeout/streaming)
      run-git-command.ts          runGitCommand helper
      terminal-capabilities.ts    Platform capability detection
      secrets.ts                  detectSecrets — flags AWS/GitHub/OpenAI/etc. tokens to gate WRITE/EDIT
  auto-enable.ts                  Lightweight auto-enable module (env reads only; no plugin runtime imports)
  build.ts                        build script (Bun.build + tsc d.ts emit)

Commands

Scripts are defined in package.json; run them from the repo root with bun run --cwd:

bun run --cwd plugins/plugin-coding-tools clean         # remove build output
bun run --cwd plugins/plugin-coding-tools build         # build package artifacts
bun run --cwd plugins/plugin-coding-tools dev           # development build/watch lane
bun run --cwd plugins/plugin-coding-tools typecheck     # TypeScript typecheck
bun run --cwd plugins/plugin-coding-tools check         # package check alias
bun run --cwd plugins/plugin-coding-tools lint          # mutating Biome check
bun run --cwd plugins/plugin-coding-tools lint:check    # read-only Biome check
bun run --cwd plugins/plugin-coding-tools format        # write formatting
bun run --cwd plugins/plugin-coding-tools format:check  # read-only formatting check
bun run --cwd plugins/plugin-coding-tools test          # run package tests

Config / env vars

All settings are read via runtime.getSetting(key) or process.env. None are required.

The folded ShellService also retains compatibility settings for external consumers of runtime.getService("shell").exec() / executeCommand(). The canonical SHELL action above continues to use the CODING_TOOLS_* settings.

Foreground SHELL results accepted by the one-million-character complete-capture boundary are returned in full after redaction. A larger result fails explicitly and exposes no partial prefix. The action never substitutes a preview, summary, or optional artifact handle for model-facing stdout/stderr. For compatibility, action=read_output_artifact can still retrieve bounded pages from an unexpired opaque artifact issued by an earlier runtime, but only when its persisted agent and conversation scope match the requesting turn; state-root paths remain private.

Auto-enable keys (in agent config.features):

• config.features.codingTools (canonical) — true or { enabled: true }.
• config.features["coding-agent"] (legacy alias).

Runtime gating env vars (read by auto-enable.ts and index.ts):

• ELIZA_BUILD_VARIANT — if store, plugin is disabled.
• ELIZA_PLATFORM — android/ios disables unless local-yolo mode.
• ELIZA_RUNTIME_MODE / RUNTIME_MODE / LOCAL_RUNTIME_MODE — local-yolo enables on Android.

How to extend

Add a new FILE sub-operation

1. Create src/actions/<op>.ts exporting a <op>Handler function with the FileHandler signature ((runtime, message, state, options, callback) => Promise<ActionResult>).
2. Export it from src/actions/index.ts.
3. Add the op name to FILE_OPERATIONS in src/actions/file.ts and wire it into FILE_ACTIONS.
4. Validate paths through SandboxService.validatePath before any filesystem access.
5. Record reads via FileStateService.recordRead and check writability via FileStateService.assertWritable before write/edit ops.

Add a new top-level action

1. Create src/actions/<action>.ts exporting a const <name>Action: Action.
2. Export from src/actions/index.ts.
3. Import and add to the actions array in src/index.ts.
4. Use contexts: [...CODING_TOOLS_CONTEXTS] and contextGate: { anyOf: [...CODING_TOOLS_CONTEXTS] } so the action only fires in coding contexts.
5. Use roleGate: { minRole: "ADMIN" } for FILE/WORKTREE actions, or roleGate: { minRole: "OWNER" } for SHELL-equivalent actions — match the role of the existing action you are most similar to.

Add a new service

1. Extend Service from @elizaos/core. Implement static async start(runtime) and async stop().
2. Assign a string constant as serviceType in src/types.ts.
3. Export from src/services/index.ts.
4. Add to services array in src/index.ts and handle stop() in the dispose hook.

Conventions / gotchas

• READ/WRITE/EDIT paths may be absolute or relative. Relative paths resolve against SessionCwdService.getCwd(message.roomId); the resolved absolute path must still pass SandboxService.validatePath. A missing session-cwd service is an explicit failure.
• Always validate paths through SandboxService.validatePath before any filesystem access. Never bypass this.
• SHELL is trusted host execution, not filesystem confinement. CODING_TOOLS_WORKSPACE_ROOTS validates SHELL's cwd only. Commands may address paths outside those roots, so the OWNER role and deployment host/container boundary must be trusted.
• Read before write: FileStateService.assertWritable will reject a write if the file was modified externally since the last read. The agent must re-read first.
• conversationId = message.roomId (string-coerced). Missing roomId is a hard failure.
• Never throw from a handler — return failureToActionResult({ reason, message }) instead.
• The @vscode/ripgrep binary is resolved at RipgrepService start time; if that import fails it falls back to a system rg on PATH.
• The device_filesystem bridge (target=device on FILE) is provided by a separate service (device_filesystem service type) registered by a platform plugin (e.g. mobile). The coding-tools plugin does not register it — it only consumes it when present.
• Tests are co-located *.test.ts files beside their source in src/actions/, src/services/, and src/lib/. Integration tests live in __tests__/plugin-integration.test.ts at the package root.
• Import paths must use the .js extension on relative imports (ESM requirement).

Verification

Follow the repository-wide verification and evidence standard in the root CLAUDE.md. Run the package's relevant build, typecheck, lint, and test commands, then exercise the real integration boundary changed by the work. Inspect the produced domain artifacts and failure behavior; do not substitute mocked success for the system under test.

Verification receipts

SHELL owns command and test-output interpretation in the coding-tools plugin. Foreground results may include typed ActionResult.verification with kind, status, family, and exit code. Assistant policy consumes that receipt rather than interpreting command syntax or reassuring prose. Workspace delta receipts continue to bind verification to the execution domain and unchanged files; background polls, help commands, and empty test selections do not prove an edit.