thoughtflow

TypeScript framework for building autonomous AI agents — streaming, tool-calling, plugins, skills, workspace automation, and advanced orchestration.

import { Conversation, OpenAiAdapter } from "thoughtflow";

const agent = new Conversation({
  llmAdapter: new OpenAiAdapter({ apiKey: process.env.OPENAI_API_KEY }),
  model: "gpt-4o",
  systemPrompt: "You are a helpful agent with tools.",
});

const { output } = await agent.sendPrompt("What files are in the project?");
console.log(output);

Features

• Conversation loop — multi-turn agent with streaming, tool-calling, and interrupt support
• Adapter system — OpenAI, Anthropic, Ollama, vLLM, and mock adapters via AdapterFactory
• 120+ built-in tools — file read/write, search, git, browser, docker, code analysis, refactoring, testing, planning, memory, and more
• Context window management — sliding-window and truncation strategies to stay within model limits
• Subagent orchestration — spawn child agents with isolated context, tools, and state
• Plugins — workspace, docker, browser, codebase intelligence
• Skills — loadable .md instructions that inject context and constraints
• Storage abstraction — in-memory, JSON file, LanceDB vector store, Ollama/Transformers embeddings
• Event bus — RxJS-based streaming events for real-time UI or logging
• Task flow engine — multi-stage pipelines with git commit/push, docker, and phase gates
• MCP support — Model Context Protocol server with smart compressed tool list, tool_search for on-demand schema discovery, multi-provider routing, and vision browser

Quickstart

Installation

npm install thoughtflow
# or
bun add thoughtflow

Basic usage

import { Conversation, OpenAiAdapter, AdapterFactory } from "thoughtflow";

// Option A: direct adapter
const agent = new Conversation({
  llmAdapter: new OpenAiAdapter({ apiKey: "sk-..." }),
  model: "gpt-4o",
});

// Option B: factory with provider
const adapter = AdapterFactory.create({
  provider: "openai",
  baseUrl: "https://api.openai.com/v1",
  apiKey: "sk-...",
});

// Multi-turn conversation
await agent.sendPrompt("List the files in src/");
const history = agent.getHistory(); // full message history

// With tools
import { ReadFileTool, GrepTool } from "thoughtflow";

const agent = new Conversation({
  llmAdapter: adapter,
  model: "gpt-4o",
  tools: [
    new ReadFileTool("/path/to/project"),
    new GrepTool("/path/to/project"),
  ],
});

Streaming events

import { filter } from "rxjs";

agent.events.pipe(
  filter((e) => e.type === "stream:chunk"),
).subscribe((chunk) => {
  process.stdout.write(chunk.delta.content ?? "");
});

Subagent delegation

import { SubagentConversationTool } from "thoughtflow";

const agent = new Conversation({
  llmAdapter: adapter,
  model: "gpt-4o",
  tools: [new SubagentConversationTool()],
});

await agent.sendPrompt(
  "Research the best Node.js testing frameworks, then summarize."
);

Architecture

thoughtflow/
├── packages/mcp-server/  # @thoughtflow/mcp-server — thin npm wrapper
├── src/
│   ├── adapters/llm/     # LLM provider adapters (OpenAI, Anthropic, Ollama, mock)
│   ├── bin/              # CLI entry point (mcp-server)
│   ├── contracts/        # TypeScript interfaces and types
│   ├── contexts/         # Context document management & routing
│   ├── libs/
│   │   ├── mcp/          # MCP protocol: JSON-RPC, server, tool registry
│   │   └── ...           # Core libraries (runner, history, subagents, task flow)
│   ├── plugins/          # Workspace, Docker, Browser, Codebase Intelligence
│   ├── skills/           # Skill loader + built-in .md skill definitions
│   ├── storage/          # Persistence adapters (memory, JSON, vector stores)
│   ├── tools/
│   │   ├── mcp/          #   tool_search — on-demand tool discovery
│   │   ├── workspace/    #   file, git, browser, docker, terminal, vision browser
│   │   ├── codebase/     #   search, graph, impact, knowledge, crossref
│   │   ├── planning/     #   breakdown, deps, estimate, risks, progress
│   │   ├── quality/      #   complexity, coupling, coverage, duplication
│   │   ├── refactor/     #   rename, extract, split, move, imports
│   │   ├── testing/      #   gen-unit, gen-integration, fuzz, snapshot, fix
│   │   ├── docs/         #   gen-readme, gen-api, gen-adr, check-links
│   │   ├── neural/       #   review, debug, explain, optimize, security
│   │   ├── memory/       #   save, recall, context, patterns, lessons
│   │   ├── database/     #   migration, diagram, index-suggest
│   │   └── devops/       #   ci-diagnose, deploy-check, docker-optimize
│   └── quick/            # Preset configs for common setups
└── tests/                # 56 unit tests (MCP protocol, JSON-RPC, tool registry)

