octoflow-tools

Ready-made OctoFlow action factories and presets. Use this package when your agent needs filesystem helpers, git, web fetch/search, HTTP, task boards, artifacts, data tools, memory, communication, or subagent tools without writing every action by hand.

Install

npm install octoflow-core octoflow-tools

Node.js >=20 is required.

Default tools (4)

allTools() ships minimal. These 4 tool-names are always included:

| Tool | What it does | | ---------------- | ------------------------------------------------------------------------------------------------ | | filesystem | Read, edit, delete, search files (intent = read | edit | delete | search_files | find_files) | | list_directory | List directory contents — name, type, path per entry | | bash | Run a bash command → stdout, stderr, exitCode | | fetch | Fetch a URL — mode: text (default), html, links, meta, tables, raw |

web_search, current_time, and every other group are opt-in: allTools({ webSearch: true, datetime: true }).

Opt-in tool groups

Every group is a key on ToolsConfig. Pass true for defaults or an options object to customise. Absent / false means the group is not included.

import { tools } from 'octoflow-tools';

const myTools = tools({
  cwd: process.cwd(), // shared default for cwd-aware tools
  basePath: '/project', // path guard root for filesystem / csv / pdf / image / archive
  timeout: 30_000, // ms — applied to HTTP and shell tools

  // ── Always on in allTools() ──────────────────────────────
  filesystem: true, // → filesystem, list_directory
  bash: true, // → bash
  fetch: true, // → fetch

  // ── Search & time (opt-in) ──────────────────────────────
  webSearch: true, // → web_search
  datetime: true, // → current_time

  // ── VCS ─────────────────────────────────────────────────
  git: true, // → git_status, git_diff, git_log, git_branch, git_show
  git: { allowWrite: true }, // also adds git_commit, git_stash

  // ── Agent state ──────────────────────────────────────────
  tasks: true, // → task_write, task_list, task_get, task_summary
  tasks: { allowDelete: true }, // also adds task_delete
  artifacts: true, // → artifact_write, artifact_get, artifact_list, artifact_search
  artifacts: { allowDelete: true }, // also adds artifact_delete

  // ── Data ─────────────────────────────────────────────────
  json: true, // → json_parse
  math: true, // → calculate
  text: true, // → regex_match
  csv: true, // → csv_parse, csv_query, csv_stats, csv_convert
  sql: true, // → sql_query, sql_schema, sql_tables
  pdf: true, // → pdf_info, pdf_to_text
  image: true, // → image_metadata, image_to_base64, image_from_base64

  // ── System / OS ──────────────────────────────────────────
  archive: true, // → archive_gzip, archive_gunzip, archive_zip, archive_unzip, archive_list, archive_tar
  crypto: true, // → crypto_hash, crypto_hmac, crypto_uuid, crypto_random, crypto_encrypt, crypto_decrypt, crypto_base64
  docker: true, // → docker_ps, docker_run, docker_exec, docker_logs, docker_images, docker_stop
  environment: true, // → system_info, get_env, which
  validation: true, // → validate, validate_json_schema
  scheduler: true, // → scheduler_wait, scheduler_cron_next, scheduler_cron_explain

  // ── Third-party web ──────────────────────────────────────
  tavily: true, // → tavily_search, tavily_extract         (needs TAVILY_API_KEY)
  youtube: true, // → youtube_info, youtube_transcript
  wikipedia: true, // → wikipedia_search, wikipedia_summary, wikipedia_article

  // ── Legacy web (used in webTools() preset) ───────────────
  web: true, // → web_fetch   (mode: text/html/links/meta/tables)
  http: true, // → http_request (GET / HEAD / POST / PUT / DELETE / PATCH)

  // ── OctoFlow platform ────────────────────────────────────
  codeAnalysis: true, // → typecheck, lint, run_tests, npm_install
  config: true, // → read_config, resolve_config, validate_config
  llmStatus: true, // → list_backends, check_cli_tools
  brain: true, // → brain_remember, brain_recall, brain_digest, brain_consolidate,
  //   brain_prune, brain_replay, brain_feedback, brain_audit, brain_resolve_contradiction
  communication: true, // → topic_publish, topic_publish_wait, topic_replay
  //   mesh_send, mesh_broadcast, mesh_request, mesh_inbox, mesh_reply,
  //   mesh_multicast, mesh_discover, mesh_list
});

Duplicate keys in the example above (git, tasks, artifacts) are shown for illustration only — in real code pick the form you need.

Disable a default

allTools({ bash: false }); // remove bash from the default bundle
allTools({ fetch: false }); // remove fetch (e.g. offline / air-gapped sessions)

Complete tool reference

All 103 tool names grouped by factory:

Filesystem & shell

| Tool | Description | | ---------------- | ----------------------------------- | | filesystem | Read / edit / delete / search files | | list_directory | List directory contents | | bash | Run a bash command |

Web

