@cagataycali/strands-tools

TypeScript/browser tools + React hooks for Strands Agents. Ship agent UIs fast.

The TS/browser counterpart of my strands-agents/tools Python package: 30+ drop-in tools and a full useAgent / useAgents hook set so you can build agent-powered chat UIs in minutes instead of weeks.

Install

npm install @cagataycali/strands-tools @strands-agents/sdk zod
# for React hooks:
npm install react idb-keyval

What you get

🧰 30+ tools

Agent self-management

• manage_messages — trim/compact/drop/stats your own context window
• manage_tools — enable/disable/list/disable_group tools at runtime
• self-modify — agent can create_tool, update_self_prompt, add_context

Coordination

• mesh — BroadcastChannel cross-tab agent coordination (invoke/broadcast/ring)
• multi-agent — spawn/kill/invoke/broadcast to sibling agents in-tab
• npm — load ANY npm package via esm.sh from the browser, fallback to WebContainer for Node-only packages

Browser-native superpowers

• dom — query/mutate/observe the agent's own page
• webcontainer — full Node.js runtime in the browser (npm install, dev servers)
• webgpu — WGSL compute shaders + image kernels + benchmark
• network-intercept — log/block/mock/delay/modify fetch + XHR + WebSocket
• offscreen-canvas — render graphics off the main thread (charts, badges, sprite sheets)
• file-system — real local disk (File System Access API)
• virtual-cursor — visible agent-controlled cursor overlay for demos

Media & ML

• transformers-js — on-device ML (Whisper, SpeechT5, Moondream, DINOv3, MiniLM, Florence-2, 1200+ models)
• vision — screenshot + camera + image analysis
• streaming-media — camera/mic/screen → Transformers.js with UI overlay
• audio — speech synthesis + recognition
• openai-image — DALL-E / gpt-image-1
• qr — generate + scan QR codes

Persistence & knowledge

• memory — IndexedDB key-value memory
• knowledge-graph — graphology-backed entity/relation graph with BFS, Dijkstra, Louvain communities
• gallery — save/recall rendered UI panels

Research

• github — GraphQL v4 against the GitHub API (repos, issues, PRs, search, everything)
• time-tools — word count, timestamps, search-replace, UI config

System

• scheduler — recurring + one-time tasks, persisted to IDB, rehydrates on boot
• notification — native Notification API
• geolocation — browser geolocation
• telegram — Telegram bot messaging
• clipboard — read/write clipboard
• panel — open/close UI panels declaratively
• core — render_ui, javascript_eval, storage_*, fetch_url

🪝 React hooks

• useAgent — the core: one Agent instance, IDB persistence per thread, streaming, cancellation, auto self-heal on context overflow, message mgmt, event-bus integration, metrics, regenerate
• useAgents — multi-agent registry for spawning sibling agents in the same tab
• useMesh — reactive peer list + ring context via BroadcastChannel
• useEventBus — subscribe to the unified event stream (task/scheduler/telegram/webhook/tool/ambient/mesh/error)
• useThreads — multi-conversation persistence with rename/pin/delete
• useUserActivity — typing/mouse/scroll/idle/battery/network/orientation/visibility tracking for dynamic context
• useBookmarks — persistent message bookmarks
• useAmbient — autonomous idle-time agent loop with [AMBIENT_DONE] signal
• useTaskListener — listen for scheduled task fires
• useVoiceCommand — continuous SpeechRecognition with trigger phrases
• useKeyboardShortcuts — declarative keybind registration
• useTheme — dark/light with data-theme sync
• useSettings — localStorage + cross-tab sync
• useWebRTC — peer-to-peer data channels with heartbeat + backoff reconnect

📚 Helper libraries (/lib)

• buildSystemPrompt — dynamic, context-rich system prompts with tool hints
• toDisplayMessages / serializeMessages — SDK ↔ UI message conversion
• estimateTotalTokens / shouldSummarize — rolling-summary heuristics
• mesh / MeshImpl — cross-tab coordination singleton
• turn-log — 200-turn continuous memory ring buffer
• event-bus — unified agent activity stream with sessionStorage persistence
• cost-estimator — USD + context window per provider+model
• webrtc-mesh — RTCPeerConnection-based peer mesh with signaling via BC
• agent-registry — in-memory multi-agent registry

🔌 Model providers (/providers)

Lazy-loaded factory for: Anthropic, OpenAI, Google Gemini, AWS Bedrock, Vercel AI SDK (with 20+ providers).

Usage

Minimum viable chat UI

import { useAgent } from '@cagataycali/strands-tools/hooks'
import { GITHUB_TOOLS, MEMORY_TOOLS } from '@cagataycali/strands-tools/tools'

function Chat({ settings }) {
  const agent = useAgent(settings, 'my-thread', [
    ...GITHUB_TOOLS,
    ...MEMORY_TOOLS,
  ])

  return (
    <div>
      {agent.getMessages().map((m, i) => <div key={i}>{m.role}: {m.content}</div>)}
      <input onKeyDown={e => {
        if (e.key === 'Enter') {
          agent.send(e.currentTarget.value)
          e.currentTarget.value = ''
        }
      }} />
    </div>
  )
}

Everything at once

import { useAgent, useAgents, useMesh, useThreads } from '@cagataycali/strands-tools/hooks'
import { buildTools, TOOL_GROUPS } from '@cagataycali/strands-tools/tools'

const tools = buildTools(settings) // respects settings.enableTools etc.
const agent = useAgent(settings, threads.storageKey, tools)
const siblings = useAgents(settings)
const { peers, ring } = useMesh()

Granular imports (tree-shaking friendly)

import { githubSearchReposTool, githubGetRepoTool } from '@cagataycali/strands-tools/tools/github'
import { useAgent } from '@cagataycali/strands-tools/hooks/useAgent'
import { buildSystemPrompt } from '@cagataycali/strands-tools/lib/system-prompt'

Philosophy

• Two paths, unified. Some tools run browser-native (lodash, date-fns, zod). Some need Node (sharp, sqlite3, express). The npm tool auto-routes.
• Agent self-management is first-class. manage_messages, manage_tools, and self-modify let the agent prune its own context, load capabilities at runtime, and evolve its system prompt.
• Multi-agent by design. useAgents + mesh + multi-agent tools = one tab can host many coordinating agents, each with its own history.
• Tree-shake aggressively. Every tool and hook is a leaf import. Use only what you need.
• Browser-native. No backend required. Runs on GitHub Pages, Vercel, anywhere that serves static files.

Architecture

useAgent owns the SDK's Agent instance. The SDK's agent.messages IS the conversation state — no duplicate React state to keep in sync. agent.stream() handles everything: user msg append, model call, tool execution, assistant msg append, cancellation via AbortSignal.

Per-thread persistence to IndexedDB (careless-thread-{id}). Auto-heals context overflow by dropping older half (preserving toolUse ↔ toolResult pairs) and retrying once. Proactive warn when >80% of context window via shouldSummarize.

Compatibility

• Modern browsers only (Chrome/Edge 113+, Safari 18+, Firefox with dom.webgpu.enabled)
• React 18+ for hooks
• Strands Agents SDK 1.x
• Zod 4.x

Status

🚧 v0.1.0 scaffold — extracted from the careless codebase. Stable API but will churn as the external surface solidifies. Pin exact versions until 1.0.

License

MIT © Çağatay Çalı