LLM Providers

| Provider | Adapter | baseUrl example | |----------|---------|-----------------| | OpenAI-compatible | OpenAiAdapter | https://api.openai.com/v1 | | Anthropic | AnthropicAdapter | — | | Ollama | OllamaAdapter | http://localhost:11434 | | Mock | MockAdapter | — (testing) |

const adapter = AdapterFactory.create({
  provider: "ollama",
  baseUrl: "http://localhost:11434",
});
// Adapter appends /v1/chat internally

MCP Server — Autonomous Agent via Model Context Protocol

Run thoughtflow as an MCP server that any MCP-compatible client can drive. Claude Desktop, Cursor, OpenCode, Continue, Zed — any client that speaks JSON-RPC over stdio becomes a fully autonomous coding agent with 100+ battle-tested tools.

Why thoughtflow MCP?

| Problem | thoughtflow solution | |---|---| | Context window pollution — 100+ tools with full JSON schemas consume 50K+ tokens upfront | Smart compressed mode — tools list shows names + one-liners only. LLM calls tool_search("analyze codebase") to pull full schemas on demand. Default: saves ~80% tokens. | | Static tool list — LLM can't discover the right tool among dozens of similar names | tool_search — describe what you want to do in natural language. Returns matching tools with full parameter schemas. Domain-aware: "testing tools", "workspace tools". | | One model for everything — vision doesn't work on your text model | Per-provider routing — route visionBrowser to GPT-4V, planning tools to Claude, code tools to your local Qwen. Mix and match. | | Setup complexity — config files, env vars, provider wiring | Single config file — thoughtflow.config.json. Providers, tool filtering, model routing, workspace paths — all in one place. |

Quickstart — one command

npx @thoughtflow/mcp-server

That's it. The server auto-detects thoughtflow.config.json in the current directory. No config file? Starts with sensible defaults (Ollama on localhost).

Custom config:

npx @thoughtflow/mcp-server --config ./my-config.json
# or
THOUGHTFLOW_CONFIG=/path/to/config.json npx @thoughtflow/mcp-server

Minimal thoughtflow.config.json:

{
  "workspace": { "allowedPaths": ["."] },
  "providers": {
    "default": {
      "type": "ollama",
      "baseUrl": "http://localhost:11434",
      "model": "qwen3"
    }
  }
}

Wire into your MCP client:

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "thoughtflow": {
      "command": "npx",
      "args": ["-y", "@thoughtflow/mcp-server", "--config", "/Users/you/project/thoughtflow.config.json"]
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "thoughtflow": {
      "command": "npx",
      "args": ["-y", "@thoughtflow/mcp-server", "--config", "/absolute/path/to/thoughtflow.config.json"]
    }
  }
}

Zed (settings.json):

{
  "context_servers": {
    "thoughtflow": {
      "command": {
        "path": "npx",
        "args": ["-y", "@thoughtflow/mcp-server", "--config", "/absolute/path/to/thoughtflow.config.json"]
      }
    }
  }
}

Your LLM now has filesystem access, git, search, code analysis, refactoring, testing — 100+ tools, zero setup beyond the config file. No API keys, no path wrangling, no dependency hell.

The tool_search advantage

In compressed mode (default), the LLM receives this instead of 50K tokens of JSON schemas:

## Tool Discovery — USE THIS FIRST

The tool list is COMPRESSED. Use `tool_search` before calling unfamiliar tools.