| Tool | Description | | -------------------- | ---------------------------------------------------- | | fetch | Unified fetch — text, html, links, meta, tables, raw | | web_search | DuckDuckGo (web or news) | | web_fetch | Legacy parsed web fetch (via web: true) | | http_request | Raw HTTP request (via http: true) | | tavily_search | Tavily AI search | | tavily_extract | Tavily web extraction | | youtube_info | YouTube video metadata | | youtube_transcript | YouTube video transcript | | wikipedia_search | Wikipedia search | | wikipedia_summary | Wikipedia summary | | wikipedia_article | Full Wikipedia article |

Time

| Tool | Description | | -------------- | ------------------------- | | current_time | ISO, unix, and local time |

VCS

| Tool | Description | | ------------ | ---------------------------------------- | | git_status | Working tree status | | git_diff | Diff staged / unstaged changes | | git_log | Commit history | | git_branch | List branches | | git_show | Show a commit or object | | git_commit | Create a commit (allowWrite: true) | | git_stash | Stash / pop changes (allowWrite: true) |

Agent state — tasks

| Tool | Description | | -------------- | ------------------------------------------ | | task_write | Create or update a task | | task_list | List tasks with filters | | task_get | Get one task by ID | | task_summary | Counts by status, progress %, next actions | | task_delete | Delete a task (allowDelete: true) |

Agent state — artifacts

| Tool | Description | | ----------------- | ---------------------------------------- | | artifact_write | Write an artifact | | artifact_get | Get an artifact by key | | artifact_list | List artifacts | | artifact_search | Search artifact content | | artifact_delete | Delete an artifact (allowDelete: true) |

Data

| Tool | Description | | ------------------- | ------------------------------- | | json_parse | Parse a JSON string | | calculate | Evaluate a math expression | | regex_match | Match / extract with a regex | | csv_parse | Parse CSV text or file | | csv_query | SQL-style query over CSV | | csv_stats | Column statistics | | csv_convert | Convert CSV ↔ JSON | | sql_query | Execute a SQL query (SQLite) | | sql_schema | Inspect table schema | | sql_tables | List tables in a database | | pdf_info | PDF metadata (pages, author, …) | | pdf_to_text | Extract text from a PDF | | image_metadata | Image dimensions, format, EXIF | | image_to_base64 | Encode image to base64 | | image_from_base64 | Decode base64 to image file |

System / OS

| Tool | Description | | ------------------------ | --------------------------------------- | | archive_gzip | Gzip a file | | archive_gunzip | Gunzip a file | | archive_zip | Create a zip archive | | archive_unzip | Extract a zip archive | | archive_list | List zip / tar contents | | archive_tar | Create a tar archive | | crypto_hash | Hash data (SHA-256, MD5, …) | | crypto_hmac | Compute HMAC | | crypto_uuid | Generate a UUID v4 | | crypto_random | Generate random bytes / string | | crypto_encrypt | AES-GCM encrypt | | crypto_decrypt | AES-GCM decrypt | | crypto_base64 | Base64 encode / decode | | docker_ps | List containers | | docker_run | Run a container | | docker_exec | Exec inside a container | | docker_logs | Fetch container logs | | docker_images | List images | | docker_stop | Stop a container | | system_info | OS, CPU, memory, Node version | | get_env | Read an environment variable | | which | Locate a binary on PATH | | validate | Validate email / URL / UUID / Luhn | | validate_json_schema | Validate data against JSON Schema | | scheduler_wait | Wait for a duration | | scheduler_cron_next | Next N occurrences of a cron expression | | scheduler_cron_explain | Human-readable cron description |

OctoFlow platform

| Tool | Description | | ----------------- | -------------------------------- | | typecheck | Run TypeScript type-check | | lint | Run ESLint | | run_tests | Run test suite | | npm_install | Install npm packages | | read_config | Read OctoFlow config file | | resolve_config | Resolve merged config | | validate_config | Validate a config file | | list_backends | List available LLM backends | | check_cli_tools | Check required CLI tool versions |

Brain (cognitive memory)

| Tool | Description | | ----------------------------- | ----------------------------------- | | brain_remember | Persist a semantic memory | | brain_recall | Retrieve relevant memories | | brain_digest | Summarise and compress memories | | brain_consolidate | Merge duplicate memories | | brain_prune | Remove stale memories | | brain_replay | Replay memory context into a prompt | | brain_feedback | Attach feedback signal to a memory | | brain_audit | Audit memory store health | | brain_resolve_contradiction | Resolve conflicting memories |

KV memory (createMemoryTools())

| Tool | Description | | --------------- | ----------------------------- | | memory_get | Read a key from the KV store | | memory_set | Write a value to the KV store | | memory_delete | Delete a key | | memory_list | List keys by prefix | | memory_has | Check if a key exists |

Communication

| Tool | Description | | -------------------- | -------------------------------------- | | topic_publish | Publish a message to a topic | | topic_publish_wait | Publish and wait for reply | | topic_replay | Replay topic history | | mesh_send | Send a direct message to another agent | | mesh_broadcast | Broadcast to all mesh peers | | mesh_request | Request–response to a peer | | mesh_inbox | Read this agent's inbox | | mesh_reply | Reply to a mesh request | | mesh_multicast | Send to a subset of peers | | mesh_discover | Discover mesh peers | | mesh_list | List known mesh agents |