Available domains:
- workspace: File I/O, terminal, git, search, browser, HTTP
- codebase: Repository intelligence — index, search, graphs, impact
- neural: LLM-powered analysis — review, explain, debug, security
- planning: Problem decomposition, project management, estimation
...

When the LLM needs to read a file:

LLM: tool_search("read a text file")
     → readFile: path (string, required), offset (number, optional)...
LLM: readFile({ path: "src/app.ts" })

Every interaction costs fewer tokens. The LLM discovers tools exactly when needed — like lazy-loading for function schemas.

Vision browser — visual page analysis

{
  "tools": {
    "visionBrowser": {
      "enabled": true,
      "provider": "custom",
      "baseUrl": "https://integrate.api.nvidia.com/v1",
      "apiKey": "***",
      "model": "nemotron-mini-3-omni"
    }
  }
}

Now the LLM can visually inspect rendered web pages:

LLM: visionBrowser({ url: "https://example.com", prompt: "Is the login form centered? What color is the submit button?" })

Works with any OpenAI-compatible vision endpoint — GPT-4V, Claude 3, Gemini, Nemotron, local Ollama with vision models.

Advanced configuration

{
  "agent": {
    "toolListMode": "compressed",
    "maxIterations": 50
  },
  "categories": {
    "workspace": { "enabled": true },
    "database": { "enabled": false }
  },
  "tools": {
    "visionBrowser": { "enabled": true, "provider": "custom", "model": "gpt-4o" },
    "browser": { "enabled": false }
  },
  "modelRouting": {
    "vision": { "provider": "openai", "model": "gpt-4o" },
    "planning": { "provider": "claude", "model": "claude-sonnet-4" },
    "default": { "provider": "ollama", "model": "qwen3" }
  },
  "providers": {
    "ollama": { "type": "ollama", "baseUrl": "http://localhost:11434", "model": "qwen3" },
    "openai": { "type": "openai", "baseUrl": "https://api.openai.com/v1", "apiKey": "***" },
    "claude": { "type": "anthropic", "baseUrl": "https://api.anthropic.com", "apiKey": "***" }
  }
}

| Config key | What it does | |---|---| | agent.toolListMode | "compressed" (default, saves tokens) or "full" (all schemas upfront) | | categories.*.enabled | Toggle entire tool categories on/off | | tools.*.enabled | Toggle individual tools | | modelRouting | Route specific tools/categories to different LLM providers | | tools.visionBrowser | Enable visual page analysis with any vision-capable model | | workspace.allowedPaths | Filesystem sandbox — which directories the LLM can touch |

Protocol

Standard MCP over stdio — JSON-RPC 2.0, newline-delimited:

→ {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}
← {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},...}}

→ {"jsonrpc":"2.0","id":2,"method":"tools/list"}
← {"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"tool_search",...},{"name":"readFile",...},...]}}

→ {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"readFile","arguments":{"path":"src/app.ts"}}}
← {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"..."}]}}

Testing

thoughtflow includes a MockAdapter — zero network calls, deterministic responses:

import { McpServer, MockAdapter } from "thoughtflow";

const server = new McpServer({
  thoughtflowConfig: { workspace: { allowedPaths: ["."] } },
  adapters: new Map([["mock", { adapter: new MockAdapter(), model: "mock", baseUrl: "" }]]),
  defaultProvider: "mock",
});
await server.initialize();

const response = await server.handleRequest({
  jsonrpc: "2.0", id: 1, method: "tools/list",
});

Hermes Agent skill

Install the thoughtflow skill for Hermes — one command:

npx @thoughtflow/mcp-server install-skill

This copies the skill to ~/.hermes/skills/thoughtflow-mcp/. Custom target:

npx @thoughtflow/mcp-server install-skill --target ~/.agents/skills/

The skill auto-activates when mcp__thoughtflow__* tools are detected and teaches the LLM:

• Task-based tool selection ("find X" → grep, "review" → neuralReview, etc.)
• Mandatory workflows (pre-change impact check, pre-commit quality gate, visual testing flow)
• Safety rules (no destructive ops without backup + user approval)
• Planning pattern (solveComplex → TODO list)

License

MIT — see LICENSE.

Built with TypeScript. Requires Node.js ≥18 or Bun ≥1.2.