Subagent

| Tool | Description | | ------ | --------------------------------------------------- | | task | Delegate work to a subagent (via subagentTools()) |

Presets

| Preset | Best for | Included by default | | ----------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------- | | tools(config) | Primary builder — exactly what you specify | Nothing unless you pass it | | allTools(config) | Minimal default surface | filesystem, bash, fetch | | devTools(config) | Local development | filesystem, bash, git+write, artifacts+delete, tasks+delete, codeAnalysis, config, llmStatus | | readOnlyTools(config) | Research, sandboxed sessions | allTools defaults filtered to 'read'-tagged tools only | | agenticTools(config) | Planning, handoffs | json, text, datetime, llmStatus, config, artifacts, tasks | | utilityTools(config) | Local helpers | math, json, text, datetime | | dataTools(config) | Basic structured data | csv, json, math, validation | | webTools(config) | Web basics | fetch, webSearch |

All presets accept the same ToolsConfig — any key overrides the preset default. Niche/heavy groups such as Docker, SQL, archive, crypto, image/PDF, raw HTTP, Tavily, YouTube, and Wikipedia are explicit opt-ins.

devTools({ sql: { requireApproval: true } }); // opt into SQL
devTools({ bash: false }); // remove bash from dev preset
webTools({ tavily: true, wikipedia: true }); // opt into specialty web tools
allTools({ tasks: true, json: true }); // add groups to the lean preset

Quick start

import { createAgent } from 'octoflow-core';
import { tools, allTools, devTools } from 'octoflow-tools';

// Lean default preset
const agent = await createAgent({
  actions: allTools({ cwd: process.cwd() }),
});

// Custom — exactly the groups you need
const custom = await createAgent({
  actions: tools({
    cwd: process.cwd(),
    filesystem: true,
    bash: true,
    fetch: true,
    webSearch: true,
    git: { allowWrite: true },
    tasks: true,
    sql: { requireApproval: true },
    csv: true,
    json: true,
  }),
});

// Full developer session
const devAgent = await createAgent({
  actions: devTools({ cwd: process.cwd() }),
});

Individual factories

Every group in ToolsConfig maps to a factory you can also call directly:

| Factory | Group key | Write? | | --------------------------------------------------------- | ----------------- | ------ | | createFileActions(opts) + createFilesystemTools(opts) | filesystem | Yes | | createBashTool(opts) | bash | Yes | | createFetchTool(opts) | fetch | No | | createWebSearchTools(opts) | webSearch | No | | createDateTimeTools() | datetime | No | | createGitTools(opts) | git | Opt-in | | createTaskManagementTools(opts) | tasks | Yes | | createArtifactTools(opts) | artifacts | Yes | | createJsonTools() | json | No | | createMathTools() | math | No | | createTextTools() | text | No | | createCsvTools(opts) | csv | No | | createSqlTools(opts) | sql | Yes | | createPdfTools(opts) | pdf | No | | createImageTools(opts) | image | Yes | | createArchiveTools(opts) | archive | Yes | | createCryptoTools() | crypto | No | | createDockerTools(opts) | docker | Yes | | createEnvironmentTools() | environment | No | | createValidationTools() | validation | No | | createSchedulerTools() | scheduler | No | | createTavilyTools(opts) | tavily | No | | createYouTubeTools(opts) | youtube | No | | createWikipediaTools(opts) | wikipedia | No | | createWebTools(opts) | web | No | | createHttpTools(opts) | http | Opt-in | | createCodeAnalysisTools(opts) | codeAnalysis | No | | createConfigTools(opts) | config | No | | createLlmStatusTools() | llmStatus | No | | createBrainTools() | brain | Yes | | createMemoryTools() | — (call directly) | Yes | | createCommunicationTools(opts) | communication | Yes | | subagentTools(opts) | — (call directly) | Yes |

Safe-path guards

filesystem, csv, image, pdf, and archive all accept basePath — every path argument is validated against it, blocking ../ traversal.

Safe web / HTTP

fetch, web, and http validate redirect chains and DNS-resolve hostnames before connecting, blocking SSRF to private / loopback addresses.

Other exports

• artifactStorePlugin() — shared artifact persistence plugin for a bridge
• ArtifactStore, TaskStore — durable stores and test harnesses
• createWebIdentity(), getDefaultWebIdentity() — shared HTTP User-Agent identity
• defineAction, ActionDefinition, ActionContext — re-exported from octoflow-core

Learn more

• ../../docs/tools.md — tools / MCP / skills / plugins overview
• ../../docs/tools.md — user-facing tools, MCP, skills, plugins, and events guide
• ../octoflow-examples/src/tools — runnable examples

Validate

npm run -w octoflow-tools lint
npm run -w octoflow-tools typecheck
npm run -w octoflow-tools test

Status

Preview. Pin versions and read ../../CHANGELOG.md before depending on it in production.